yandex-query-client

yandex-query-client is a Python SDK for Yandex Query, the serverless analytics service in Yandex Cloud. It wraps the Yandex Query HTTP API behind a small YQHttpClient, letting you submit analytical queries, track their execution status, and retrieve results without hand-rolling REST calls or polling logic.

Authentication uses a Yandex Cloud IAM token and a folder (project) ID supplied through a config object. The client creates queries, waits for them to succeed, and returns result sets complete with column names, types, and row values — ready to feed into pandas, which the package depends on for tabular handling.

What You Get

• A YQHttpClient with a YQHttpClientConfig for IAM-token and folder-scoped access
• Query creation, status polling, and a wait-for-success helper
• Retrieval of one or many result sets with column names, types, and rows
• IAM-token based authentication against the Yandex Cloud API
• pandas-friendly result handling for downstream analysis

Common Use Cases

• Running Yandex Query analytical queries from Python scripts or services
• Polling long-running queries until they complete and collecting results
• Integrating Yandex Query results into pandas-based data workflows
• Automating scheduled analytical jobs against Yandex Cloud data

Under The Hood

Architecture — The package is small and focused: src/yandex_query_client/http_client.py implements YQHttpClient and YQHttpClientConfig, driving the Yandex Query REST endpoints (create query, check status, fetch result sets) over requests, while query_results.py models the returned result sets with their columns, types, and rows. The public surface is re-exported from the package init, so the whole SDK is two modules of logic.

Tech Stack — Pure Python (targeting 3.8) built on requests and urllib3 for HTTP, python-dateutil for temporal parsing, and pandas for tabular result handling. Packaging is via pyproject.toml, with ruff and mypy configured for linting and typing.

Code Quality — The repository ships a pytest suite (test_http_client, test_query_results) using the responses library to mock the HTTP layer, and enforces style with a pinned ruff version and mypy plus typing stubs. The codebase is compact and readable, though project health signals (very low stars, no recent commits) indicate limited ongoing maintenance.

API Design — The API is deliberately linear and easy to follow: construct a config with an IAM token and folder ID, create a query, wait for it to succeed, then fetch result sets. The README’s end-to-end select example demonstrates the entire flow in a dozen lines, keeping the learning curve low for anyone already holding Yandex Cloud credentials.