Databases¶

class tinyolap.database.Database(name: Optional[str] = None, in_memory: bool = True, encryption: tinyolap.encryption.EncryptionMethodEnum = EncryptionMethodEnum.NoEnryption, password: Optional[str] = None)

Databases are the root objects that should be use to create TinyOlap data model or database. The Database object provides methods to create dimensions and cubes.

add_cube(name: str, dimensions: list, measures=None, description: Optional[str] = None)

Creates a new cube and adds it to the database.

Parameters

name – Name of the cube to be created.
dimensions – A list of either names of existing dimensions of the database or dimension objects contained in the database.
measures – (optional) a measure name or a list of measures names for the cube. If argument ‘measures’ is not defined, that a default measure named ‘value’ will be created.
description – (optional) description for the cube.

Returns

The added cube object.

Raises

TinyOlapCubeCreationError – Raised if the creation of the cubed failed due to one of the following reasons:

The cube name is not invalid. Cube have to consist of lower case alphanumeric characters
or underscore only, blanks or special characters are not allowed.
The list of dimensions is empty, contains dimension names or objects not associated with the cube, or the number of dimensions exceeds the upper limit of dimensions supported for cube creation.

Note

The default upper limit for cube creation is 32 dimensions, but this limit can be adjusted at any time by changing the value for MAX_DIMS_PER_CUBE in the source file ‘database.py’.

Raises: TinyOlapDuplicateKeyError – Raised if the cube already exists.”)

add_dimension(name: str, description: Optional[str] = None) → tinyolap.dimension.Dimension

Adds a new dimension to the database.

Parameters

name – Name of the dimension to be added.
description – Description for the dimension.

Return Dimension

The newly added dimension.

Raises

InvalidDimensionNameException – If the dimension name is invalid.
DuplicateDimensionException – If a dimension with the same name already exists.

property caching: bool

Identifies if caching is activated for the database. By default, caching is activated for all cubes. The caching setting for individual cubes can be overwritten.

Note

It is highly recommended, especially for larger data models containing a lot of data maybe even essential, to always set caching to True` what anyhow is the default value. Caching greatly improves the user experience by caching values for aggregated cells from cubes.

Please be aware that the cache needs to be warmed up on first use. For future versions of TinyOlap it is planned to also persist the cube cache to enable faster initial cell access.

Returns: Returns True if caching is activated for the database, False otherwise.

clone(): Creates a clone of the database.

close()

Closes the database. If in-memory mode is off in_memory == False , then all pending changes to the database file will be committed and the connection to the underlying database will be be closed.

The close() command has no effect if the database is in-memory mode, meaning in_memory == True.

property code_manager: tinyolap.codemanager.CodeManager: Returns the code manager of the database.

cube_exists(name: str)

Checks if a cube exists.

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

delete(): Deletes the database file and log file, if such exists. If the database is open, it will be closed beforehand. You should handle this method with care. The delete() command has no effect if the database is in in-memory mode in_memory == True.

dimension_exists(name: str)

Checks if a dimension exists.

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

dimension_remove(dimension)

Removes a :ref:´dimension <dimensions>´ from the database.

Parameters: dimension – Name of the dimension, or the dimension object to be removed.
Raises: TinyOlapKeyNotFoundError – If the dimension not exists.

export(name: str, overwrite_if_exists: bool = False, encryption: tinyolap.encryption.EncryptionMethodEnum = EncryptionMethodEnum.NoEnryption, password: Optional[str] = None)

Exports the database to a new database file. This method is useful e.g. for creating backups and especially to persist databases that run in in-memory mode.

Note

When TinyOlap is used for data processing purposes, rather than as for planning or other data-entry focussed tasks, it is a clever idea to spin up the database first in in-memory mode, do all your processing and then persists the result using the export(...) method. This approach is presumably much faster than constantly writing to the database file.

Parameters

name – Either a simple name or a fully qualified file path. If the name does not represent a path, then the database file will be created in the default location /db or whatever is specified in the config file for database_folder.
overwrite_if_exists – Defines if an already existing file should be overwritten or not. If set to False and the file already exist, an FileExistsError will be raised.
encryption – Encryption method for database contents when ìn-memory = True. By default no encryption is used, encryption = EncryptionMethodEnum.NoEnryption.

Note

If encryption is required, using encryption = EncryptionMethodEnum.Obfuscation should be sufficient for most cases and is recommended for performance reasons. Use encryption = EncryptionMethodEnum.Encryption only if the highest possible security level is required. For such cases also ensure to choose a long (>= 32 charactes) and cryptic password consisting of upper- and lower-case chatacter, number and special characters.

Parameters: password – Password for encryption. Require if any other encryption method is required than encryption = EncryptionMethodEnum.NoEnryption. Please ensure to remember the password.
Returns

property file_path: str: Returns the file path of the database.

get(cube: str, address: Tuple[str], measure: str): Returns a value from the database for a given cube, idx_address and measure. If no records exist for a given valid idx_address, then 0.0 will be returned.

property history: tinyolap.history.History: Returns the history of the database.

property in_memory: bool

Identifies if the database is in-memory mode. Please note that the in-memory property can not be changed after the initialization of a database object.

Returns: Returns True if the database is in-memory mode, False otherwise.

property name: str: Returns the name of the database.

open(file_name: str)

Opens a database from a file.

Note

Please note that an already defined database name will be overwritten by the name defined in the dabase file.

Caution

If the database is set to in_memory == True, then the requested database file will be opened and used only to initialize the database (like a template). But it will NOT be connected and write back change to that database file. So, any subsequent change, after opening a database file, will happen in-memory only and not be persisted. Please remember, that you can use the export() method to save an in-memory databases at any time.

Parameters: file_name – The database file to open.

rename(new_name: str): Renames the database. :param new_name: New name for the database. :raise KeyError: Raised if the key is invalid.

save()

Saves pending changes to the database. The save() command has no effect if the database is in-memory mode, meaning in_memory == True.

Returns

set(cube: str, address: Tuple[str], value: float)

Writes a value to the database for the given cube, idx_address and measure. Write back is supported for base level cells only.

Note

Although TinyOlap is intended to be used for numerical data mainly, any Python data type or object reference can be written to a database. Persistence is only provided/guarantied for build-in base data types. If you want to serialized/deserialized custom objects through cube cells, then write/read json and do serialization and deserialization by yourself.

Parameters

cube – Name of the cube to write to.
address – Address of the cube cell to write to.
value – The value to be written to the database.

property uri: str: Returns the uri of the database.