atoti.cube module

class atoti.cube.Cube(java_api, name, base_store, session)

Cube of a Session.

property aggregates_cache

Aggregates cache of the cube.

Return type


create_static_parameter_hierarchy(name, members, *, data_type=None, index_measure=None, indices=None, store_name=None)

Create an arbitrary single-level static hierarchy with the given members.

It can be used as a parameter hierarchy in advanced analyses.

  • name (str) – The name of hierarchy and its single level.

  • members (Sequence[Any]) – The members of the hierarchy.

  • data_type (Optional[DataType]) – The type with which the members will be stored. Automatically inferred by default.

  • index_measure (Optional[str]) – The name of the indexing measure to create for this hierarchy, if any.

  • indices (Optional[Sequence[int]]) – The custom indices for each member in the new hierarchy. They are used when accessing a member through the index_measure. Defaults to range(len(members)).

  • store_name (Optional[str]) – The name of the store backing the parameter hierarchy. Defaults to the passed name argument.

create_store_column_parameter_hierarchy(name, column)

Create a single level static hierarchy which takes its members from a column.

explain_query(*measures, condition=None, include_totals=False, levels=None, scenario='Base', timeout=30)

Run the query but return an explanation of how the query was executed instead of its result.

See also

query() for the roles of the parameters.

Return type



An explanation containing a summary, global timings, and the query plan with all the retrievals.

property hierarchies

Hierarchies of the cube.

Return type


property levels

Levels of the cube.

Return type


property measures

Measures of the cube.

Return type


property name

Name of the cube.

Return type


query(*measures, condition=None, include_totals=False, levels=None, mode='pretty', scenario='Base', timeout=30)

Query the cube to retrieve the value of the passed measures on the given levels.

In JupyterLab with the atoti-jupyterlab plugin installed, query results can be converted to interactive widgets with the Convert to Widget Below action available in the command palette or by right clicking on the representation of the returned Dataframe.

  • measures (Union[NamedMeasure, QueryMeasure]) – The measures to query. If None, all the measures are queried.

  • condition (Union[LevelCondition, MultiCondition, LevelIsInCondition, HierarchyIsInCondition, None]) –

    The filtering condition. Only conditions on level equality with a string are supported.


    >>> cube.query(
    ...     m["Price.SUM"],
    ...     levels=[lvl["Country"]],
    ...     condition=lvl["Continent"] == "Europe",
    ... )
    Continent Country
    Europe    France            200.00
              Germany           150.00
              United Kingdom    120.00
    >>> cube.query(
    ...     m["Price.SUM"],
    ...     levels=[lvl["Country"], lvl["Currency"]],
    ...     condition=(
    ...         (lvl["Continent"] == "Europe")
    ...         & (lvl["Currency"] == "EUR")
    ...     ),
    ... )
    Continent Country Currency
    Europe    France  EUR         200.00
              Germany EUR         150.00
    >>> cube.query(
    ...     m["Price.SUM"],
    ...     levels=[lvl["Country"]],
    ...     condition=h["Geography"].isin(
    ...         ("America",), ("Europe", "Germany")
    ...     ),
    ... )
    Continent Country
    America   Mexico           270.00
              United states    240.00
    Europe    Germany          150.00

  • include_totals (bool) –

    Whether the returned DataFrame should include the grand total and subtotals. Totals can be useful but they make the DataFrame harder to work with since its index will have some empty values.


    >>> cube.query(
    ...     m["Price.SUM"],
    ...     levels=[lvl["Country"], lvl["Currency"]],
    ...     include_totals=True,
    ... )
    Continent Country        Currency
    Total                                980.00
    America                              510.00
              Mexico                     270.00
                             MXN         270.00
              United states              240.00
                             USD         240.00
    Europe                               470.00
              France                     200.00
                             EUR         200.00
              Germany                    150.00
                             EUR         150.00
              United Kingdom             120.00
                             GBP         120.00

  • levels (Union[~_Level, Sequence[~_Level], None]) – The levels to split on. If None, the value of the measures at the top of the cube is returned.

  • scenario (str) – The scenario to query.

  • timeout (int) – The query timeout in seconds.

  • mode (Literal[‘pretty’, ‘raw’]) –

    The query mode.

    • "pretty" is best for queries returning small results:

      • A QueryResult will be returned and its rows will be sorted according to the level comparators.


      >>> cube.query(
      ...     m["Price.SUM"],
      ...     levels=[lvl["Continent"]],
      ...     mode="pretty",
      ... )
      America      510.00
      Europe       470.00
    • "raw" is best for benchmarks or large exports:

    • A faster and more efficient endpoint reducing the data transfer from Java to Python will be used.

    • A classic pandas.DataFrame will be returned.

    • include_totals="True" will not be allowed.

    • The Convert to Widget Below action provided by the atoti-jupyterlab plugin will not be available.


    >>> cube.query(
    ...     m["Price.SUM"],
    ...     levels=[lvl["Continent"]],
    ...     mode="raw",
    ... )
      Continent  Price.SUM
    0    Europe      470.0
    1   America      510.0

Return type

Union[QueryResult, DataFrame]

property schema

Schema of the cube’s stores as an SVG graph.


Graphviz is required to display the graph. It can be installed with Conda: conda install graphviz or by following the download instructions.

Return type



An SVG image in IPython and a Path to the SVG file otherwise.

setup_simulation(name, *, base_scenario='Base', levels=None, multiply=None, replace=None, add=None)

Create a simulation store for the given measures.

Simulations can have as many scenarios as desired.

The same measure cannot be passed in several methods.

Return type



The simulation on which scenarios can be made.

property shared_context

Context values shared by all the users.

Context values can also be set at query time, and per user, directly from the UI. The values in the shared context are the default ones for all the users.

  • queriesTimeLimit

    The number of seconds after which a running query is cancelled and its resources reclaimed. Set to -1 to remove the limit. Defaults to 30s.

  • queriesResultLimit.intermediateSize

    The limit number of point locations for a single intermediate result. This works as a safe-guard to prevent queries from consuming too much memory, which is especially useful when going to production with several simulatenous users on the same server. Set to -1 to use the maximum limit. In atoti, the maximum limit is the default while in Atoti+ it defaults to 1000000.

  • queriesResultLimit.tansientResultSize

    Similar to intermediateSize but across all the intermediate results of the same query. Set to -1 to use the maximum limit. In atoti, the maximum limit is the default while in Atoti+ it defaults to 10000000.


>>> df = pd.DataFrame(
...     columns=["City", "Price"],
...     data=[
...         ("London", 240.0),
...         ("New York", 270.0),
...         ("Paris", 200.0),
...     ],
... )
>>> store = session.read_pandas(
...     df, keys=["City"], store_name="shared_context example"
... )
>>> cube = session.create_cube(store)
>>> cube.shared_context["queriesTimeLimit"] = 60
>>> cube.shared_context["queriesResultLimit.intermediateSize"] = 1000000
>>> cube.shared_context["queriesResultLimit.transientSize"] = 10000000
>>> cube.shared_context
{'queriesTimeLimit': '60', 'queriesResultLimit.intermediateSize': '1000000', 'queriesResultLimit.transientSize': '10000000'}
Return type


property simulations

Simulations of the cube.

Return type


class atoti.cube.CubeContext(_java_api, _cube)