OLAP Cubes

Note: For Cubes API see brewery.cubes.

Logical Model

The logical model entities and relationships.

Create a model:

model = brewery.cubes.model_from_path(path)

The path is a directory with logical model description files.

Model can be represented also as a single json file containing all model objects.

Original design decision for directory based models was because of easier copying of model objects (dimensions, cubes) from one model to another without requirements for any special tools - filesystem copy would be sufficient.

Logical Model description

File	Description
model.json	Core model information
cube_*cube_name*.json	Cube description, one file per cube
dim_*dimension_name*.json	Dimension description, one file per dimension

model.json

The model.json contains main model description dictionary. The file looks like this:

{
    "name": "public_procurements",
    "label": "Public Procurements of Slovakia",
    "description": "Contracts of public procurement winners in Slovakia"
}

Key	Description
name	dimension name
label	human readable name - can be used in an application
description	longer human-readable description of the model

Dimension descriptions

Dimension descriptions are stored in json files with prefix dim_ like dim_supplier, or as a dictionary for key dimensions in the model description dictionary.

Dimension description - attributes.

The dimension description contains keys:

Key	Description
name	dimension name
label	human readable name - can be used in an application
levels	dictionary of hierarchy levels
attributes	dictionary of dimension attributes
hierarchies	dictionary of dimension hierarchies

Example:

{
    "name": "date",
    "label": "Dátum",
    "levels": { ... }
    "attributes": { ... }
    "hierarchies": { ... }
}

Hierarchy levels are described:

Key	Description
label	human readable name - can be used in an application
key	key field of the level (customer number for customer level, region code for region level, year-month for month level). key will be used as a grouping field for aggregations. Key should be unique within level.
label_attribute	name of attribute containing label to be displayed (customer name for customer level, region name for region level, month name for month level)
attributes	list of other additional attributes that are related to the level. The attributes are not being used for aggregations, they provide additional useful information.

Example of month level of date dimension:

"month": {
    "label": "Mesiac",
    "key": "month",
    "label_attribute": "month_name",
    "attributes": ["month", "month_name", "month_sname"]
},

Example of supplier level of supplier dimension:

"supplier": {
    "label": "Dodávateľ",
    "key": "ico",
    "label_attribute": "name",
    "attributes": ["ico", "name", "address", "date_start", "date_end",
                    "legal_form", "ownership"]
}

Hierarchies are described:

Key	Description
label	human readable name - can be used in an application
levels	ordered list of level names from top to bottom - from least detailed to most detailed (for example: from year to day, from country to city)

Example:

"hierarchies": {
    "default": {
        "levels": ["year", "month"]
    },
    "ymd": {
        "levels": ["year", "month", "day"]
    },
    "yqmd": {
        "levels": ["year", "quarter", "month", "day"]
    }
}

Cube descriptions

Cube descriptions are stored in json files with prefix cube_ like cube_contracts, or as a dictionary for key cubes in the model description dictionary.

Key	Description
name	dimension name
label	human readable name - can be used in an application
measures	list of cube measures
dimensions	list of cube dimensions
joins	specification of physical table joins
mappings	mapping of logical attributes to physical attributes

Example:

{
    "name": "date",
    "label": "Dátum",
    "dimensions": [ "date", ... ]
    "joins": { ... }
    "mappings": { ... }
}

Model validation

To validate a model do:

results = model.validate()

This will return a list of tuples (result, message) where result might be ‘warning’ or ‘error’. If validation contains errors, the model can not be used without resulting in failure. If there are warnings, some functionalities might or might not fail or might not work as expected.

You can validate model from command line:

brewery validate_model /path/to/model

Errors

Error	Resolution
No mappings for cube a cube	Provide mappings dictionary for cube
No mapping for measure a measure in cube a cube	Add mapping for a measure into mappings dictionary
No levels in dimension a dimension	Define at least one dimension level.
No hierarchies in dimension a dimension	Define at least one hierarchy.
No defaut hierarchy specified, there is more than one hierarchy in dimension a dimension	Specify a default hierarchy name or name one hierarchy as default
Level a level in dimension a dimension has no attributes	Provide level attributes. At least one - the level key.
Key a key in level a level in dimension a dimension is not in attribute list	Add key attribute into attribute list or check the key name.
Dimension a dimension is not a subclass of Dimension class	This might happen when model was constructed programatically. Check your model construction code.

Warnings

Warning	Resolution
No fact specified for cube a cube (factless cubes are not yet supported, using ‘fact’ as default dataset/table name	Specify a fact table/dataset, otherwise table with name fact will be used. View builder will fail if such table does not exist.
No mapping for dimension a dimension attribute an attribute in cube a cube (using default mapping)	Provide mapping for dimension, otherwise identity mapping will be used (dimension.attribute)
No default hierarchy name specified in dimension a dimension, using some autodetect default name	Provide default_hierarchy_name. If there is only one hierarchy for dimension, the only one will be used. If there are more hierarchies, the one with name default will be used.
Default hierarchy a hierarchy does not exist in dimension a dimension	Check that default_hierarchy refers to existing hierarchy within that dimension.
Level a level in dimension a dimension has no key attribute specified, first attribute will be used: first attribute name	Specify key attribute in the dimension level.
No cubes defined	Define at least one cube.