> ## 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. # atoti.Cube.query() #### Cube.query(\*measures: [Measure](./atoti.measure#atoti.Measure), 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(\{}), explain: [Literal](https://docs.python.org/3/library/typing.html#typing.Literal)\[False] = False, filter: CubeQueryFilterCondition | [None](https://docs.python.org/3/library/constants.html#None) = None, include\_empty\_rows: [bool](https://docs.python.org/3/library/functions.html#bool) = False, include\_totals: [bool](https://docs.python.org/3/library/functions.html#bool) = False, levels: [Sequence](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence)\[[Level](./atoti.level#atoti.Level)] = (), mode: [Literal](https://docs.python.org/3/library/typing.html#typing.Literal)\['pretty'] = 'pretty', scenario: [str](https://docs.python.org/3/library/stdtypes.html#str) = None) → [MdxQueryResult](./atoti.mdx_query_result#atoti.MdxQueryResult) #### Cube.query(\*measures: [Measure](./atoti.measure#atoti.Measure), 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(\{}), explain: [Literal](https://docs.python.org/3/library/typing.html#typing.Literal)\[False] = False, filter: CubeQueryFilterCondition | [None](https://docs.python.org/3/library/constants.html#None) = None, include\_empty\_rows: [bool](https://docs.python.org/3/library/functions.html#bool) = False, include\_totals: [bool](https://docs.python.org/3/library/functions.html#bool) = False, levels: [Sequence](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence)\[[Level](./atoti.level#atoti.Level)] = (), mode: [Literal](https://docs.python.org/3/library/typing.html#typing.Literal)\['pretty', 'raw'] = 'pretty', scenario: [str](https://docs.python.org/3/library/stdtypes.html#str) = None) → [DataFrame](https://pandas.pydata.org/pandas-docs/version/2.3/reference/api/pandas.DataFrame.html#pandas.DataFrame) #### Cube.query(\*measures: [Measure](./atoti.measure#atoti.Measure), 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(\{}), explain: [Literal](https://docs.python.org/3/library/typing.html#typing.Literal)\[True], filter: CubeQueryFilterCondition | [None](https://docs.python.org/3/library/constants.html#None) = None, include\_empty\_rows: [bool](https://docs.python.org/3/library/functions.html#bool) = False, include\_totals: [bool](https://docs.python.org/3/library/functions.html#bool) = False, levels: [Sequence](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence)\[[Level](./atoti.level#atoti.Level)] = (), mode: [Literal](https://docs.python.org/3/library/typing.html#typing.Literal)\['pretty', 'raw'] = 'pretty', scenario: [str](https://docs.python.org/3/library/stdtypes.html#str) = None) → [object](https://docs.python.org/3/library/functions.html#object) Execute and 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:** * **measures** – The measures to query. * **context** – 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. * **explain** – 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. * **filter** – The filtering condition. ### Example ```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: [] ``` * **include\_empty\_rows** – Whether to keep the rows where all the requested measures have no value. ### Example ```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 ``` * **include\_totals** – 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 ```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 ``` * **levels** – The levels to split on. If `None`, the value of the measures at the top of the cube is returned. * **mode** – The query mode. * `"pretty"` is best for queries returning small results. ### Example ```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. ### Example ```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 ``` * **scenario** – The name of the scenario to query. **See also**: [`atoti.Session.query_mdx()`](./atoti.Session.query_mdx#atoti.Session.query_mdx)