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.
Model Utility Functions¶
-
cubes.
object_dict
(objects, by_ref=False, error_message=None, error_dict=None)¶ Make an ordered dictionary from model objects objects where keys are object names. If for_ref is True then object’s ref (reference) is used instead of object name. Keys are supposed to be unique in the list, otherwise an exception is raised.
-
cubes.
create_list_of
(class_, objects)¶ Return a list of model objects of class class_ from list of object metadata objects
-
cubes.
collect_attributes
(attributes, *containers)¶ Collect attributes from arguments. containers are objects with method all_attributes or might be Nulls. Returns a list of attributes. Note that the function does not check whether the attribute is an actual attribute object or a string.
-
cubes.
collect_dependencies
(attributes, all_attributes)¶ Collect all original and dependant cube attributes for attributes, sorted by their dependency: starting with attributes that don’t depend on anything. For exapmle, if the attributes is [a, b] and a = c * 2, then the result list would be [b, c, a] or [c, b, a].
This method is supposed to be used by backends that can handle attribute expressions. It is safe to generate a mapping between logical references and their physical object representations from expressions in the order of items in the returned list.
Returns a list of sorted attribute references.
-
cubes.
depsort_attributes
(attributes, all_dependencies)¶ Returns a sorted list of attributes by their dependencies. attributes is a list of attribute names, all_dependencies is a dictionary where keys are attribute names and values are direct attribute dependencies (that is attributes in attribute’s expression, for example). all_dependencies should contain all known attributes, variables and constants.
Raises an exception when a circular dependecy is detected.
Model components¶
-
class
cubes.
ModelObject
(name=None, label=None, description=None, info=None)¶ Initializes model object basics. Assures that the info is a dictionary.
-
localized
(context)¶ Returns a copy of the cube translated with translation
-
to_dict
(create_label=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 toFalse
when returning a dictionary that will be provided in an user interface or through server API.
-
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, **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.link_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
-
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: attributes of dimensions, details, measures and aggregates. Use this method if you need to prepare structures for any kind of query. For attributes for more specific types of queries refer to
Cube.all_fact_attributes()
andCube.all_aggregate_attributes()
.Changed in version 1.1: Returns all attributes, including aggregates. Original functionality is available as all_fact_attributes()
-
all_dimension_keys
¶ Returns all attributes that represent keys of dimensions and their levels..
-
all_fact_attributes
¶ All cube’s attributes from the fact: attributes of dimensions, details and measures.
New in version 1.1.
-
attribute
(attribute)¶ Returns an attribute object (dimension attribute, measure or detail).
-
attribute_dependencies
¶ Dictionary of dependencies between attributes. Values are references of attributes that the key attribute depends on. For example for attribute a which has expression b + c the dictionary would be: {“a”: [“b”, “c”]}. The result dictionary includes all cubes’ attributes and aggregates.
New in version 1.1.
-
base_attributes
¶ Returns a list of attributes that are not derived from other attributes, do not depend on other cube attributes, variables or parameters. Any attribute that has an expression (regardless of it’s contents, it might be a constant) is considered derived attribute.
The list contains also aggregate attributes that are base – for example attributes that represent pre-aggregated column in a table.
New in version 1.1.
-
collect_dependencies
(attributes)¶ Collect all original and dependant cube attributes for attributes, sorted by their dependency: starting with attributes that don’t depend on anything. For exapmle, if the attributes is [a, b] and a = c * 2, then the result list would be [b, c, a] or [c, b, a].
This method is supposed to be used by backends that can handle attribute expressions. It is safe to generate a mapping between logical references and their physical object representations from expressions in the order of items in the returned list.
New in version 1.1.
-
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.
-
distilled_hierarchies
¶ Returns a dictionary of hierarchies. Keys are hierarchy references and values are hierarchy level key attribute references.
Warning
This method might change in the future. Consider experimental.
-
classmethod
from_metadata
(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()
-
get_aggregates
(names=None)¶ Get a list of aggregates with names.
-
get_attributes
(attributes=None, 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_dimension
(dimension)¶ Links dimension object or a clone of it to the cube according to the specification of cube’s dimension link. See
Dimension.clone()
for more information about cloning a dimension.
-
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).
-
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 toFalse
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=None, hierarchies=None, default_hierarchy_name=None, label=None, description=None, info=None, role=None, cardinality=None, category=None, master=None, nonadditive=None, attributes=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) orall
(non-additive for any other dimension) - attributes – attributes for dimension. Use either this or levels, not both.
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
(name, by_ref=False)¶ Get dimension attribute. name is an attribute name (default) or attribute reference if by_ref is True.`.
-
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
-
classmethod
from_metadata
(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 templatehierarchies
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
-
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
orhierarchy[index]
. String valuestr(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.
-
keys
(depth=None)¶ Return names of keys for all levels in the hierarchy to depth. If depth is None then all levels are returned.
-
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 isNone
, 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
, returnsNone
-
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) orall
(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 elementshigh
– 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
-
classmethod
from_metadata
(metadata, name=None, dimension=None)¶ Create a level object from metadata. name can override level name in the metadata.
-
has_details
¶ Is
True
when level has more than one attribute, for all levels with only one attribute it isFalse
.
-
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, expression=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 useAttribute.ASC
andAttribute.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. - expression – arithmetic expression for computing this attribute from other existing attributes.
String representation of the AttributeBase returns its name.
cubes.ArgumentError is raised when unknown ordering type is specified.
-
dependencies
¶ Set of attributes that the attribute depends on. If the attribute is an expresion, then returns the direct dependencies from the expression. If the attribute is an aggregate with an unary function operating on a measure, then the measure is considered as a dependency. Attribute can’t have both expression and measure specified, since you can have only expression or an function, not both.
-
classmethod
from_metadata
(metadata)¶ Create an attribute from metadata which can be a dictionary or a string representing the attribute name.
-
localize
(trans)¶ Localize the attribute, allow localization of the format.
-
localized_ref
(locale)¶ Returns localized attribute reference for locale locale.
-
class
cubes.
Attribute
(name, label=None, description=None, order=None, info=None, format=None, dimension=None, locales=None, missing_value=None, expression=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 useAttribute.ASC
andAttribute.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.
Note: copied attributes are dis-owned from dimension. The new dimension has to be assigned after copying.
-
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)¶ Create a 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) orall
(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 full reference.
-
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 backend supported)
- nonadditive – additive behavior for the aggregate (inherited from the measure in most of the times)
-
dependencies
¶ Set of attributes that the attribute depends on. If the attribute is an expresion, then returns the direct dependencies from the expression. If the attribute is an aggregate with an unary function operating on a measure, then the measure is considered as a dependency. Attribute can’t have both expression and measure specified, since you can have only expression or an function, not both.
-
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.