0
# YDB Python SDK
1

2
The official Python client for YDB (Yandex Database), a distributed SQL database. The SDK provides comprehensive functionality for table operations, query execution, transaction management, authentication, async operations, topic operations for streaming data, and integrations with SQLAlchemy and DB-API 2.0.
3

4
## Package Information
5

6
- **Package Name**: ydb
7
- **Language**: Python
8
- **Installation**: `pip install ydb`
9
- **Repository**: https://github.com/ydb-platform/ydb-python-sdk
10
- **Documentation**: https://ydb-platform.github.io/ydb-python-sdk
11

12
## Core Imports
13

14
```python
15
import ydb
16
```
17

18
Common patterns for specific functionality:
19

20
```python
21
# Core driver and connection
22
from ydb import Driver, DriverConfig
23

24
# Table operations and sessions
25
from ydb import SessionPool, Session, TxContext
26

27
# Data types
28
from ydb import types
29

30
# Async operations
31
import ydb.aio as ydb_aio
32

33
# Schema operations
34
from ydb import SchemeClient
35

36
# Query service
37
from ydb import QueryService
38

39
# Topic operations
40
from ydb import TopicClient
41

42
# Authentication
43
from ydb import AnonymousCredentials, StaticCredentials
44
import ydb.iam
45

46
# SQLAlchemy integration
47
import ydb.sqlalchemy
48

49
# DB-API 2.0 interface
50
import ydb.dbapi
51
```
52

53
## Basic Usage
54

55
### Simple Connection and Query
56

57
```python
58
import ydb
59

60
# Create driver with connection string
61
driver = ydb.Driver(
62
    endpoint="grpc://localhost:2136",
63
    database="/local",
64
    credentials=ydb.AnonymousCredentials()
65
)
66

67
# Wait for driver to be ready
68
driver.wait(fail_fast=True, timeout=5)
69

70
# Create session pool
71
session_pool = ydb.SessionPool(driver)
72

73
def execute_query(session):
74
    # Execute YQL query
75
    result_sets = session.transaction(ydb.SerializableReadWrite()).execute(
76
        "SELECT 1 AS value;",
77
        commit_tx=True
78
    )
79
    
80
    for result_set in result_sets:
81
        for row in result_set.rows:
82
            print(f"Value: {row.value}")
83

84
# Execute query using session pool
85
session_pool.retry_operation_sync(execute_query)
86

87
# Clean up
88
session_pool.stop()
89
driver.stop()
90
```
91

92
### Table Operations
93

94
```python
95
import ydb
96

97
# Create table
98
def create_table(session):
99
    session.create_table(
100
        '/local/test_table',
101
        ydb.TableDescription()
102
        .with_column(ydb.TableColumn('id', ydb.OptionalType(ydb.PrimitiveType.Uint64)))
103
        .with_column(ydb.TableColumn('name', ydb.OptionalType(ydb.PrimitiveType.Utf8)))
104
        .with_primary_key('id')
105
    )
106

107
session_pool.retry_operation_sync(create_table)
108
```
109

110
## Architecture
111

112
The YDB Python SDK is organized around several key components:
113

114
- **Driver**: Manages connections to YDB cluster and handles endpoint discovery
115
- **Session Pool**: Manages database sessions with automatic retry and failover
116
- **Query Execution**: Table service for traditional operations and Query service for modern SQL
117
- **Type System**: Complete type mapping between Python and YDB data types
118
- **Authentication**: Multiple credential providers including OAuth2, JWT, and service accounts
119
- **Async Support**: Full async/await interface through `ydb.aio` module
120
- **Integrations**: SQLAlchemy dialect and DB-API 2.0 compliant interface
121

122
## Capabilities
123

124
### Driver and Connection Management
125

126
Core connection functionality including driver configuration, endpoint discovery, credential management, and connection lifecycle.
127

128
```python { .api }
129
class Driver:
130
    def __init__(self, endpoint: str, database: str, credentials: Credentials = None, **kwargs): ...
131
    def wait(self, fail_fast: bool = True, timeout: float = None) -> bool: ...
132
    def stop(self, timeout: float = None): ...
133

134
class DriverConfig:
135
    def __init__(self, endpoint: str, database: str, credentials: Credentials = None, **kwargs): ...
136

137
def construct_driver(config: DriverConfig) -> Driver: ...
138
def construct_driver_from_string(connection_string: str, **kwargs) -> Driver: ...
139
```
140

141
[Driver and Connection Management](./driver-connection.md)
142

143
### Authentication and Credentials
144

145
Complete authentication system supporting anonymous access, static tokens, OAuth2 token exchange, JWT authentication, service account credentials, and Yandex Cloud IAM integration.
146

147
```python { .api }
148
class AnonymousCredentials(Credentials): ...
149

150
class StaticCredentials(Credentials):
151
    def __init__(self, token: str): ...
152

153
class OAuth2TokenExchangeCredentials(Credentials):
154
    def __init__(self, token_endpoint: str, **kwargs): ...
155

156
def credentials_from_env_variables() -> Credentials: ...
157
def default_credentials(credentials: Credentials = None) -> Credentials: ...
158
```
159

160
[Authentication and Credentials](./authentication.md)
161

162
### Table Operations and Sessions
163

164
Comprehensive table operations including session management, transaction handling, query execution, table creation/modification, bulk operations, and point reads.
165

166
```python { .api }
167
class SessionPool:
168
    def __init__(self, driver: Driver, size: int = None): ...
169
    def retry_operation_sync(self, callee: callable, *args, **kwargs): ...
170
    def acquire(self, timeout: float = None) -> Session: ...
171

172
class Session:
173
    def execute_query(self, query: str, parameters: dict = None, **kwargs): ...
174
    def create_table(self, path: str, table_description: TableDescription, **kwargs): ...
175
    def transaction(self, tx_mode: TxMode = None) -> TxContext: ...
176

177
class TxContext:
178
    def execute(self, query: str, parameters: dict = None, commit_tx: bool = False): ...
179
    def commit(self): ...
180
    def rollback(self): ...
181
```
182

183
[Table Operations and Sessions](./table-operations.md)
184

185
### Data Types and Conversion
186

187
Complete type system mapping Python types to YDB types, including primitives, optionals, containers, and advanced types like decimals and variants.
188

189
```python { .api }
190
class PrimitiveType:
191
    Bool: Type
192
    Int8: Type
193
    Uint8: Type
194
    Int16: Type
195
    Uint16: Type
196
    Int32: Type
197
    Uint32: Type
198
    Int64: Type
199
    Uint64: Type
200
    Float: Type
201
    Double: Type
202
    String: Type
203
    Utf8: Type
204
    Yson: Type
205
    Json: Type
206
    Uuid: Type
207
    Date: Type
208
    Datetime: Type
209
    Timestamp: Type
210
    Interval: Type
211

212
def Optional(item_type: Type) -> OptionalType: ...
213
def List(item_type: Type) -> ListType: ...
214
def Tuple(*item_types: Type) -> TupleType: ...
215
def Struct(**kwargs: Type) -> StructType: ...
216
def Dict(key_type: Type, value_type: Type) -> DictType: ...
217
```
218

219
[Data Types and Conversion](./data-types.md)
220

221
### Query Service Operations
222

223
Modern query interface supporting session management, transaction execution, result streaming, and advanced query options with the new Query service.
224

225
```python { .api }
226
class QueryService:
227
    def __init__(self, driver: Driver): ...
228

229
class QuerySession:
230
    def execute_query(self, query: str, **kwargs): ...
231
    def transaction(self, tx_settings: TxSettings = None) -> QueryTransaction: ...
232

233
class QueryTransaction:
234
    def execute(self, query: str, parameters: dict = None): ...
235
    def commit(self): ...
236
    def rollback(self): ...
237
```
238

239
[Query Service Operations](./query-service.md)
240

241
### Async Operations
242

243
Full async/await interface providing asynchronous versions of all core functionality through the `ydb.aio` module.
244

245
```python { .api }
246
import ydb.aio as ydb_aio
247

248
class Driver:
249
    async def __aenter__(self) -> 'Driver': ...
250
    async def __aexit__(self, *args): ...
251
    async def wait(self, fail_fast: bool = True, timeout: float = None) -> bool: ...
252

253
class SessionPool:
254
    async def acquire(self, timeout: float = None) -> Session: ...
255
    async def retry_operation(self, callee: callable, *args, **kwargs): ...
256

257
class Session:
258
    async def execute_query(self, query: str, parameters: dict = None, **kwargs): ...
259
    async def create_table(self, path: str, table_description: TableDescription, **kwargs): ...
260
```
261

262
[Async Operations](./async-operations.md)
263

264
### Schema Operations
265

266
Database schema management including directory operations, table schema inspection, permissions management, and metadata operations.
267

268
```python { .api }
269
class SchemeClient:
270
    def __init__(self, driver: Driver): ...
271
    def make_directory(self, path: str, **kwargs): ...
272
    def remove_directory(self, path: str, **kwargs): ...
273
    def list_directory(self, path: str, **kwargs): ...
274
    def describe_path(self, path: str, **kwargs): ...
275

276
class SchemeEntry:
277
    name: str
278
    type: SchemeEntryType
279
    is_directory: bool
280
    is_table: bool
281

282
class TableDescription:
283
    def with_column(self, column: TableColumn) -> 'TableDescription': ...
284
    def with_primary_key(self, *key_names: str) -> 'TableDescription': ...
285
```
286

287
[Schema Operations](./schema-operations.md)
288

289
### Topic Operations
290

291
Streaming data operations including topic creation, message publishing, message consuming, and topic administration.
292

293
```python { .api }
294
class TopicClient:
295
    def __init__(self, driver: Driver): ...
296

297
class TopicWriter:
298
    def __init__(self, driver: Driver, topic_path: str, **kwargs): ...
299
    def write(self, messages: List[ProducerMessage]): ...
300
    def flush(self): ...
301

302
class TopicReader:
303
    def __init__(self, driver: Driver, **kwargs): ...
304
    def receive_message(self) -> Message: ...
305
    def commit(self, message: Message): ...
306

307
class ProducerMessage:
308
    def __init__(self, data: bytes, **kwargs): ...
309
```
310

311
[Topic Operations](./topic-operations.md)
312

313
### Error Handling and Retries
314

315
Comprehensive error handling with detailed error hierarchies, retry strategies, backoff configurations, and operation result processing.
316

317
```python { .api }
318
class Error(Exception):
319
    status: int
320
    message: str
321
    issues: List[Issue]
322

323
class RetryableError(Error): ...
324
class BadRequestError(Error): ...
325
class UnauthorizedError(Error): ...
326
class NotFoundError(Error): ...
327
class AlreadyExistsError(Error): ...
328

329
class RetrySettings:
330
    def __init__(self, max_retries: int = 10, **kwargs): ...
331

332
class BackoffSettings:
333
    def __init__(self, max_backoff: float = 32.0, **kwargs): ...
334

335
def retry_operation_sync(callee: callable, retry_settings: RetrySettings = None, *args, **kwargs): ...
336
```
337

338
[Error Handling and Retries](./error-handling.md)
339

340
### SQLAlchemy Integration
341

342
SQLAlchemy dialect for YDB enabling ORM usage, custom YDB types, connection management, and standard SQLAlchemy operations.
343

344
```python { .api }
345
import ydb.sqlalchemy
346

347
def register_dialect(): ...
348

349
class UInt32(Integer): ...
350
class UInt64(Integer): ...
351
class UInt8(Integer): ...
352

353
# Connection string format
354
# ydb://endpoint/database?param=value
355
```
356

357
[SQLAlchemy Integration](./sqlalchemy-integration.md)
358

359
### DB-API 2.0 Interface
360

361
Standard Python DB-API 2.0 compliant interface providing familiar database connectivity patterns.
362

363
```python { .api }
364
import ydb.dbapi
365

366
def connect(endpoint: str, database: str, **kwargs) -> Connection: ...
367

368
class Connection:
369
    def cursor(self) -> Cursor: ...
370
    def commit(self): ...
371
    def rollback(self): ...
372
    def close(self): ...
373

374
class Cursor:
375
    def execute(self, query: str, parameters: tuple = None): ...
376
    def executemany(self, query: str, seq_of_parameters: List[tuple]): ...
377
    def fetchone(self) -> tuple: ...
378
    def fetchall(self) -> List[tuple]: ...
379
    def fetchmany(self, size: int = None) -> List[tuple]: ...
380
```
381

382
[DB-API 2.0 Interface](./dbapi-interface.md)
383

384
### Scripting Operations
385

386
YQL script execution and management for running complex analytical queries and operations outside of table service.
387

388
```python { .api }
389
class ScriptingClient:
390
    def __init__(self, driver: Driver): ...
391
    def execute_yql_script(self, yql_script: str, **kwargs): ...
392
    def explain_yql_script(self, yql_script: str, **kwargs): ...
393

394
class YqlQueryResult:
395
    result_sets: List[ResultSet]
396
    status: int
397

398
class YqlExplainResult:
399
    plan: str
400
    ast: str
401
```
402

403
### Operation Management
404

405
Management of long-running operations including export/import operations and other asynchronous tasks.
406

407
```python { .api }
408
class Operation:
409
    def __init__(self, operation_id: str, driver: Driver): ...
410
    def cancel(self): ...
411
    def forget(self): ...
412
    def get(self): ...
413

414
class OperationClient:
415
    def __init__(self, driver: Driver): ...
416
    def cancel_operation(self, operation: Operation): ...
417
    def forget_operation(self, operation: Operation): ...
418
    def get_operation(self, operation: Operation): ...
419
```
420

421
### Export and Import Operations
422

423
Data export to external systems (S3, Yandex Object Storage) and import from external sources.
424

425
```python { .api }
426
class ExportToS3Settings:
427
    def __init__(self, endpoint: str, bucket: str, **kwargs): ...
428

429
class ExportToS3Operation(Operation):
430
    def __init__(self, driver: Driver, source_path: str, settings: ExportToS3Settings): ...
431

432
class ImportFromS3Settings:
433
    def __init__(self, endpoint: str, bucket: str, **kwargs): ...
434

435
class ImportFromS3Operation(Operation):
436
    def __init__(self, driver: Driver, destination_path: str, settings: ImportFromS3Settings): ...
437

438
class ExportProgress:
439
    UNSPECIFIED: int
440
    PREPARING: int
441
    TRANSFER_DATA: int
442
    DONE: int
443
    CANCELLATION: int
444
    CANCELLED: int
445

446
class ImportProgress:
447
    UNSPECIFIED: int
448
    PREPARING: int
449
    TRANSFER_DATA: int
450
    BUILD_INDEXES: int
451
    DONE: int
452
    CANCELLATION: int
453
    CANCELLED: int
454
```
455

456
### Retry Configuration
457

458
Configurable retry logic and backoff strategies for handling transient failures.
459

460
```python { .api }
461
class RetrySettings:
462
    def __init__(self, max_retries: int = 10, **kwargs): ...
463

464
class BackoffSettings:
465
    def __init__(self, max_backoff: float = 32.0, **kwargs): ...
466

467
def retry_operation_sync(callee: callable, retry_settings: RetrySettings = None, *args, **kwargs): ...
468
def retry_operation_async(callee: callable, retry_settings: RetrySettings = None, *args, **kwargs): ...
469
```
470

471
### Tracing Support
472

473
Distributed tracing integration for monitoring and debugging database operations.
474

475
```python { .api }
476
class Tracer:
477
    def __init__(self, **kwargs): ...
478

479
class TraceLevel:
480
    OFF: int
481
    ERROR: int
482
    WARN: int
483
    INFO: int
484
    DEBUG: int
485
    TRACE: int
486
```
487

488
### Global Settings
489

490
Global configuration options affecting SDK behavior across all operations.
491

492
```python { .api }
493
def global_allow_truncated_result(enabled: bool): ...
494
def global_allow_split_transactions(enabled: bool): ...
495
```
496

497
## Common Types
498

499
```python { .api }
500
# Transaction modes
501
class TxMode:
502
    SERIALIZABLE_RW: TxMode
503
    ONLINE_RO: TxMode
504
    STALE_RO: TxMode
505
    SNAPSHOT_RO: TxMode
506

507
# Time units
508
class Unit:
509
    SECONDS: Unit
510
    MILLISECONDS: Unit
511
    MICROSECONDS: Unit
512
    NANOSECONDS: Unit
513

514
# Schema entry types  
515
class SchemeEntryType:
516
    DIRECTORY: SchemeEntryType
517
    TABLE: SchemeEntryType
518
    TOPIC: SchemeEntryType
519
    DATABASE: SchemeEntryType
520

521
# RPC compression options
522
class RPCCompression:
523
    NoCompression: int
524
    Deflate: int
525
    Gzip: int
526
```