IYREE Python SDK

Python SDK for the IYREE BI analytics platform

The IYREE Python SDK provides a convenient interface to the IYREE platform, including data warehouse (StarRocks), Cube.js analytics, S3 object storage, and a key-value store.

Installation

pip install iyree

To enable pandas integration (DataFrame support in DWH, Cube, and S3):

pip install iyree[pandas]

Requires Python 3.9 or later.

Initialization

There are two ways to use the SDK: module-level (global client) or explicit client instances.

Module-level

Call iyree.init() once, then access sub-clients directly on the iyree module.

import iyree

iyree.init(api_key="my-key", gateway_host="https://public-api.iyree.ru")

result = iyree.dwh.sql("SELECT 1")
iyree.close()

Explicit client (recommended)

Create an IyreeClient instance. Use it as a context manager to ensure resources are released.

from iyree import IyreeClient

with IyreeClient(api_key="my-key", gateway_host="https://public-api.iyree.ru") as client:
    result = client.dwh.sql("SELECT * FROM orders LIMIT 10")
    for row in result.to_dicts():
        print(row)

Async client

For asyncio applications, use AsyncIyreeClient. All methods are await-able.

from iyree import AsyncIyreeClient

async with AsyncIyreeClient(api_key="my-key") as client:
    result = await client.dwh.sql("SELECT 1 AS n")
    print(result.to_dicts())

---

Configuration

api_key · str · required

API key for gateway authentication. Sent as the x-api-key header.

gateway_host · str

Gateway base URL (e.g. https://public-api.iyree.ru). Falls back to the IYREE_GATEWAY_HOST environment variable. If the value does not start with http:// or https://, https:// is prepended automatically.

timeout · float · default: "30.0"

Default HTTP request timeout in seconds.

stream_load_timeout · float · default: "300.0"

Timeout for DWH Stream Load (insert) operations in seconds.

cube_continue_wait_timeout · float · default: "120.0"

Maximum duration in seconds for Cube “Continue wait” polling.

max_retries · int · default: "3"

Maximum retry attempts for retryable errors (timeouts, transport errors, HTTP 429/502/503/504).

---

Sub-clients

After initialization, access the four sub-clients as properties:

Property	Description
client.dwh	DWH — SQL queries and Stream Load inserts (StarRocks)
client.cube	Cube — Cube.js analytics queries with a typed query builder
client.s3	S3 — Object storage (upload, download, list, copy, delete)
client.kv	KV — Key-Value document store

---

Error handling

All SDK exceptions inherit from IyreeError. Catch specific subclasses for fine-grained control.

from iyree import IyreeClient, IyreeAuthError, IyreeNotFoundError

try:
    with IyreeClient(api_key="my-key") as client:
        doc = client.kv.get("store", "missing-key")
except IyreeAuthError:
    print("Invalid API key")
except IyreeNotFoundError:
    print("Document not found")

Exception hierarchy

Exception	Trigger
IyreeError	Base exception for all SDK errors
IyreeConfigError	Invalid or incomplete configuration
IyreeAuthError	HTTP 401 — invalid or missing API key
IyreePermissionError	HTTP 403 — insufficient permissions
IyreeNotFoundError	HTTP 404 — resource not found
IyreeValidationError	HTTP 422 — request failed server-side validation
IyreeRateLimitError	HTTP 429 — rate limit exceeded (after retries)
IyreeServerError	HTTP 5xx — server error (after retries)
IyreeTimeoutError	Request timed out
IyreeStreamLoadError	DWH Stream Load status is not Success
IyreeDuplicateLabelError	Stream Load label already exists (extends IyreeStreamLoadError)
IyreeCubeTimeoutError	Cube continue-wait polling exceeded timeout
IyreeS3Error	S3 presigned-URL operation failed

Each exception exposes .message, .status_code, and .response_body attributes.