Dimensions¶

class tinyolap.dimension.Dimension(dim_creation_key, name: str, description: str = '')

Dimensions are used to define the axis of a multi-dimensional cube. Dimensions contain a list or hierarchy of member_defs. Members are string address and representing the entities of the dimension. e.g., for a dimension called ‘months’ this would be the month names ‘Jan’ to ‘Dec’ or month aggregations like quarters or semesters.

Important

It is not foreseen to create Dimension objects directly! Always use the add_dimension() method of a database to create a new dimension instance, as shown in the code fragment below.

from tinyolap.database import Database

# setup a new database
database = Database("foo")

# define dimensions
dimension = db.add_dimension("bar")

Within a single database, dimensions need to be unique by there name.

class MemberIndexManager(current: Optional[list[int]] = None, first_free: int = 1): Manages the available member index numbers.

add_attribute(attribute_name: str, value_type: type = <class 'object'>)

Adds an attribute field to the dimension. Attributes enable to store additional information along side of dimension member_defs. Attributes have a value_type which is checked when an attribute value is set.

Parameters

attribute_name – Name of the attribute to be added.
value_type – Type of value expected for the attribute. Default value is object to allow any data.

Raises

TinyOlapInvalidKeyError – Raised when the name of the attribute is invalid.
TinyOlapDuplicateKeyError – Raised when the name of the attribute already exists.

add_member(member, children=None, description=None, number_format=None) → tinyolap.dimension.Dimension

Adds one or multiple member_defs and (optionally) associated child-member_defs to the dimension.

Parameters

member – A single string or an iterable of strings containing the member_defs to be added.
children – A single string or an iterable of strings containing the child member_defs to be added. If parameter ‘member’ is an iterable of strings, then children must be an iterable of same size, either containing strings (adds a single child) or itself an iterable of string (adds multiple children).
description – A description for the member to be added. If parameter ‘member’ is an iterable, then description will be ignored. For that case, please set descriptions for each member individually.
number_format – A format string for output formatting, e.g. for numbers or percentages. Formatting follows the standard Python formatting specification at <https://docs.python.org/3/library/string.html#format-specification-mini-language>.

Return Dimension

Returns the dimension itself.

add_subset(subset_name: str, members)

Adds a new subset to the dimension. A subset is a plain list of member_defs, useful for calculation and reporting purposes.

Parameters

subset_name – Name of the subset to be added.
members – A list (iterable) containing the member to be added to the subset.

Raises

TinyOlapInvalidKeyError – Raised when the name of the subset is invalid.
TinyOlapDuplicateKeyError – Raised when the name of the subset already exists.
TypeError – Raised when member_defs list is not of the expected type (list or tuple)
KeyError – Raised when a member from the member_defs list is not contained in the dimension.

attributes_count() → int

Returns the number attributes defined in the dimension.

Returns: Number attributes defined in the dimension.

clear() → tinyolap.dimension.Dimension

Deletes all member_defs and all member_defs from the dimension. Attributes will be kept.

Returns: The dimension itself.

commit() → tinyolap.dimension.Dimension

Commits all changes since ‘edit_begin()’ was called and ends the edit mode.

Returns: The dimension itself.

del_attribute_value(attribute: str, member: str)

Deletes an attribute value for a specific member of the dimension.

Parameters

attribute – Name of the attribute to be deleted.
member – Name of the member to delete the attribute for.

Raises

KeyError – Raised when either the member or the attribute name does not exist.

edit() → tinyolap.dimension.Dimension

Sets the dimension into edit mode. Required to add, remove or rename member_defs, to add remove or edit subsets or attributes and alike.

Returns: The dimension itself.

from_json(json_string: str)

(Re-)initializes the dimension from a json string.

Warning

Calling this method for dimensions which are already used by cubes will very likely corrupt your database! Calling this method is only save before you create any cube. Handle with care.

Parameters: json_string – The json string containing the dimension definition.
Raises: TinyOlapFatalError – Raised if an error occurred during the deserialization from json string.

get_aggregated_members() → list[str]

Returns a list of all aggregated member_defs (member_defs with children = level greater 0) of the dimension.

Returns: List of aggregated member_defs of the dimension.

get_attribute(attribute: str, member: str)

Returns the attribute value for a specific member of the dimension.

Parameters

attribute – Name of the attribute to be returned.
member – Name of the member to get the attribute for.

Raises

KeyError – Raised when either the member or the attribute name does not exist.

Returns

The value of the attribute, or None if the attribute is not defined for the specific member.

get_attribute_type(attribute: str)

Returns the data type of an attribute.

Parameters: attribute – Name of the attribute to be returned.
Raises: KeyError – Raised when the attribute name does not exist.
Returns: The type of the attribute.

get_first_member() → str

Returns the first member of the dimension.

Returns: Returns the first member_defs of the dimension.

get_leaves() → list[str]

Returns a list of all leave member_defs (member_defs without children = level equals 0) of the dimension.

Returns: List of leave level member_defs of the dimension.

get_member_by_alias(alias: str) → str

Returns the name of a member associated with the given.

Parameters: alias – Name of the alias to be checked.
Raises: KeyError – Raised if the alias does not exist.

get_member_by_index(index: int) → str

Returns the name of a member associated with the given.

Parameters: index – Index of the member to be returned.
Raises: KeyError – Raised if the alias does not exist.

get_members() → list[str]

Returns a list of all member_defs of the dimension.

Returns: List of all member_defs of the dimension.

get_members_by_attribute(attribute_name: str, attribute_value) → list[str]

Returns all member_defs having a specific attribute value.

Parameters

attribute_name – Name of the attribute to be analyzed.
attribute_value – Value of the attribute to used for filtering.

Returns

get_members_by_level(level: int) → list[str]

Returns a list of all member_defs of the specific member level. 0 identifies the leave level of the dimension.

Parameters: level – Level of the member_defs to be returned.
Returns: List of member_defs of the specific member level.

get_members_idx() → list[int]

Returns a list of indexes of all member_defs of the dimension.

Returns: List of indexes of all member_defs of the dimension.

get_root_members() → list[str]

Returns a list of all root member_defs (member_defs with a parent) of the dimension.

Returns: Returns a list of all root member_defs of the dimension.

get_subset(subset_name: str) → tuple[str]

Returns the list of member from a subset to the dimension.

Parameters: subset_name – Name of the subset to be return.
Raises: KeyError – Raised when the subset is not contained in the dimension.

get_top_level() → int

Returns the highest member level over all member_defs of the dimension.

Returns: The highest member level over all member_defs of the dimension.

has_attribute(attribute: str)

Checks if a specific attribute is defined for the dimension.

Parameters: attribute – Name of the attribute to be checked.
Returns: True``if the attribute exists. ``False otherwise.

has_subset(subset_name: str) → bool

Checks if a specific subset is defined for the dimension.

Parameters: subset_name – Name of the subset to be checked.
Returns: True``if the subset exists. ``False otherwise.

member_add_alias(member: str, alias: str)

Adds a member alias to the dimension. Aliases enable the access of member_defs by alternative names or address (e.g. a technical key, or an abbreviation).

Parameters

member – Name of the member to add an alias for.
alias – The alias to be set.

Raises

KeyError – Raised if the member does not exist.
TinyOlapDuplicateKeyError – Raised if the alias is already used by another member. Individual aliases can only be assigned to one member.

member_aliases_count(member: str) → int

Returns the number of aliases defined for a given member.

Parameters: member – Name of the member to be checked.
Raises: KeyError – Raised if the member does not exist.

member_exists(member: str) → bool

Check if the member exists in the dimension.

Parameters: member – Name of the member to be checked.
Returns: True if the member exists, False otherwise.

member_get_children(member: str) → tinyolap.member.MemberList

Returns a list of all children of a member.

Parameters: member – Name of the member to be evaluated.
Returns: List of children.
Raises: KeyError – Raised if the member does not exist.

member_get_format(member: str) → str

Returns the number_format string of a member.

Parameters: member – Name of the member to return the number_format for.
Returns: Returns the number_format string for the member, or None if no number_format string is defined.

member_get_index(member: str) → int

Returns the database internal index of a member.

Parameters: member – Name of the member to be evaluated.
Returns: The internal index of the member.
Raises: KeyError – Raised if the member does not exist.

member_get_leaves(member) → tinyolap.member.MemberList

Returns a list of all leave (base level) member_defs of a member.

Parameters: member – Name of the member to be evaluated.
Returns: List of leave children/member_defs.
Raises: KeyError – Raised if the member does not exist.

member_get_level(member: str)

Returns the level of a member within the member hierarchy.

Parameters: member – Name of the member to be evaluated.
Returns: 0 for leave level member_defs, values > 0 for aggregated member_defs.
Raises: KeyError – Raised if the member does not exist.

member_get_ordinal(member: str) → int

Returns the ordinal position of a member with the list of member_defs of the dimension.

Parameters: member – Name of the member to be checked.
Returns: The ordinal position of the member. If the member does not exits -1 will be returned

member_get_parents(member: str) → list[str]: Returns a list of all parents of a member. :param member: Name of the member to be evaluated. :return: List of parents. :raises KeyError: Raised if the member does not exist.

member_get_roots(member) → tinyolap.member.MemberList

Returns a list of all root (top level) member_defs of a member.

Parameters: member – Name of the member to be evaluated.
Returns: List of root parents/member_defs.
Raises: KeyError – Raised if the member does not exist.

member_has_alias(member: str) → bool

Checks if for a given member an alias is defined.

Parameters: member – Name of the member to be checked.
Raises: KeyError – Raised if the member does not exist.

member_is_leave(member: str)

Returns True if the member is a leave-level member (member.level = 0) within the member hierarchy.

Parameters: member – Name of the member to be evaluated.
Returns: True if the member is a leave-level member, False otherwise.
Raises: KeyError – Raised if the member does not exist.

member_is_root(member: str)

Returns True if the member is a leave-level member (member.level = 0) within the member hierarchy.

Parameters: member – Name of the member to be evaluated.
Returns: True if the member is a leave-level member, False otherwise.
Raises: KeyError – Raised if the member does not exist.

member_remove_all_aliases(member: str)

Removes all aliases of a member from the dimension.

Parameters: member – Name of the member to remove the aliases for.
Raises: KeyError – Raised if the member does not exist.

member_remove_format(member: str)

Removes the number_format string of a member.

Parameters: member – Name of the member to remove the number_format for.

member_set_format(member: str, format_string: str)

Set a number_format string for output formatting, especially useful for number formatting. Member formatting follows the standard Python formatting specification at https://docs.python.org/3/library/string.html#format-specification-mini-language.

Parameters

member – Name of the member to set the number_format for.
format_string – The number_format string to be used. Member formatting follows the standard Python formatting specification at https://docs.python.org/3/library/string.html#format-specification-mini-language.

property members: tinyolap.member.MemberList: Returns the list of member in the dimension. :return:

remove_alias(alias: str)

Removes a member alias from the dimension.

Parameters: alias – The alias to be removed.

remove_attribute(attribute_name: str)

Removes an attribute from the dimension.

Parameters: attribute_name – Name of the attribute to be removed.
Raises: KeyError – Raises KeyError if the attribute name not exists.

remove_member(member)

Removes one or multiple member_defs from a dimension.

Parameters: member – The member or an iterable of member_defs to be deleted.

remove_subset(subset_name: str)

Removes a subset from the dimension.

Parameters: subset_name – Name of the subset to be removed.
Raises: KeyError – Raised when the subset is not contained in the dimension.

rename_attribute(attribute_name: str, new_attribute_name: str)

Renames an attribute of a dimension.

Parameters

attribute_name – The name of the attribute to be renamed.
new_attribute_name – The new name of the attribute.

Raises

TinyOlapInvalidKeyError – Raised when the new name of the attribute is invalid.
TinyOlapDuplicateKeyError – Raised when the new name of the attribute already exists.

rename_member(member: str, new_name: str, new_description: Optional[str] = None): Renames a member.

rename_subset(subset_name: str, new_subset_name: str)

Renames a subset of the dimension.

Parameters

subset_name – Name of the subset to be added.
new_subset_name – New name of the subset.

Raises

TinyOlapInvalidKeyError – Raised when the new name for the subset is invalid.
KeyError – Raised when the subset is not contained in the dimension.

rollback() → tinyolap.dimension.Dimension

Rollback all changes since ‘edit_begin()’ was called and ends the edit mode.

Returns: The dimension itself.

set_attribute(attribute: str, member: str, value)

Sets an attribute for a specific member of the dimension.

Parameters

member – Name of the member to set the attribute for.
attribute – Name of the attribute to be set.
value – Value to be set.

Raises

KeyError – Raised when either the member or the attribute name does not exist.
TypeError – Raised when the value if not of the expected type.

subset_contains(subset_name: str, member_name: str) → bool

Checks if a specific member is contained in a subset of the dimension.

Parameters

subset_name – Name of the subset to be checked.
member_name – Name of the member to be checked.

Returns

True``if the member is contained in the subset. ``False otherwise.

subsets_count() → int

Returns the number subsets defined in the dimension.

Returns: Number subsets defined in the dimension.

to_json(beautify: bool = False)

Returns the json representation of the dimension. Helpful for serialization and deserialization of a dimension. The json returned by this function is the same as the one contained in the SQLite database storage provider (if available).

Parameters: beautify – Identifies if the json code should be beautified (multiple rows + indentation).
Returns: A json string representing the dimension.