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.dimension_links property using Cube.add_dimension()

cubes.create_dimension(metadata, templates=None)

Create a dimension from a metadata dictionary. Some rules:

• levels might contain level names as strings – names of levels to inherit from the template
• hierarchies might contain hierarchies as strings – names of hierarchies to inherit from the template
• all levels that are not covered by hierarchies are not included in the final dimension

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, dimension_links=None, locale=None, category=None, store=None, datastore=None, namespace=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
• dimension_links – dimensions to be linked after the cube is created

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 dimension_links 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
• store - name of data store 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)

The dimension links are either dimension names or dictionaries specifying how the dimension will be linked to the cube. The keys of the link dictionary are:

• name – name of the dimension to be linked
• hierarchies – list of hierarchy names to be kept from the dimension
• nonadditive – additivity of the linked dimension (overrides the dimension’s value)
• cardinality – cardinality of the linked dimension in the cube’s context (overrides the dimension’s value)
• default_hierarchy_name – which hierarchy will be used as default in the linked dimension

add_dimension(dimension)

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

aggregate(name)

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

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

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

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

all_attributes

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=None)

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.

link_dimensions(dimensions)

Links dimensions according to cube’s dimension_links. The dimensions should be a dictionary with keys as dimension names and values as Dimension instances.

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 Measure 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.

nonadditive_type(aggregate)

Returns non-additive type of aggregate‘s measure. If aggregate has no measure specified or is unknown (backend-specific) then None is returned.

remove_dimension(dimension)

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

to_dict(**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, category=None, master=None, nonadditive=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.
• category – logical dimension group (user-oriented metadata)
• nonadditive – kind of non-additivity of the dimension. Possible values: None (fully additive, default), time (non-additive for time dimensions) or all (non-additive for any other dimension)

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.

Note: The hierarchy will be owned by the dimension.

attribute(reference, by_ref=False)

Get dimension attribute from reference.

attributes

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.

clone(hierarchies=None, exclude_hierarchies=None, nonadditive=None, default_hierarchy_name=None, cardinality=None, alias=None, **extra)

Returns a clone of the receiver with some modifications. master of the clone is set to the receiver.

• hierarchies – 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.
• exclude_hierarchies – all hierarchies are preserved except the hierarchies in this list
• nonadditive – non-additive value for the dimension
• alias – name of the cloned dimension

has_details

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

hierarchies

Get list of dimension hierarchies.

hierarchy(obj=None)

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

is_flat

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

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

levels

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

to_dict(**options)

Return dictionary representation of the dimension

validate()

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

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

Dimension hierarchy - specifies order of dimension levels.

Attributes:

• name: hierarchy name
• levels: ordered list of levels or level names from dimension
• label: human readable name
• description: user description of the hierarchy
• 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.

Note: The levels should have attributes already owned by a dimension.

all_attributes

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, key=None, order_attribute=None, order=None, label_attribute=None, label=None, info=None, cardinality=None, role=None, nonadditive=None, description=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
• 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.
• nonadditive – kind of non-additivity of the level. Possible values: None (fully additive, default), time (non-additive for time dimensions) or all (non-additive for any other dimension)

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.

Note: the attributes are going to be owned by the dimension.

attribute(name)

Get attribute by name

has_details

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.

localize(trans)

Localize the attribute, allow localization of the format.

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, nonadditive=None, window_size=None, **kwargs)

Fact measure attribute.

Properties in addition to the attribute base properties:

• formula – name of a formula for the measure
• aggregates – list of default (relevant) aggregate functions that can be applied to this measure attribute.
• nonadditive – kind of non-additivity of the dimension. Possible values: none (fully additive, default), time (non-additive for time dimensions) or all (non-additive for any other dimension)

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, nonadditive=None, window_size=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)
• nonadditive – additive behavior for the aggregate (inherited from the measure in most of the times)

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.