New to the SDK?

Start with Quick Start — it shows how to install the package, connect to a database, and run your first query in under five minutes.

Then read Driver to understand how to configure the connection: which endpoint and database to use, how to authenticate, and how to set up TLS. Every service in the SDK is accessed through a Driver instance, so this page is the foundation for everything else.

LLM-ready Documentation

For AI-assisted coding, use llms.txt as the documentation index and llms-full.txt as the complete documentation context.

Running Queries

The Query Service page covers the Query service — the primary API for executing YQL statements. It explains QuerySessionPool, how to run DDL and DML, how to pass parameters safely, and how to work with transactions. Start here if you want to read or write data.

The YDB Types page is a companion to query: it shows how Python values map to YDB types and how to specify types explicitly when the automatic mapping is not enough.

Messaging

The Topic Service page covers the Topic service — a persistent message queue similar to Kafka. It explains how to create topics, write messages, read and commit them, and how topics integrate with transactions. Both synchronous and asynchronous patterns are covered.

Table Service

The Table Service page covers driver.table_client — the lower-level API for operations that cannot be expressed in YQL: creating tables with custom partitioning, TTL, secondary indexes, and column families; bulk loading data with bulk_upsert; point reads by primary key with read_rows; and streaming full-table reads with read_table. Use this alongside the Query service when you need fine-grained schema or data-loading control.

Distributed Coordination

The Coordination Service page covers distributed semaphores and leader election. If you need to limit concurrent access to a shared resource across multiple processes or hosts, this is the service to use.

Schema Management

The Scheme Service page covers driver.scheme_client — creating and removing directories, listing directory contents, and describing any path in the YDB hierarchy (tables, topics, coordination nodes, etc.).

Error Handling and Retries

The Errors and Retries page is important reading before going to production. YDB returns structured error codes, and the SDK’s retry logic depends on them. This page explains which errors are safe to retry, which are not, how to tune backoff settings, and how to use the @ydb_retry decorator. Skipping this section is a common source of production incidents.

Observability

The Observability page describes the SDK’s vendor-neutral tracing interface. Key operations — query sessions, transactions, and connection pool activity — are turned into spans and handed to whichever backend you install. OpenTelemetry is the built-in backend (OpenTelemetry), so one call to enable_tracing() lets you visualize request flow in Jaeger, Grafana, or any OpenTelemetry-compatible system — while the same interface lets you plug in a custom provider when you need one.

API Reference

The YDB API Reference page contains auto-generated documentation for all public classes and methods.