atoti.Cube.query()

Cube.query(*measures, context={}, filter=None, include_empty_rows=False, include_totals=False, levels=(), mode='pretty', scenario='Base', timeout=datetime.timedelta(seconds=30), **kwargs)

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.

Parameters:

• measures (BaseMeasure) – The measures to query.

• filter (QueryFilter | None) –

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

  Examples

  >>> df = pd.DataFrame(
  ...     columns=["Continent", "Country", "Currency", "Price"],
  ...     data=[
  ...         ("Europe", "France", "EUR", 200.0),
  ...         ("Europe", "Germany", "EUR", 150.0),
  ...         ("Europe", "United Kingdom", "GBP", 120.0),
  ...         ("America", "United states", "USD", 240.0),
  ...         ("America", "Mexico", "MXN", 270.0),
  ...     ],
  ... )
  >>> table = session.read_pandas(
  ...     df,
  ...     keys=["Continent", "Country", "Currency"],
  ...     table_name="Prices",
  ... )
  >>> cube = session.create_cube(table)
  >>> del cube.hierarchies["Continent"]
  >>> del cube.hierarchies["Country"]
  >>> cube.hierarchies["Geography"] = [
  ...     table["Continent"],
  ...     table["Country"],
  ... ]
  >>> cube.measures["American Price"] = tt.where(
  ...     cube.levels["Continent"] == "America",
  ...     cube.measures["Price.SUM"],
  ... )
  >>> h, l, m = cube.hierarchies, cube.levels, cube.measures
  

  Single equality test:

  >>> cube.query(
  ...     m["Price.SUM"],
  ...     levels=[l["Country"]],
  ...     filter=l["Continent"] == "Europe",
  ... )
                           Price.SUM
  Continent Country
  Europe    France            200.00
            Germany           150.00
            United Kingdom    120.00
  

  Combined equality test:

  >>> cube.query(
  ...     m["Price.SUM"],
  ...     levels=[l["Country"], l["Currency"]],
  ...     filter=(
  ...         (l["Continent"] == "Europe")
  ...         & (l["Currency"] == "EUR")
  ...     ),
  ... )
                             Price.SUM
  Continent Country Currency
  Europe    France  EUR         200.00
            Germany EUR         150.00
  

  Hierarchy filter:

  >>> cube.query(
  ...     m["Price.SUM"],
  ...     levels=[l["Country"]],
  ...     filter=h["Geography"].isin(
  ...         ("America",), ("Europe", "Germany")
  ...     ),
  ... )
                          Price.SUM
  Continent Country
  America   Mexico           270.00
            United states    240.00
  Europe    Germany          150.00
  

  Exclusion filter:

  >>> cube.query(
  ...     m["Price.SUM"],
  ...     levels=[l["Country"], l["Currency"]],
  ...     # Equivalent to `filter=(l["Currency"] != "GBP") & (l["Currency"] != "MXN")`
  ...     filter=~l["Currency"].isin("GBP", "MXN"),
  ... )
                                   Price.SUM
  Continent Country       Currency
  America   United states USD         240.00
  Europe    France        EUR         200.00
            Germany       EUR         150.00
  

• include_empty_rows (bool) –

  Whether to keep the rows where all the requested measures have no value.

  Example

  >>> cube.query(
  ...     m["American Price"],
  ...     levels=[l["Continent"]],
  ...     include_empty_rows=True,
  ... )
            American Price
  Continent
  America           510.00
  Europe
  

• include_totals (bool) –

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

  Example

  >>> cube.query(
  ...     m["Price.SUM"],
  ...     levels=[l["Country"], l["Currency"]],
  ...     include_totals=True,
  ... )
                                    Price.SUM
  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 (Iterable[BaseLevel]) – 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 (timedelta) – The amount of time the query execution can take before aborting it.

• 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 order.

    >>> cube.query(
    ...     m["Price.SUM"],
    ...     levels=[l["Continent"]],
    ...     mode="pretty",
    ... )
              Price.SUM
    Continent
    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=[l["Continent"]],
    ...     mode="raw",
    ... )
      Continent  Price.SUM
    0    Europe      470.0
    1   America      510.0
    

• context (Mapping[str, Any]) –

  Context values to use when executing the query.

  Defaults to atoti.Cube.shared_context.

Return type:

DataFrame