Cube

The Cube sub-client provides access to the IYREE Cube.js API. Build type-safe analytics queries with the query builder or pass raw dicts.

from iyree import IyreeClient

with IyreeClient(api_key="my-key") as client:
    result = client.cube.load({"measures": ["orders.count"]})
    print(result.data)

Methods

`load`

Execute a Cube.js query. Handles JWT token refresh and “Continue wait” polling automatically.

result = client.cube.load(query)

Parameters

Dict[str, Any] | Query

required

A Query object (see Query builder below) or a raw Cube.js query dict.

# Raw dict
client.cube.load({"measures": ["orders.count"]})

# Query builder
client.cube.load(query_object)

float

Override for the continue-wait polling timeout in seconds. Defaults to cube_continue_wait_timeout from configuration.

Returns `CubeQueryResult`

List[Dict[str, Any]]

Result rows as a list of dictionaries.

Dict[str, Any]

Column annotation metadata from Cube.js (titles, types, formats).

Dict[str, Any]

The original query echoed back by Cube.js.

Dict[str, Any]

The full JSON response for advanced use cases.

Result methods

() -> pd.DataFrame

Convert to a pandas DataFrame. Requires iyree[pandas].

df = client.cube.load(query).to_dataframe()

Errors

Exception	Condition
`IyreeCubeTimeoutError`	Continue-wait polling exceeded the configured timeout
`IyreeAuthError`	Invalid or expired token (retried once automatically)

`meta`

Fetch Cube.js metadata — available cubes, measures, dimensions, and segments.

metadata = client.cube.meta()
for cube in metadata["cubes"]:
    print(cube["name"])

Parameters

float

Per-request timeout override in seconds.

Returns `Dict[str, Any]`

The raw metadata dict from Cube.js containing cubes, measures, dimensions, and segments.

Query builder

The SDK provides a typed query builder for constructing Cube.js queries. All classes are importable from the top-level iyree package.

from iyree import Cube, Query, TimeDimension, DateRange, TimeGranularity, Filter, FilterOperator, Order

`Cube`

Factory for creating measure, dimension, and segment references scoped to a cube name.

orders = Cube("orders")

str

required

The cube name as defined in the Cube.js schema.

Methods

(str) -> Measure

Create a Measure reference. Serializes to "cube_name.measure_name".

orders.measure("count")        # => "orders.count"
orders.measure("total_amount") # => "orders.total_amount"

(str) -> Dimension

Create a Dimension reference. Serializes to "cube_name.dimension_name".

orders.dimension("status")     # => "orders.status"
orders.dimension("created_at") # => "orders.created_at"

(str) -> Segment

Create a Segment reference. Serializes to "cube_name.segment_name".

orders.segment("completed") # => "orders.completed"

`Query`

Typed builder for Cube.js queries. Pass it to client.cube.load().

query = Query(
    measures=[orders.measure("count")],
    dimensions=[orders.dimension("status")],
    limit=100,
)

Parameters

List[Measure]

required

Measures to compute.

List[TimeDimension]

Time dimensions for filtering and grouping by time.

List[Dimension]

Dimensions for grouping results.

List[Filter]

Data filters to apply.

List[Segment]

Segments to apply.

int

default:"5000"

Maximum number of result rows.

int

default:"0"

Row offset for pagination.

List[Tuple[Dimension | Measure, Order]]

Ordering of result rows. Each element is a tuple of (member, direction).

order=[(orders.measure("count"), Order.desc)]

str

default:"\"UTC\""

IANA timezone name applied to time dimensions (e.g. "America/New_York").

bool

default:"False"

If True, skip GROUP BY in the generated SQL — returns raw rows.

`TimeDimension`

Combination of a time dimension reference, date range, and granularity.

td = TimeDimension(
    orders.dimension("created_at"),
    date_range=DateRange(relative="last 30 days"),
    granularity=TimeGranularity.month,
)

Dimension

required

Reference to a time-type dimension.

DateRange

Single date range for filtering. Provide either date_range or compare_date_range.

List[DateRange]

List of date ranges for period-over-period comparison.

compare_date_range=[
    DateRange(relative="this month"),
    DateRange(relative="last month"),
]

TimeGranularity

default:"TimeGranularity.null"

Grouping granularity. When null, no time grouping is applied (filter only).

`DateRange`

Absolute or relative date range for time-dimension filtering. Provide either (start_date, end_date) or relative.

str

Start of the absolute range (YYYY-MM-DD or ISO-8601).

str

End of the absolute range.

str

Relative date expression understood by Cube.js.

DateRange(relative="last 7 days")
DateRange(relative="this quarter")
DateRange(relative="from 6 months ago to now")

DateRange(start_date="2024-01-01", end_date="2024-03-31")

DateRange(relative="last 30 days")

`Filter`

A data filter applied to a measure or dimension.

f = Filter(
    orders.dimension("status"),
    FilterOperator.equals,
    values=["completed", "shipped"],
)

Dimension | Measure

required

The dimension or measure to filter on.

FilterOperator

required

The filter operator (see FilterOperator).

List[Any]

Filter values. Values are stringified during serialization. Not required for operators like is_set and not_set.

`And` / `Or`

Boolean filter expressions for combining multiple filters.

from iyree import And, Or, Filter, FilterOperator

combined = Or(
    Filter(orders.dimension("status"), FilterOperator.equals, ["completed"]),
    And(
        Filter(orders.dimension("region"), FilterOperator.equals, ["US"]),
        Filter(orders.measure("total_amount"), FilterOperator.gt, [1000]),
    ),
)

Filter | BooleanExpression

required

Any number of Filter, And, or Or instances.

Enums

`TimeGranularity`

Value	Description
`TimeGranularity.second`	Group by second
`TimeGranularity.minute`	Group by minute
`TimeGranularity.hour`	Group by hour
`TimeGranularity.day`	Group by day
`TimeGranularity.week`	Group by week
`TimeGranularity.month`	Group by month
`TimeGranularity.year`	Group by year
`TimeGranularity.null`	No grouping (default)

`Order`

Value	Description
`Order.asc`	Ascending
`Order.desc`	Descending

`FilterOperator`

Value	Serialized	Description
`FilterOperator.equals`	`equals`	Equal to
`FilterOperator.not_equals`	`notEquals`	Not equal to
`FilterOperator.contains`	`contains`	Contains substring
`FilterOperator.not_contains`	`notContains`	Does not contain
`FilterOperator.gt`	`gt`	Greater than
`FilterOperator.gte`	`gte`	Greater than or equal
`FilterOperator.lt`	`lt`	Less than
`FilterOperator.lte`	`lte`	Less than or equal
`FilterOperator.is_set`	`set`	Value is set (not null)
`FilterOperator.not_set`	`notSet`	Value is not set (null)
`FilterOperator.in_date_range`	`inDateRange`	Within date range
`FilterOperator.not_in_date_range`	`notInDateRange`	Outside date range
`FilterOperator.before_date`	`beforeDate`	Before date
`FilterOperator.after_date`	`afterDate`	After date

Examples

from iyree import (
    IyreeClient, Cube, Query, TimeDimension, DateRange,
    TimeGranularity, Filter, FilterOperator, Order,
)

orders = Cube("orders")

query = Query(
    measures=[orders.measure("count"), orders.measure("total_amount")],
    dimensions=[orders.dimension("status")],
    time_dimensions=[
        TimeDimension(
            orders.dimension("created_at"),
            date_range=DateRange(relative="last 30 days"),
            granularity=TimeGranularity.day,
        ),
    ],
    filters=[
        Filter(orders.dimension("status"), FilterOperator.not_equals, ["cancelled"]),
    ],
    order=[(orders.measure("total_amount"), Order.desc)],
    limit=1000,
    timezone="Europe/Moscow",
)

with IyreeClient(api_key="my-key") as client:
    result = client.cube.load(query)
    df = result.to_dataframe()
    print(df.head())

with IyreeClient(api_key="my-key") as client:
    result = client.cube.load({
        "measures": ["orders.count"],
        "dimensions": ["orders.status"],
        "timeDimensions": [{
            "dimension": "orders.created_at",
            "granularity": "day",
            "dateRange": "last 7 days",
        }],
    })
    for row in result.data:
        print(row)

from iyree import Cube, Query, TimeDimension, DateRange, TimeGranularity

orders = Cube("orders")

query = Query(
    measures=[orders.measure("count")],
    time_dimensions=[
        TimeDimension(
            orders.dimension("created_at"),
            compare_date_range=[
                DateRange(relative="this month"),
                DateRange(relative="last month"),
            ],
            granularity=TimeGranularity.day,
        ),
    ],
)

result = client.cube.load(query)

metadata = client.cube.meta()
for cube in metadata["cubes"]:
    print(f"Cube: {cube['name']}")
    for measure in cube.get("measures", []):
        print(f"  Measure: {measure['name']}")

from iyree import AsyncIyreeClient, Cube, Query

orders = Cube("orders")
query = Query(measures=[orders.measure("count")])

async with AsyncIyreeClient(api_key="my-key") as client:
    result = await client.cube.load(query)
    print(result.data)

Начало работы

Аналитика для ресторанов

BI функционал

Интеграции

Methods

`load`

Parameters

Returns `CubeQueryResult`

Result methods

Errors

`meta`

Parameters

Returns `Dict[str, Any]`

Query builder

`Cube`

Methods

`Query`

Parameters

`TimeDimension`

`DateRange`

`Filter`

`And` / `Or`

Enums

`TimeGranularity`

`Order`

`FilterOperator`

Examples

​Methods

​load

​Parameters

​Returns CubeQueryResult

​Result methods

​Errors

​meta

​Parameters

​Returns Dict[str, Any]

​Query builder

​Cube

​Methods

​Query

​Parameters

​TimeDimension

​DateRange

​Filter

​And / Or

​Enums

​TimeGranularity

​Order

​FilterOperator

​Examples

Methods

`load`

Parameters

Returns `CubeQueryResult`

Result methods

Errors

`meta`

Parameters

Returns `Dict[str, Any]`

Query builder

`Cube`

Methods

`Query`

Parameters

`TimeDimension`

`DateRange`

`Filter`

`And` / `Or`

Enums

`TimeGranularity`

`Order`

`FilterOperator`

Examples