0
# ClickHouse Driver
1

2
A high-performance Python driver for ClickHouse database with native interface support. Provides comprehensive database connectivity through both pure client and DB API 2.0 compatible interfaces, enabling efficient query execution, data type handling, and database operations with advanced features including external data processing, query settings configuration, compression, TLS security, and optional NumPy integration.
3

4
## Package Information
5

6
- **Package Name**: clickhouse-driver
7
- **Language**: Python
8
- **Installation**: `pip install clickhouse-driver`
9
- **Optional Dependencies**: 
10
  - LZ4 compression: `pip install clickhouse-driver[lz4]`
11
  - ZSTD compression: `pip install clickhouse-driver[zstd]`
12
  - NumPy integration: `pip install clickhouse-driver[numpy]`
13

14
## Core Imports
15

16
Standard client interface:
17

18
```python
19
from clickhouse_driver import Client
20
```
21

22
DB API 2.0 interface:
23

24
```python
25
from clickhouse_driver import connect
26
```
27

28
## Basic Usage
29

30
### Using the Client Interface
31

32
```python
33
from clickhouse_driver import Client
34

35
# Connect to ClickHouse
36
client = Client('localhost', user='default', password='', database='default')
37

38
# Execute queries
39
rows = client.execute('SELECT version()')
40
print(rows)
41

42
# Insert data
43
client.execute('CREATE TABLE test (id UInt32, name String) ENGINE = Memory')
44
client.execute('INSERT INTO test VALUES', [(1, 'Alice'), (2, 'Bob')])
45

46
# Query with parameters
47
result = client.execute('SELECT * FROM test WHERE id = %(user_id)s', {'user_id': 1})
48
print(result)
49

50
# Query with column types
51
result = client.execute('SELECT * FROM test', with_column_types=True)
52
columns_with_types, rows = result
53
print(columns_with_types)  # [('id', 'UInt32'), ('name', 'String')]
54
print(rows)  # [(1, 'Alice'), (2, 'Bob')]
55

56
# Disconnect
57
client.disconnect()
58
```
59

60
### Using the DB API 2.0 Interface
61

62
```python
63
from clickhouse_driver import connect
64

65
# Connect using DB API 2.0
66
conn = connect(host='localhost', user='default', password='', database='default')
67
cursor = conn.cursor()
68

69
# Execute queries
70
cursor.execute('SELECT version()')
71
result = cursor.fetchone()
72
print(result)
73

74
# Insert data with parameters
75
cursor.execute('INSERT INTO test VALUES', [(3, 'Charlie'), (4, 'Diana')])
76

77
# Query with fetchall
78
cursor.execute('SELECT * FROM test')
79
rows = cursor.fetchall()
80
print(rows)
81

82
# Close resources
83
cursor.close()
84
conn.close()
85
```
86

87
## Architecture
88

89
The driver provides two complementary interfaces:
90

91
- **Client Interface**: Direct ClickHouse operations with full feature access and advanced capabilities
92
- **DB API 2.0 Interface**: Standards-compliant database connectivity following Python Database API specification  
93
- **Column Type System**: Comprehensive data type support covering all ClickHouse types including complex nested structures
94
- **Result Processing**: Multiple result formats including streaming, progress tracking, and optional NumPy optimization
95
- **Connection Management**: Native TCP protocol with connection pooling, SSL/TLS support, and automatic reconnection
96

97
## Capabilities
98

99
### Client Interface
100

101
Direct ClickHouse client providing full access to native protocol features including streaming results, progress tracking, external tables, and advanced query settings.
102

103
```python { .api }
104
class Client:
105
    def __init__(self, host='localhost', port=9000, database='', user='default', 
106
                 password='', client_name='python-driver', **kwargs): ...
107
    def execute(self, query, params=None, with_column_types=False, 
108
                external_tables=None, query_id=None, settings=None, 
109
                types_check=False, columnar=False): ...
110
    def execute_with_progress(self, query, params=None, **kwargs): ...
111
    def execute_iter(self, query, params=None, **kwargs): ...
112
    def disconnect(self): ...
113
```
114

115
[Client Interface](./client-interface.md)
116

117
### DB API 2.0 Interface
118

119
Standards-compliant database connectivity following Python Database API specification with connection and cursor objects for familiar database interaction patterns.
120

121
```python { .api }
122
def connect(dsn=None, host=None, user='default', password='', 
123
            port=9000, database='', **kwargs):
124
    """Create a new database connection."""
125

126
class Connection:
127
    def cursor(self, cursor_factory=None): ...
128
    def close(self): ...
129
    def commit(self): ...  # No-op
130
    def rollback(self): ...  # No-op
131

132
class Cursor:
133
    def execute(self, operation, parameters=None): ...
134
    def executemany(self, operation, seq_of_parameters): ...
135
    def fetchone(self): ...
136
    def fetchmany(self, size=None): ...
137
    def fetchall(self): ...
138
```
139

140
[DB API Interface](./dbapi-interface.md)
141

142
### Data Types and Columns
143

144
Comprehensive support for all ClickHouse data types including integers, floats, strings, dates, arrays, tuples, maps, and specialized types like UUID, IP addresses, and geographic coordinates.
145

146
```python { .api }
147
# Integer types: Int8, Int16, Int32, Int64, Int128, Int256, UInt8, UInt16, UInt32, UInt64, UInt128, UInt256
148
# Float types: Float32, Float64  
149
# String types: String, FixedString
150
# Date/Time types: Date, Date32, DateTime (with timezone)
151
# Special types: UUID, IPv4, IPv6, Bool
152
# Container types: Array, Tuple, Map, Nested
153
# Advanced types: LowCardinality, JSON, Decimal, Enum
154
```
155

156
[Data Types](./data-types.md)
157

158
### Error Handling
159

160
Comprehensive exception hierarchy for ClickHouse-specific errors and standard DB API 2.0 exceptions, providing detailed error information including server error codes and nested exception handling.
161

162
```python { .api }
163
# Core exceptions
164
class Error(Exception): ...
165
class ServerException(Error): ...
166
class NetworkError(Error): ...
167
class TypeMismatchError(Error): ...
168

169
# DB API 2.0 exceptions  
170
class DatabaseError(Error): ...
171
class OperationalError(DatabaseError): ...
172
class ProgrammingError(DatabaseError): ...
173
class DataError(DatabaseError): ...
174
```
175

176
[Error Handling](./error-handling.md)
177

178
### Query Results and Data Processing
179

180
Multiple result formats including standard tuples, streaming iterators, progress tracking, and optional NumPy arrays for high-performance numerical computing workloads.
181

182
```python { .api }
183
class QueryResult:
184
    """Standard query result storage."""
185

186
class IterQueryResult:
187
    """Streaming query result iterator."""
188

189
class ProgressQueryResult:
190
    """Query result with progress information."""
191
```
192

193
[Results Processing](./results-processing.md)
194

195
### Compression and Performance
196

197
Built-in support for LZ4 and ZSTD compression algorithms with configurable block sizes, plus optional Cython extensions for performance-critical operations.
198

199
```python { .api }
200
# Compression support (requires extras)
201
# LZ4: pip install clickhouse-driver[lz4] 
202
# ZSTD: pip install clickhouse-driver[zstd]
203
```
204

205
[Compression](./compression.md)
206

207
## Types
208

209
```python { .api }
210
# Connection settings type
211
ConnectionSettings = Dict[str, Any]
212

213
# Client settings type  
214
ClientSettings = Dict[str, Any]
215

216
# Query parameters type
217
QueryParams = Dict[str, Any]
218

219
# External table definition
220
ExternalTable = Dict[str, Any]
221

222
# Column information tuple
223
ColumnInfo = Tuple[str, str]  # (name, type)
224
```