Model Reference

Model - Cubes meta-data objects and functionality for working with them. Logical Model and Metadata

Note

All model objects: Cube, Dimension, Hierarchy, Level and attribute objects should be considered immutable once created. Any changes to the object attributes might result in unexpected behavior.

See also

Model Providers Reference

Model providers – objects for constructing model objects from other kinds of sources, even during run-time.

Creating model objects from metadata

Following methods are used to create model objects from a metadata dicitonary.

cubes.create_cube(metadata)

Create a cube object from metadata dictionary. The cube has no dimensions attached after creation. You should link the dimensions to the cube according to the Cube.linked_dimensions property using Cube.add_dimension()

cubes.create_dimension(metadata, dimensions=None, name=None)

Create a dimension from a metadata dictionary.

cubes.create_level(metadata, name=None, dimension=None)

Create a level object from metadata. name can override level name in the metadata.

cubes.create_attribute(obj, class_=None)

Makes sure that the obj is an Attribute instance. If obj is a string, then new instance is returned. If it is a dictionary, then the dictionary values are used for Attribute instance initialization.

cubes.create_measure(md)

Create a measure object from metadata.

cubes.create_measure_aggregate(md)

cubes.attribute_list(attributes, class_=None)

Create a list of attributes from a list of strings or dictionaries. see cubes.coalesce_attribute() for more information.

Model components

Note

The Model class is no longer publicly available and should not be used. For more information, please see cubes.Workspace.

Cube

class cubes.Cube(name, dimensions=None, measures=None, aggregates=None, label=None, details=None, mappings=None, joins=None, fact=None, key=None, description=None, browser_options=None, info=None, linked_dimensions=None, locale=None, category=None, datastore=None, hierarchies=None, **options)

Create a new Cube model object.

Properties:

• name: cube name, used as identifier
• measures: list of measures – numerical attributes aggregation functions or natively aggregated values
• label: human readable cube label
• details: list of detail attributes
• description - human readable description of the cube
• key: fact key field (if not specified, then backend default key will be used, mostly id for SLQ or _id for document based databases)
• info - custom information dictionary, might be used to store application/front-end specific information
• locale: cube’s locale
• linked_dimensions – dimensions to be linked after the cube is created
• hierarchies – a dictionary of relevant dimension hierarchies for this cube. Keys are dimension names, values are hierarchy names. If a dimension is not in this dictionary, then all hierarchies are used.

There are two ways how to assign dimensions to the cube: specify them during cube initialization in dimensions by providing a list of Dimension objects. Alternatively you can set linked_dimensions list with dimension names and the link the dimension using cubes.Cube.add_dimension().

Physical properties of the cube are described in the following attributes. They are used by the backends:

• mappings - backend-specific logical to physical mapping dictionary. Keys and values of this dictionary are interpreted by the backend.
• joins - backend-specific join specification (used for example in the SQL backend). It should be a list of dictionaries.
• fact - fact table (collection, dataset, ...) name
• datastore - name of datastore where the cube belongs
• browser_options - dictionary of other options used by the backend - refer to the backend documentation to see what options are used (for example SQL browser might look here for denormalized_view in case of denormalized browsing)

add_dimension(dimension)

Add dimension to cube. Replace dimension with same name. Raises ModelInconsistencyError when dimension with same name already exists in the receiver.

aggregates_for_measure(name)

Returns aggregtates for measure with name. Only direct function aggregates are returned. If the measure is specified in an expression, the aggregate is not included in the returned list

all_aggregate_attributes None

All cube’s attributes for aggregation: attributes of dimensions and aggregates.

all_attributes None

All cube’s attributes from the fact: attributes of dimensions, details and measures.

attribute(attribute)

Returns an attribute object (dimension attribute, measure or detail).

dimension(obj)

Get dimension object. If obj is a string, then dimension with given name is returned, otherwise dimension object is returned if it belongs to the cube.

Raises NoSuchDimensionError when there is no such dimension.

get_aggregates(names)

Get a list of aggregates with names

get_attributes(attributes=None, simplify=True, aggregated=False)

Returns a list of cube’s attributes. If aggregated is True then attributes after aggregation are returned, otherwise attributes for a fact are considered.

Aggregated attributes contain: dimension attributes and aggregates. Fact attributes contain: dimension attributes, fact details and fact measures.

If the list attributes is empty, all attributes are returned.

If simplified_references is True then dimension attribute references in attrubutes are considered simplified, otherwise they are considered as full (dim.attribute).

get_measures(measures)

Get a list of measures as Attribute objects. If measures is None then all cube’s measures are returned.

measure(name)

Get measure object. If obj is a string, then measure with given name is returned, otherwise measure object is returned if it belongs to the cube. Returned object is of Attribute type.

Raises NoSuchAttributeError when there is no such measure or when there are multiple measures with the same name (which also means that the model is not valid).

measure_aggregate(name)

Returns a measure aggregate by name.

remove_dimension(dimension)

Remove a dimension from receiver. dimension can be either dimension name or dimension object.

to_dict(expand_dimensions=False, with_mappings=True, hierarchy_limits=None, **options)

Convert to a dictionary. If with_mappings is True (which is default) then joins, mappings, fact and options are included. Should be set to False when returning a dictionary that will be provided in an user interface or through server API.

validate()

Validate cube. See Model.validate() for more information.

Dimension, Hierarchy and Level

class cubes.Dimension(name, levels, hierarchies=None, default_hierarchy_name=None, label=None, description=None, info=None, role=None, cardinality=None, **desc)

Create a new dimension

Attributes:

• name: dimension name
• levels: list of dimension levels (see: cubes.Level)
• hierarchies: list of dimension hierarchies. If no hierarchies are specified, then default one is created from ordered list of levels.
• default_hierarchy_name: name of a hierarchy that will be used when no hierarchy is explicitly specified
• label: dimension name that will be displayed (human readable)
• description: human readable dimension description
• info - custom information dictionary, might be used to store application/front-end specific information (icon, color, ...)
• role – one of recognized special dimension types. Currently supported is only time.
• cardinality – cardinality of the dimension members. Used optionally by the backends for load protection and frontends for better auto-generated front-ends. See Level for more information, as this attribute is inherited by the levels, if not specified explicitly in the level.

Dimension class is not meant to be mutable. All level attributes will have new dimension assigned.

Note that the dimension will claim ownership of levels and their attributes. You should make sure that you pass a copy of levels if you are cloning another dimension.

all_attributes None

Return all dimension attributes regardless of hierarchy. Order is not guaranteed, use cubes.Hierarchy.all_attributes() to get known order. Order of attributes within level is preserved.

attribute(reference, by_ref=False)

Get dimension attribute from reference.

has_details None

Returns True when each level has only one attribute, usually key.

hierarchy(obj=None)

Get hierarchy object either by name or as Hierarchy. If obj is None then default hierarchy is returned.

is_flat None

Is true if dimension has only one level

key_attributes()

Return all dimension key attributes, regardless of hierarchy. Order is not guaranteed, use a hierarchy to have known order.

level(obj)

Get level by name or as Level object. This method is used for coalescing value

level_names None

Get list of level names. Order is not guaranteed, use a hierarchy to have known order.

levels None

Get list of all dimension levels. Order is not guaranteed, use a hierarchy to have known order.

limited_clone(hierarchies)

Returns a shallow copy of the receiver and limit hierarchies only to those specified in hierarchies. If default hierarchy name is not in the new hierarchy list, then the first hierarchy from the list is used.

to_dict(hierarchy_limits=None, **options)

Return dictionary representation of the dimension

validate()

Validate dimension. See Model.validate() for more information.

class cubes.Hierarchy(name, levels, dimension=None, label=None, info=None)

Dimension hierarchy - specifies order of dimension levels.

Attributes:

• name: hierarchy name
• dimension: dimension the hierarchy belongs to
• label: human readable name
• levels: ordered list of levels or level names from dimension
• info - custom information dictionary, might be used to store application/front-end specific information

Some collection operations might be used, such as level in hierarchy or hierarchy[index]. String value str(hierarchy) gives the hierarchy name.

all_attributes None

Return all dimension attributes as a single list.

is_last(level)

Returns True if level is last level of the hierarchy.

key_attributes()

Return all dimension key attributes as a single list.

level_index(level)

Get order index of level. Can be used for ordering and comparing levels within hierarchy.

levels_for_depth(depth, drilldown=False)

Returns levels for given depth. If path is longer than hierarchy levels, cubes.ArgumentError exception is raised

levels_for_path(path, drilldown=False)

Returns levels for given path. If path is longer than hierarchy levels, cubes.ArgumentError exception is raised

next_level(level)

Returns next level in hierarchy after level. If level is last level, returns None. If level is None, then the first level is returned.

path_is_base(path)

Returns True if path is base path for the hierarchy. Base path is a path where there are no more levels to be added - no drill down possible.

previous_level(level)

Returns previous level in hierarchy after level. If level is first level or None, returns None

rollup(path, level=None)

Rolls-up the path to the level. If level is None then path is rolled-up only one level.

If level is deeper than last level of path the cubes.HierarchyError exception is raised. If level is the same as path level, nothing happens.

to_dict(depth=None, **options)

Convert to dictionary. Keys:

• name: hierarchy name
• label: human readable label (localizable)
• levels: level names

class cubes.Level(name, attributes, dimension=None, key=None, order_attribute=None, order=None, label_attribute=None, label=None, info=None, cardinality=None, role=None)

Object representing a hierarchy level. Holds all level attributes.

This object is immutable, except localization. You have to set up all attributes in the initialisation process.

Attributes:

• name: level name
• dimension: dimnesion the level is associated with
• attributes: list of all level attributes. Raises ModelError when attribute list is empty.
• key: name of level key attribute (for example: customer_number for customer level, region_code for region level, month for month level). key will be used as a grouping field for aggregations. Key should be unique within level. If not specified, then the first attribute is used as key.
• order: ordering of the level. asc for ascending, desc for descending or might be unspecified.
• order_attribute: name of attribute that is going to be used for sorting, default is first attribute (usually key)
• label_attribute: name of attribute containing label to be displayed (for example: customer_name for customer level, region_name for region level, month_name for month level)
• label: human readable label of the level
• role: role of the level within a special dimension
• info: custom information dictionary, might be used to store application/front-end specific information
• cardinality – approximation of the number of level’s members. Used optionally by backends and front ends.

Cardinality values:

• tiny – few values, each value can have it’s representation on the screen, recommended: up to 5.
• low – can be used in a list UI element, recommended 5 to 50 (if sorted)
• medium – UI element is a search/text field, recommended for more than 50 elements
• high – backends might refuse to yield results without explicit pagination or cut through this level.

attribute(name)

Get attribute by name

has_details None

Is True when level has more than one attribute, for all levels with only one attribute it is False.

to_dict(full_attribute_names=False, **options)

Convert to dictionary

Attributes, Measures and Aggregates

class cubes.AttributeBase(name, label=None, description=None, order=None, info=None, format=None, missing_value=None, **kwargs)

Base class for dimension attributes, measures and measure aggregates.

Attributes:

• name - attribute name, used as identifier
• label - attribute label displayed to a user
• order - default order of this attribute. If not specified, then order is unexpected. Possible values are: 'asc' or 'desc'. It is recommended and safe to use Attribute.ASC and Attribute.DESC
• info - custom information dictionary, might be used to store application/front-end specific information
• format - application-specific display format information, useful for formatting numeric values of measure attributes
• missing_value – value to be used when there is no value (NULL) in the data source. Support of this attribute property depends on the backend. Please consult the backend documentation for more information.

String representation of the AttributeBase returns its name.

cubes.ArgumentError is raised when unknown ordering type is specified.

class cubes.Attribute(name, label=None, description=None, order=None, info=None, format=None, dimension=None, locales=None, missing_value=None, **kwargs)

Dimension attribute object. Also used as fact detail.

Attributes:

• name - attribute name, used as identifier
• label - attribute label displayed to a user
• locales = list of locales that the attribute is localized to
• order - default order of this attribute. If not specified, then order is unexpected. Possible values are: 'asc' or 'desc'. It is recommended and safe to use Attribute.ASC and Attribute.DESC
• info - custom information dictionary, might be used to store application/front-end specific information
• format - application-specific display format information, useful for formatting numeric values of measure attributes

String representation of the Attribute returns its name (without dimension prefix).

cubes.ArgumentError is raised when unknown ordering type is specified.

ref(simplify=True, locale=None)

Return full attribute reference. Append locale if it is one of attribute’s locales, otherwise raise cubes.ArgumentError. If simplify is True, then reference to an attribute of flat dimension without details will be just the dimension name.

class cubes.Measure(name, label=None, description=None, order=None, info=None, format=None, missing_value=None, aggregates=None, formula=None, expression=None, **kwargs)

Fact measure attribute.

Properties:

• formula – name of a formula for the measure
• aggregates – list of default (relevant) aggregate functions that can be applied to this measure attribute.

Note that if the formula is specified, it should not refer to any other measure that refers to this one (no circular reference).

The aggregates is an optional property and is used for: * measure aggergate object preparation * optional validation

String representation of a Measure returns its name.

default_aggregates()

Creates default measure aggregates from a list of receiver’s measures. This is just a convenience function, correct models should contain explicit list of aggregates. If no aggregates are specified, then the only aggregate sum is assumed.

class cubes.MeasureAggregate(name, label=None, description=None, order=None, info=None, format=None, missing_value=None, measure=None, function=None, formula=None, expression=None, **kwargs)

Masure aggregate

Attributes:

• function – aggregation function for the measure
• formula – name of a formula that contains the arithemtic expression (optional)
• measure – measure name for this aggregate (optional)
• expression – arithmetic expression (only if bacend supported)

exception ModelError

Exception raised when there is an error with model and its structure, mostly during model construction.

exception ModelIncosistencyError

Raised when there is incosistency in model structure, mostly when model was created programatically in a wrong way by mismatching classes or misonfiguration.

exception NoSuchDimensionError

Raised when a dimension is requested that does not exist in the model.

exception NoSuchAttributeError

Raised when an unknown attribute, measure or detail requested.