Aggregation Browser Reference

Abstraction for aggregated browsing (concrete implementation is provided by one of the backends in package backend or a custom backend).

Browser package classes.

Aggregate browsing

class cubes.AggregationBrowser(cube)

Class for browsing data cube aggregations

Attributes :

• cube - cube for browsing

aggregate(cell=None, measures=None, drilldown=None, **options)

Return aggregate of a cell.

Subclasses of aggregation browser should implement this method.

Attributes :

• drilldown - dimensions and levels through which to drill-down, default None
• measures - list of measures to be aggregated. By default all measures are aggregated.

Drill down can be specified in two ways: as a list of dimensions or as a dictionary. If it is specified as list of dimensions, then cell is going to be drilled down on the next level of specified dimension. Say you have a cell for year 2010 and you want to drill down by months, then you specify drilldown = ["date"].

If drilldown is a dictionary, then key is dimension or dimension name and value is last level to be drilled-down by. If the cell is at year level and drill down is: { "date": "day" } then both month and day levels are added.

If there are no more levels to be drilled down, an exception is raised. Say your model has three levels of the date dimension: year, month, day and you try to drill down by date at the next level then ValueError will be raised.

Retruns a :class:AggregationResult object.

cell_details(cell=None, dimension=None)

Returns details for the cell. Returned object is a list with one element for each cell cut. If dimension is specified, then details only for cuts that use the dimension are returned.

Default implemenatation calls AggregationBrowser.cut_details() for each cut. Backends might customize this method to make it more efficient.

cut_details(cut)

Gets details for a cut which should be a Cut instance.

• PointCut - all attributes for each level in the path
• SetCut - list of PointCut results, one per path in the set
• RangeCut - PointCut-like results for lower range (from) and upper range (to)

fact(key)

Returns a single fact from cube specified by fact key key

facts(cell=None, **options)

Return an iterable object with of all facts within cell

features = []

List of browser features as strings.

report(cell, queries)

Bundle multiple requests from queries into a single one.

Keys of queries are custom names of queries which caller can later use to retrieve respective query result. Values are dictionaries specifying arguments of the particular query. Each query should contain at least one required value query which contains name of the query function: aggregate, facts, fact, values and cell cell (for cell details). Rest of values are function specific, please refer to the respective function documentation for more information.

Example:

queries = {
    "product_summary" = { "query": "aggregate",
                          "drilldown": "product" }
    "year_list" = { "query": "values",
                    "dimension": "date",
                    "depth": 1 }
}

Result is a dictionary where keys wil lbe the query names specified in report specification and values will be result values from each query call.:

result = browser.report(cell, queries)
product_summary = result["product_summary"]
year_list = result["year_list"]

This method provides convenient way to perform multiple common queries at once, for example you might want to have always on a page: total transaction count, total transaction amount, drill-down by year and drill-down by transaction type.

Raises cubes.ArgumentError when there are no queries specified or if a query is of unknown type.

Roll-up

Report queries might contain rollup specification which will result in “rolling-up” one or more dimensions to desired level. This functionality is provided for cases when you would like to report at higher level of aggregation than the cell you provided is in. It works in similar way as drill down in AggregationBrowser.aggregate() but in the opposite direction (it is like cd .. in a UNIX shell).

Example: You are reporting for year 2010, but you want to have a bar chart with all years. You specify rollup:

...
"rollup": "date",
...

Roll-up can be:

• a string - single dimension to be rolled up one level
• an array - list of dimension names to be rolled-up one level
• a dictionary where keys are dimension names and values are levels to be rolled up-to

Future

In the future there might be optimisations added to this method, therefore it will become faster than subsequent separate requests. Also when used with Slicer OLAP service server number of HTTP call overhead is reduced.

values(cell, dimension, depth=None, paths=None, hierarchy=None, **options)

Return values for dimension with level depth depth. If depth is None, all levels are returned.

Note

Some backends might support only default hierarchy.

Result

The result of aggregated browsing is returned as object:

class cubes.AggregationResult(cell=None, measures=None)

Result of aggregation or drill down.

Attributes:

• cell – cell that this result is aggregate of
• summary - dictionary of summary row fields
• cells - list of cells that were drilled-down
• total_cell_count - number of total cells in drill-down (after limit, before pagination)
• measures – measures that were selected in aggregation
• remainder - summary of remaining cells (not yet implemented)
• levels – aggregation levels for dimensions that were used to drill- down

Note

Implementors of aggregation browsers should populate cell, measures and levels from the aggregate query.

cached()

Return shallow copy of the receiver with cached cells. If cells are an iterator, they are all fetched in a list.

cross_table(onrows, oncolumns, measures=None)

Creates a cross table from result’s cells. onrows contains list of attribute names to be placed at rows and oncolumns contains list of attribute names to be placet at columns. measures is a list of measures to be put into cells. If measures are not specified, then only record_count is used.

Returns a named tuble with attributes:

• columns - labels of columns. The tuples correspond to values of attributes in oncolumns.
• rows - labels of rows as list of tuples. The tuples correspond to values of attributes in onrows.
• data - list of measure data per row. Each row is a list of measure tuples as specified in measures.

Warning

Experimental implementation. Interface might change - either arguments or result object.

has_dimension(dimension)

Returns True if the result was drilled down by dimension (at any level)

table_rows(dimension, depth=None, hierarchy=None)

Returns iterator of drilled-down rows which yields a named tuple with named attributes: (key, label, path, record). depth is last level of interest. If not specified (set to None) then deepest level for dimension is used.

• key: value of key dimension attribute at level of interest
• label: value of label dimension attribute at level of interest
• path: full path for the drilled-down cell
• is_base: True when dimension element is base (can not drill down more)
• record: all drill-down attributes of the cell

Example use:

for row in result.table_rows(dimension):
    print "%s: %s" % (row.label, row.record["record_count"])

dimension has to be cubes.Dimension object. Raises TypeError when cut for dimension is not PointCut.

to_dict()

Return dictionary representation of the aggregation result. Can be used for JSON serialisation.

Slicing and Dicing

class cubes.Cell(cube=None, cuts=[])

Part of a cube determined by slicing dimensions. Immutable object.

cut_for_dimension(dimension)

Return first found cut for given dimension

drilldown(dimension, value, hierarchy=None)

Create another cell by drilling down dimension next level on current level’s key value.

Example:

cell = cubes.Cell(cube)
cell = cell.drilldown("date", 2010)
cell = cell.drilldown("date", 1)

is equivalent to:

cut = cubes.PointCut(“date”, [2010, 1]) cell = cubes.Cell(cube, [cut])

Reverse operation is cubes.rollup("date")

Works only if the cut for dimension is PointCut. Otherwise the behaviour is undefined.

If hierarchy is not specified (by default) then default dimension hierarchy is used.

Returns new derived cell object.

is_base(dimension, hierarchy=None)

Returns True when cell is base cell for dimension. Cell is base if there is a point cut with path referring to the most detailed level of the dimension hierarchy.

level_depths()

Returns a dictionary of dimension names as keys and level depths (index of deepest level).

multi_slice(cuts)

Create another cell by slicing through multiple slices. cuts is a list of Cut object instances. See also Cell.slice().

point_cut_for_dimension(dimension)

Return first point cut for given dimension

point_slice(dimension, path)

Create another cell by slicing receiving cell through dimension at path. Receiving object is not modified. If cut with dimension exists it is replaced with new one. If path is empty list or is none, then cut for given dimension is removed.

Example:

full_cube = Cell(cube)
contracts_2010 = full_cube.point_slice("date", [2010])

Returns: new derived cell object.

Warning

Depreiated. Use cell.slice() instead with argument PointCut(dimension, path)

rollup(rollup)

Rolls-up cell - goes one or more levels up through dimension hierarchy. It works in similar way as drill down in AggregationBrowser.aggregate() but in the opposite direction (it is like cd .. in a UNIX shell).

Roll-up can be:

• a string - single dimension to be rolled up one level
• an array - list of dimension names to be rolled-up one level
• a dictionary where keys are dimension names and values are levels to be rolled up-to

Note

Only default hierarchy is currently supported.

rollup_dim(dimension, level=None, hierarchy=None)

Rolls-up cell - goes one or more levels up through dimension hierarchy. If there is no level to go up (we are at the top level), then the cut is removed.

If no hierarchy is specified, then the default dimension’s hierarchy is used.

Returns new cell object.

slice(cut)

Returns new cell by slicing receiving cell with cut. Cut with same dimension as cut will be replaced, if there is no cut with the same dimension, then the cut will be appended.

to_dict()

Returns a dictionary representation of the cell

to_str()

Return string representation of the cell by using standard cuts-to-string conversion.

Cuts

class cubes.PointCut(dimension, path, hierarchy=None)

Object describing way of slicing a cube (cell) through point in a dimension

level_depth()

Returns index of deepest level.

to_dict()

Returns dictionary representation of the receiver. The keys are: dimension, type`=``point` and path.

class cubes.RangeCut(dimension, from_path, to_path, hierarchy=None)

Object describing way of slicing a cube (cell) between two points of a dimension that has ordered points. For dimensions with unordered points behaviour is unknown.

level_depth()

Returns index of deepest level which is equivalent to the longest path.

to_dict()

Returns dictionary representation of the receiver. The keys are: dimension, type`=``range`, from and to paths.

class cubes.SetCut(dimension, paths, hierarchy=None)

Object describing way of slicing a cube (cell) between two points of a dimension that has ordered points. For dimensions with unordered points behaviour is unknown.

level_depth()

Returns index of deepest level which is equivalent to the longest path.

to_dict()

Returns dictionary representation of the receiver. The keys are: dimension, type`=``range` and set as a list of paths.

String conversions

In applications where slicing and dicing can be specified in form of a string, such as arguments of HTTP requests of an web application, there are couple helper methods that do the string-to-object conversion:

cubes.cuts_from_string(string)

Return list of cuts specified in string. You can use this function to parse cuts encoded in a URL.

Examples:

date:2004
date:2004,1
date:2004,1|class=5
date:2004,1,1|category:5,10,12|class:5

Ranges are in form from-to with possibility of open range:

date:2004-2010
date:2004,5-2010,3
date:2004,5-2010
date:2004,5-
date:-2010

Sets are in form path1;path2;path3 (none of the paths should be empty):

date:2004;2010
date:2004;2005,1;2010,10

Grammar:

<list> ::= <cut> | <cut> '|' <list>
<cut> ::= <dimension> ':' <path>
<dimension> ::= <identifier>
<path> ::= <value> | <value> ',' <path>

The characters ‘|’, ‘:’ and ‘,’ are configured in CUT_STRING_SEPARATOR, DIMENSION_STRING_SEPARATOR, PATH_STRING_SEPARATOR respectively.

cubes.string_from_cuts(cuts)

Returns a string represeting cuts. String can be used in URLs

cubes.string_from_path(path)

Returns a string representing dimension path. If path is None or empty, then returns empty string. The ptah elements are comma , spearated.

Raises ValueError when path elements contain characters that are not allowed in path element (alphanumeric and underscore _).

cubes.path_from_string(string)

Returns a dimension point path from string. The path elements are separated by comma , character.

Returns an empty list when string is empty or None.

cubes.levels_from_drilldown(cell, drilldown)

Converts drilldown into a list of levels to be used to drill down. drilldown can be:

• list of dimensions
• list of dimension level specifier strings (dimension@hierarchy:level)
• list of tuples in form (dimension, hierarchy, level).

If drilldown is a list of dimensions or if the level is not specified, then next level in the cell is considered. The implicit next level is determined from a `PointCut for dimension in the cell.

For other types of cuts, such as range or set, “next” level is the first level of hierarachy.

Returns a list of tuples: (dimension, levels) where levels is a list of levels to be drilled down.

Note

For backward compatibility the function accepts a dictionary where keys are dimension names and values are level names to drill up to. This is argument format is depreciated.

cubes.string_to_drilldown(astring)

Converts astring into a drilldown tuple (dimension, hierarchy, level). The string should have a format: dimension@hierarchy:level. Hierarchy and level are optional.

Raises ArgumentError when astring does not match expected pattern.

Mapper

class cubes.Mapper(cube, locale=None, schema=None, fact_name=None, **options)

Abstract class for mappers which maps logical references to physical references (tables and columns).

Attributes:

• cube - mapped cube
• simplify_dimension_references – references for flat dimensions (with one level and no details) will be just dimension names, no attribute name. Might be useful when using single-table schema, for example, with couple of one-column dimensions.
• fact_name – fact name, if not specified then cube.name is used
• schema – default database schema

all_attributes(expand_locales=False)

Return a list of all attributes of a cube. If expand_locales is True, then localized logical reference is returned for each attribute’s locale.

attribute(name)

Returns an attribute with logical reference name.

logical(attribute, locale=None)

Returns logical reference as string for attribute in dimension. If dimension is Null then fact table is assumed. The logical reference might have following forms:

• dimension.attribute - dimension attribute
• attribute - fact measure or detail

If simplify_dimension_references is True then references for flat dimensios without details is dimension.

If locale is specified, then locale is added to the reference. This is used by backends and other mappers, it has no real use in end-user browsing.

map_attributes(attributes, expand_locales=False)

Convert attributes to physical attributes. If expand_locales is True then physical reference for every attribute locale is returned.

physical(attribute, locale=None)

Returns physical reference as tuple for attribute, which should be an instance of cubes.model.Attribute. If there is no dimension specified in attribute, then fact table is assumed. The returned tuple has structure: (schema, table, column).

This method should be implemented by Mapper subclasses.

relevant_joins(attributes)

Get relevant joins to the attributes - list of joins that are required to be able to acces specified attributes. attributes is a list of three element tuples: (schema, table, attribute).

Subclasses sohuld implement this method.

set_locale(locale)

Change the mapper’s locale

split_logical(reference)

Returns tuple (dimension, attribute) from logical_reference string. Syntax of the string is: dimensions.attribute.

class cubes.SnowflakeMapper(cube, mappings=None, locale=None, schema=None, fact_name=None, dimension_prefix=None, joins=None, dimension_schema=None, **options)

A snowflake schema mapper for a cube. The mapper creates required joins, resolves table names and maps logical references to tables and respective columns.

Attributes:

• cube - mapped cube
• mappings – dictionary containing mappings
• simplify_dimension_references – references for flat dimensions (with one level and no details) will be just dimension names, no attribute name. Might be useful when using single-table schema, for example, with couple of one-column dimensions.
• dimension_prefix – default prefix of dimension tables, if default table name is used in physical reference construction
• fact_name – fact name, if not specified then cube.name is used
• schema – default database schema
• dimension_prefix – prefix for dimension tables
• dimension_schema – schema whre dimension tables are stored (if different than fact table schema)

mappings is a dictionary where keys are logical attribute references and values are table column references. The keys are mostly in the form:

• attribute for measures and fact details
• attribute.locale for localized fact details
• dimension.attribute for dimension attributes
• dimension.attribute.locale for localized dimension attributes

The values might be specified as strings in the form table.column (covering most of the cases) or as a dictionary with keys schema, table and column for more customized references.

physical(attribute, locale=None)

Returns physical reference as tuple for attribute, which should be an instance of cubes.model.Attribute. If there is no dimension specified in attribute, then fact table is assumed. The returned tuple has structure: (schema, table, column).

The algorithm to find physicl reference is as follows:

IF localization is requested:
    IF is attribute is localizable:
        IF requested locale is one of attribute locales
            USE requested locale
        ELSE
            USE default attribute locale
    ELSE
        do not localize

IF mappings exist:
    GET string for logical reference
    IF locale:
        append '.' and locale to the logical reference

    IF mapping value exists for localized logical reference
        USE value as reference

IF no mappings OR no mapping was found:
    column name is attribute name

    IF locale:
        append '_' and locale to the column name

    IF dimension specified:
        # Example: 'date.year' -> 'date.year'
        table name is dimension name

        IF there is dimension table prefix
            use the prefix for table name

    ELSE (if no dimension is specified):
        # Example: 'date' -> 'fact.date'
        table name is fact table name

relevant_joins(attributes)

Get relevant joins to the attributes - list of joins that are required to be able to acces specified attributes. attributes is a list of three element tuples: (schema, table, attribute).

table_map()

Return list of references to all tables. Keys are aliased tables: (schema, aliased_table_name) and values are real tables: (schema, table_name). Included is the fact table and all tables mentioned in joins.

To get list of all physical tables where aliased tablesare included only once:

finder = JoinFinder(cube, joins, fact_name)
tables = set(finder.table_map().keys())

class cubes.DenormalizedMapper(cube, locale=None, schema=None, fact_name=None, denormalized_view_prefix=None, denormalized_view_schema=None, **options)

Creates a mapper for a cube that has data stored in a denormalized view/table.

Attributes:

• denormalized_view_prefix – default prefix used for constructing

  view name from cube name

• fact_name – fact name, if not specified then cube.name is used

• schema – schema where the denormalized view is stored

• fact_schema – database schema for the original fact table

physical(attribute, locale=None)

Returns same name as localized logical reference.

relevant_joins(attributes)

Returns an empty list. No joins are necessary for denormalized view.