> ## Documentation Index
> Fetch the complete documentation index at: https://docs.activeviam.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Cube.query()

<span id="atoti.Cube.query" />

> @overload<br />
> Cube.query(<br />
>     *\*measures*: [Measure](./atoti.Measure#atoti.Measure),<br />
>     *context*: [Mapping](https://docs.python.org/3/library/collections.abc.html#collections.abc.Mapping)\[[str](https://docs.python.org/3/library/stdtypes.html#str), [bool](https://docs.python.org/3/library/functions.html#bool) | [int](https://docs.python.org/3/library/functions.html#int) | [float](https://docs.python.org/3/library/functions.html#float) | [str](https://docs.python.org/3/library/stdtypes.html#str)] = `frozendict({})`,<br />
>     *explain*: [Literal](https://docs.python.org/3/library/typing.html#typing.Literal)\[False] = `False`,<br />
>     *filter*: CubeQueryFilterCondition | [None](https://docs.python.org/3/library/constants.html#None) = `None`,<br />
>     *include\_empty\_rows*: [bool](https://docs.python.org/3/library/functions.html#bool) = `False`,<br />
>     *include\_totals*: [bool](https://docs.python.org/3/library/functions.html#bool) = `False`,<br />
>     *levels*: [Sequence](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence)\[[Level](./atoti.Level#atoti.Level)] = `()`,<br />
>     *mode*: [Literal](https://docs.python.org/3/library/typing.html#typing.Literal)\['pretty'] = `'pretty'`,<br />
>     *scenario*: [str](https://docs.python.org/3/library/stdtypes.html#str) | [None](https://docs.python.org/3/library/constants.html#None) = `None`,<br />
> ) → [MdxQueryResult](./atoti.MdxQueryResult#atoti.MdxQueryResult)

> @overload<br />
> Cube.query(<br />
>     *\*measures*: [Measure](./atoti.Measure#atoti.Measure),<br />
>     *context*: [Mapping](https://docs.python.org/3/library/collections.abc.html#collections.abc.Mapping)\[[str](https://docs.python.org/3/library/stdtypes.html#str), [bool](https://docs.python.org/3/library/functions.html#bool) | [int](https://docs.python.org/3/library/functions.html#int) | [float](https://docs.python.org/3/library/functions.html#float) | [str](https://docs.python.org/3/library/stdtypes.html#str)] = `frozendict({})`,<br />
>     *explain*: [Literal](https://docs.python.org/3/library/typing.html#typing.Literal)\[False] = `False`,<br />
>     *filter*: CubeQueryFilterCondition | [None](https://docs.python.org/3/library/constants.html#None) = `None`,<br />
>     *include\_empty\_rows*: [bool](https://docs.python.org/3/library/functions.html#bool) = `False`,<br />
>     *include\_totals*: [bool](https://docs.python.org/3/library/functions.html#bool) = `False`,<br />
>     *levels*: [Sequence](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence)\[[Level](./atoti.Level#atoti.Level)] = `()`,<br />
>     *mode*: [Literal](https://docs.python.org/3/library/typing.html#typing.Literal)\['pretty', 'raw'] = `'pretty'`,<br />
>     *scenario*: [str](https://docs.python.org/3/library/stdtypes.html#str) | [None](https://docs.python.org/3/library/constants.html#None) = `None`,<br />
> ) → [DataFrame](https://pandas.pydata.org/pandas-docs/version/3.0/reference/api/pandas.DataFrame.html#pandas.DataFrame)

> @overload<br />
> Cube.query(<br />
>     *\*measures*: [Measure](./atoti.Measure#atoti.Measure),<br />
>     *context*: [Mapping](https://docs.python.org/3/library/collections.abc.html#collections.abc.Mapping)\[[str](https://docs.python.org/3/library/stdtypes.html#str), [bool](https://docs.python.org/3/library/functions.html#bool) | [int](https://docs.python.org/3/library/functions.html#int) | [float](https://docs.python.org/3/library/functions.html#float) | [str](https://docs.python.org/3/library/stdtypes.html#str)] = `frozendict({})`,<br />
>     *explain*: [Literal](https://docs.python.org/3/library/typing.html#typing.Literal)\[True],<br />
>     *filter*: CubeQueryFilterCondition | [None](https://docs.python.org/3/library/constants.html#None) = `None`,<br />
>     *include\_empty\_rows*: [bool](https://docs.python.org/3/library/functions.html#bool) = `False`,<br />
>     *include\_totals*: [bool](https://docs.python.org/3/library/functions.html#bool) = `False`,<br />
>     *levels*: [Sequence](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence)\[[Level](./atoti.Level#atoti.Level)] = `()`,<br />
>     *mode*: [Literal](https://docs.python.org/3/library/typing.html#typing.Literal)\['pretty', 'raw'] = `'pretty'`,<br />
>     *scenario*: [str](https://docs.python.org/3/library/stdtypes.html#str) | [None](https://docs.python.org/3/library/constants.html#None) = `None`,<br />
> ) → [object](https://docs.python.org/3/library/functions.html#object)

Execute an MDX query.

In JupyterLab with [`atoti-jupyterlab`](./atoti_jupyterlab#module-atoti_jupyterlab) 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

<h4 id="atoti.Cube.query.measures">
  *\*measures*
</h4>

The measures to query.

<h4 id="atoti.Cube.query.context">
  *context*
</h4>

Context values to use when executing the query.

See [`shared_context`](./atoti.Cube.shared_context#atoti.Cube.shared_context) for some of the available context values.

<h4 id="atoti.Cube.query.explain">
  *explain*
</h4>

When `True`, execute the query but, instead of returning its result, return an explanation of how it was executed containing a summary, global timings, and the query plan and all its retrievals.

<h4 id="atoti.Cube.query.filter">
  *filter*
</h4>

The filtering condition.

```pycon theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
>>> df = pd.DataFrame(
...     columns=[
...         "Continent",
...         "Country",
...         "Currency",
...         "Year",
...         "Month",
...         "Price",
...     ],
...     data=[
...         ("Europe", "France", "EUR", 2023, 10, 200.0),
...         ("Europe", "Germany", "EUR", 2024, 2, 150.0),
...         ("Europe", "United Kingdom", "GBP", 2022, 10, 120.0),
...         ("America", "United states", "USD", 2020, 5, 240.0),
...         ("America", "Mexico", "MXN", 2021, 3, 270.0),
...     ],
... )
>>> table = session.read_pandas(
...     df,
...     keys={"Continent", "Country", "Currency", "Year", "Month"},
...     table_name="Prices",
... )
>>> cube = session.create_cube(table)
>>> h, l, m = cube.hierarchies, cube.levels, cube.measures
>>> h["Geography"] = [table["Continent"], table["Country"]]
>>> for name in h["Geography"]:
...     del h[name]
>>> h["Date"] = [table["Year"], table["Month"]]
>>> for name in h["Date"]:
...     del h[name]
```

Single equality condition:

```pycon theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
>>> 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 condition:

```pycon theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
>>> 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 condition:

```pycon theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
>>> 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
```

Inequality condition:

```pycon theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
>>> cube.query(
...     m["Price.SUM"],
...     levels=[l["Country"], l["Currency"]],
...     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
>>> cube.query(
...     m["Price.SUM"],
...     levels=[l["Year"]],
...     filter=l["Year"] >= 2022,
... )
     Price.SUM
Year
2022    120.00
2023    200.00
2024    150.00
```

Deep level of a multilevel hierarchy condition:

```pycon theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
>>> cube.query(
...     m["Price.SUM"],
...     levels=[l["Month"]],
...     filter=l["Month"] == 10,
... )
           Price.SUM
Year Month
2022 10       120.00
2023 10       200.00
```

Measure condition:

```pycon theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
>>> cube.query(
...     m["Price.SUM"],
...     levels=[l["Month"]],
...     filter=m["Price.SUM"] >= 123,
... )
           Price.SUM
Year Month
2020 5        240.00
2021 3        270.00
2023 10       200.00
2024 2        150.00
```

```pycon theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
>>> cube.query(m["Price.SUM"], filter=m["Price.SUM"] > 123)
  Price.SUM
0    980.00
```

```pycon theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
>>> cube.query(m["Price.SUM"], filter=m["Price.SUM"] < 123)
Empty DataFrame
Columns: []
Index: []
```

<h4 id="atoti.Cube.query.include_empty_rows">
  *include\_empty\_rows*
</h4>

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

```pycon theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
>>> m["American price"] = tt.where(
...     l["Continent"] == "America", m["Price.SUM"]
... )
>>> cube.query(
...     m["American price"],
...     levels=[l["Continent"]],
...     include_empty_rows=True,
... )
          American price
Continent
America           510.00
Europe
```

<h4 id="atoti.Cube.query.include_totals">
  *include\_totals*
</h4>

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.

```pycon theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
>>> 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
```

<h4 id="atoti.Cube.query.levels">
  *levels*
</h4>

The levels to split on.
If `None`, the value of the measures at the top of the cube is returned.

<h4 id="atoti.Cube.query.mode">
  *mode*
</h4>

The query mode.

* `"pretty"` is best for queries returning small results.

```pycon theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
>>> 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.
  * The **Convert to Widget Below** action provided by [`atoti-jupyterlab`](./atoti_jupyterlab#module-atoti_jupyterlab) will not be available.

```pycon theme={"languages":{"custom":["/engine/python-sdk/0.9/languages/pycon.tmLanguage.json"]}}
>>> cube.query(
...     m["Price.SUM"],
...     levels=[l["Continent"]],
...     mode="raw",
... )
  Continent  Price.SUM
0   America      510.0
1    Europe      470.0
```

<h4 id="atoti.Cube.query.scenario">
  *scenario*
</h4>

The name of the scenario to query.

***

<Callout icon="link">
  **See also**:
  [`atoti.Session.query_mdx()`](./atoti.Session.query_mdx#atoti.Session.query_mdx)
</Callout>