0
# Client API
1

2
Core client classes providing the primary interface for executing queries, inserting data, and managing ClickHouse database connections. Supports both synchronous and asynchronous operations with comprehensive configuration options.
3

4
## Capabilities
5

6
### Client Factory Functions
7

8
Primary functions for creating client instances with full configuration support including authentication, security, compression, and connection management.
9

10
```python { .api }
11
def create_client(
12
    host: str | None = None,
13
    username: str | None = None,
14
    password: str = '',
15
    access_token: str | None = None,
16
    database: str = '__default__',
17
    interface: str | None = None,
18
    port: int = 0,
19
    secure: bool | str = False,
20
    dsn: str | None = None,
21
    settings: dict[str, Any] | None = None,
22
    generic_args: dict[str, Any] | None = None,
23
    compress: bool | str = False,
24
    query_limit: int = 0,
25
    connect_timeout: int = 10,
26
    send_receive_timeout: int = 300,
27
    client_name: str = '',
28
    verify: bool = True,
29
    ca_cert: str = '',
30
    client_cert: str = '',
31
    client_cert_key: str = '',
32
    session_id: str = '',
33
    pool_mgr = None,
34
    http_proxy: str = '',
35
    https_proxy: str = '',
36
    server_host_name: str = '',
37
    autogenerate_session_id: bool = None,
38
    **kwargs
39
) -> Client:
40
    """
41
    Create a synchronous ClickHouse client.
42
    
43
    Parameters:
44
    - host: ClickHouse server hostname/IP (default: localhost)
45
    - username: ClickHouse username (default: default user)
46
    - password: Password for username
47
    - access_token: JWT access token for ClickHouse Cloud
48
    - database: Default database name
49
    - interface: 'http' or 'https' (auto-detected from port/secure)
50
    - port: HTTP/HTTPS port (default: 8123/8443)
51
    - secure: Use HTTPS/TLS connection
52
    - dsn: Data Source Name string for connection parameters
53
    - settings: ClickHouse server settings dictionary
54
    - compress: Compression method (True/'lz4', 'zstd', 'brotli', 'gzip')
55
    - query_limit: Default LIMIT on returned rows (0 = no limit)
56
    - connect_timeout: HTTP connection timeout in seconds
57
    - send_receive_timeout: Read timeout in seconds
58
    - client_name: Client identifier for User-Agent header
59
    - verify: Verify server certificate in HTTPS mode
60
    - ca_cert: Certificate Authority root certificate file path
61
    - client_cert: TLS client certificate file path
62
    - client_cert_key: Private key for client certificate
63
    - session_id: ClickHouse session identifier
64
    - autogenerate_session_id: Auto-generate UUID session ID
65
    
66
    Returns:
67
    HttpClient instance implementing the Client interface
68
    """
69

70
async def create_async_client(
71
    executor_threads: int | None = None,
72
    **kwargs
73
) -> AsyncClient:
74
    """
75
    Create an asynchronous ClickHouse client.
76
    
77
    Parameters:
78
    - executor_threads: ThreadPoolExecutor max workers (default: 4 + CPU cores)
79
    - **kwargs: All parameters from create_client()
80
    
81
    Returns:
82
    AsyncClient wrapping a synchronous client with async interface
83
    """
84
```
85

86
### Base Client Class
87

88
Abstract base class defining the complete ClickHouse client interface with query execution, data insertion, and connection management methods.
89

90
```python { .api }
91
class Client:
92
    """Base ClickHouse Connect client interface."""
93
    
94
    # Connection management
95
    def ping(self) -> bool:
96
        """Test connection to ClickHouse server."""
97
    
98
    def close(self):
99
        """Close client connection."""
100
    
101
    def close_connections(self):
102
        """Close all pooled connections."""
103
    
104
    def min_version(self, version_str: str) -> bool:
105
        """Check if server version meets minimum requirement."""
106
    
107
    # Settings management
108
    def set_client_setting(self, key: str, value: Any):
109
        """Set ClickHouse client setting."""
110
    
111
    def get_client_setting(self, key: str) -> Any:
112
        """Get ClickHouse client setting value."""
113
    
114
    def set_access_token(self, access_token: str):
115
        """Update JWT access token."""
116
```
117

118
### Query Methods
119

120
Comprehensive query execution methods supporting multiple result formats, streaming, and parameter binding for flexible data retrieval.
121

122
```python { .api }
123
def query(
124
    self,
125
    query: str,
126
    parameters: dict | None = None,
127
    settings: dict | None = None,
128
    query_formats: dict | None = None,
129
    column_formats: dict | None = None,
130
    encoding: str = 'utf8',
131
    use_none: bool = True,
132
    max_str_len: int = 0,
133
    context: QueryContext | None = None,
134
    stream_context: StreamContext | None = None
135
) -> QueryResult:
136
    """
137
    Execute SELECT query and return results.
138
    
139
    Parameters:
140
    - query: SQL query string with optional parameter placeholders
141
    - parameters: Dictionary of query parameters
142
    - settings: ClickHouse settings for this query
143
    - query_formats: Column-specific format overrides
144
    - column_formats: Output format specifications
145
    - encoding: Text encoding for string columns
146
    - use_none: Return None for NULL values (vs default values)
147
    - max_str_len: Maximum string length (0 = unlimited)
148
    - context: Reusable query context
149
    - stream_context: Stream processing context
150
    
151
    Returns:
152
    QueryResult with result_set, column_names, column_types, and metadata
153
    """
154

155
def command(
156
    self,
157
    cmd: str,
158
    parameters: dict | None = None,
159
    data: Any = None,
160
    use_database: bool = True,
161
    session_id: str = ''
162
) -> Any:
163
    """
164
    Execute command and return single result value.
165
    
166
    Parameters:
167
    - cmd: Command string
168
    - parameters: Command parameters
169
    - data: Optional data payload
170
    - use_database: Include database in command context
171
    - session_id: Session identifier for command
172
    
173
    Returns:
174
    Single value result from command execution
175
    """
176

177
def raw_query(
178
    self,
179
    query: str,
180
    parameters: dict | None = None,
181
    settings: dict | None = None,
182
    fmt: str = 'Native',
183
    use_database: bool = True,
184
    session_id: str = ''
185
) -> bytes:
186
    """
187
    Execute query and return raw bytes result.
188
    
189
    Parameters:
190
    - query: SQL query string
191
    - parameters: Query parameters
192
    - settings: ClickHouse settings
193
    - fmt: ClickHouse output format
194
    - use_database: Use default database
195
    - session_id: Session identifier
196
    
197
    Returns:
198
    Raw bytes response from ClickHouse
199
    """
200
```
201

202
### Streaming Query Methods
203

204
High-performance streaming query methods for processing large datasets with configurable batch sizes and multiple output formats.
205

206
```python { .api }
207
def query_column_block_stream(
208
    self,
209
    query: str,
210
    parameters: dict | None = None,
211
    settings: dict | None = None,
212
    context: QueryContext | None = None
213
) -> Generator[Sequence[Sequence], None, None]:
214
    """
215
    Stream query results as column-oriented blocks.
216
    
217
    Yields:
218
    Column blocks where each block contains columns as sequences
219
    """
220

221
def query_row_block_stream(
222
    self,
223
    query: str,
224
    parameters: dict | None = None,
225
    settings: dict | None = None,
226
    context: QueryContext | None = None
227
) -> Generator[Sequence[Sequence], None, None]:
228
    """
229
    Stream query results as row-oriented blocks.
230
    
231
    Yields:
232
    Row blocks where each block contains multiple rows
233
    """
234

235
def query_rows_stream(
236
    self,
237
    query: str,
238
    parameters: dict | None = None,
239
    settings: dict | None = None,
240
    context: QueryContext | None = None
241
) -> Generator[Sequence, None, None]:
242
    """
243
    Stream query results as individual rows.
244
    
245
    Yields:
246
    Individual result rows
247
    """
248

249
def raw_stream(
250
    self,
251
    query: str,
252
    parameters: dict | None = None,
253
    settings: dict | None = None,
254
    fmt: str = 'Native',
255
    chunk_size: int = 8192
256
) -> Generator[bytes, None, None]:
257
    """
258
    Stream raw query results as bytes chunks.
259
    
260
    Parameters:
261
    - chunk_size: Size of each yielded chunk in bytes
262
    
263
    Yields:
264
    Raw bytes chunks from ClickHouse response
265
    """
266
```
267

268
### Insert Methods
269

270
Data insertion methods supporting various Python data structures and formats with comprehensive options for data type handling and batch processing.
271

272
```python { .api }
273
def insert(
274
    self,
275
    table: str,
276
    data: Sequence[Sequence] | BinaryIO,
277
    column_names: Sequence[str] | None = None,
278
    database: str = '',
279
    settings: dict | None = None,
280
    column_types_dict: dict | None = None,
281
    column_type_names: Sequence[str] | None = None,
282
    context: InsertContext | None = None,
283
    stream_context: StreamContext | None = None
284
):
285
    """
286
    Insert data into ClickHouse table.
287
    
288
    Parameters:
289
    - table: Target table name
290
    - data: Data as sequence of sequences or binary stream
291
    - column_names: List of column names (inferred if not provided)
292
    - database: Target database (uses client default if empty)
293
    - settings: ClickHouse settings for insert
294
    - column_types_dict: Column name to ClickHouse type mapping
295
    - column_type_names: Ordered list of ClickHouse type names
296
    - context: Reusable insert context
297
    - stream_context: Stream processing context
298
    """
299

300
def raw_insert(
301
    self,
302
    table: str,
303
    column_names: Sequence[str],
304
    insert_block: bytes | BinaryIO,
305
    settings: dict | None = None,
306
    column_types: Sequence[ClickHouseType] | None = None,
307
    database: str = ''
308
):
309
    """
310
    Insert pre-formatted binary data.
311
    
312
    Parameters:
313
    - table: Target table name
314
    - column_names: Column names for insert
315
    - insert_block: Pre-formatted binary data block
316
    - settings: ClickHouse settings
317
    - column_types: ClickHouse type objects for columns
318
    - database: Target database
319
    """
320
```
321

322
### Context Creation
323

324
Factory methods for creating reusable query and insert contexts to optimize repeated operations with similar parameters.
325

326
```python { .api }
327
def create_query_context(
328
    self,
329
    settings: dict | None = None,
330
    query_formats: dict | None = None,
331
    column_formats: dict | None = None,
332
    encoding: str = 'utf8',
333
    use_none: bool = True,
334
    max_str_len: int = 0,
335
    **kwargs
336
) -> QueryContext:
337
    """
338
    Create reusable query execution context.
339
    
340
    Returns:
341
    QueryContext object for repeated query operations
342
    """
343

344
def create_insert_context(
345
    self,
346
    table: str,
347
    column_names: Sequence[str] | None = None,
348
    database: str = '',
349
    settings: dict | None = None,
350
    column_types_dict: dict | None = None,
351
    **kwargs
352
) -> InsertContext:
353
    """
354
    Create reusable insert execution context.
355
    
356
    Returns:
357
    InsertContext object for repeated insert operations
358
    """
359
```
360

361
### HTTP Client Implementation
362

363
Concrete HTTP/HTTPS client implementation with connection pooling, compression, and advanced networking features.
364

365
```python { .api }
366
class HttpClient(Client):
367
    """HTTP/HTTPS implementation of ClickHouse client."""
368
    
369
    def __init__(
370
        self,
371
        interface: str,
372
        host: str,
373
        port: int,
374
        username: str,
375
        password: str,
376
        database: str,
377
        access_token: str = '',
378
        **kwargs
379
    ):
380
        """
381
        Initialize HTTP client with connection parameters.
382
        
383
        Additional HTTP-specific features:
384
        - Connection pooling via urllib3.PoolManager
385
        - Request/response compression
386
        - SSL/TLS certificate validation
387
        - HTTP proxy support
388
        - Custom User-Agent headers
389
        - Session management
390
        """
391
```
392

393
### Async Client Wrapper
394

395
Asynchronous client wrapper providing async/await interface using ThreadPoolExecutor for non-blocking database operations.
396

397
```python { .api }
398
class AsyncClient:
399
    """Asynchronous wrapper for ClickHouse client operations."""
400
    
401
    def __init__(
402
        self,
403
        client: Client,
404
        executor_threads: int | None = None
405
    ):
406
        """
407
        Initialize async client wrapper.
408
        
409
        Parameters:
410
        - client: Synchronous client instance to wrap
411
        - executor_threads: ThreadPoolExecutor max workers
412
        """
413
    
414
    async def query(self, *args, **kwargs) -> QueryResult:
415
        """Async version of query method."""
416
    
417
    async def insert(self, *args, **kwargs):
418
        """Async version of insert method."""
419
    
420
    async def command(self, *args, **kwargs) -> Any:
421
        """Async version of command method."""
422
    
423
    async def ping(self) -> bool:
424
        """Async version of ping method."""
425
    
426
    async def close(self):
427
        """Async version of close method."""
428
```
429

430
## Usage Examples
431

432
### Basic Query Operations
433

434
```python
435
import clickhouse_connect
436

437
# Create client
438
client = clickhouse_connect.create_client(host='localhost')
439

440
# Simple query
441
result = client.query('SELECT count() FROM system.tables')
442
row_count = result.first_item()
443
print(f"Tables: {row_count}")
444

445
# Parameterized query
446
result = client.query(
447
    'SELECT name, engine FROM system.tables WHERE database = {db:String}',
448
    parameters={'db': 'system'}
449
)
450

451
for table_name, engine in result.result_set:
452
    print(f"{table_name}: {engine}")
453

454
# Using command for single values
455
version = client.command('SELECT version()')
456
print(f"ClickHouse version: {version}")
457
```
458

459
### Advanced Query Configuration
460

461
```python
462
# Query with custom settings
463
result = client.query(
464
    'SELECT * FROM large_table',
465
    settings={
466
        'max_threads': 4,
467
        'max_memory_usage': '2G',
468
        'max_block_size': 65536
469
    },
470
    query_limit=1000
471
)
472

473
# Streaming large results
474
for row_block in client.query_row_block_stream(
475
    'SELECT * FROM huge_table',
476
    settings={'max_block_size': 10000}
477
):
478
    process_block(row_block)
479
```
480

481
### Data Insertion
482

483
```python
484
# Insert list data
485
data = [
486
    ['Alice', 25, 'Engineer'],
487
    ['Bob', 30, 'Manager'],
488
    ['Carol', 35, 'Developer']
489
]
490

491
client.insert(
492
    'employees',
493
    data,
494
    column_names=['name', 'age', 'role']
495
)
496

497
# Insert with type specification
498
client.insert(
499
    'metrics',
500
    data,
501
    column_names=['timestamp', 'value', 'label'],
502
    column_type_names=['DateTime', 'Float64', 'String']
503
)
504
```
505

506
### Async Operations
507

508
```python
509
import asyncio
510
import clickhouse_connect
511

512
async def async_operations():
513
    # Create async client
514
    client = await clickhouse_connect.create_async_client(
515
        host='localhost',
516
        executor_threads=8
517
    )
518
    
519
    # Async query
520
    result = await client.query('SELECT count() FROM events')
521
    print(f"Event count: {result.first_item()}")
522
    
523
    # Async insert
524
    await client.insert('logs', log_data, column_names=['timestamp', 'message'])
525
    
526
    # Close connection
527
    await client.close()
528

529
# Run async operations
530
asyncio.run(async_operations())
531
```
532

533
### Connection Management
534

535
```python
536
# Connection with custom settings
537
client = clickhouse_connect.create_client(
538
    host='clickhouse.example.com',
539
    username='analytics_user',
540
    password='secure_password',
541
    database='analytics',
542
    compress='lz4',
543
    settings={
544
        'max_threads': 8,
545
        'max_memory_usage': '4G'
546
    }
547
)
548

549
# Test connection
550
if client.ping():
551
    print("Connection successful")
552

553
# Check server capabilities
554
if client.min_version('21.8'):
555
    print("Server supports advanced features")
556

557
# Runtime setting changes
558
client.set_client_setting('send_progress_in_http_headers', 1)
559

560
# Clean shutdown
561
client.close()
562
```