0
# Data Types and Columns
1

2
Comprehensive support for all ClickHouse data types including integers, floats, strings, dates, arrays, tuples, maps, and specialized types. The driver handles automatic conversion between ClickHouse types and Python objects while preserving precision and supporting complex nested data structures.
3

4
## Capabilities
5

6
### Integer Types
7

8
Full range of signed and unsigned integer types supporting small values to large precision integers.
9

10
```python { .api }
11
# Signed integers
12
Int8Column     # -128 to 127
13
Int16Column    # -32,768 to 32,767  
14
Int32Column    # -2^31 to 2^31-1
15
Int64Column    # -2^63 to 2^63-1
16
Int128Column   # -2^127 to 2^127-1
17
Int256Column   # -2^255 to 2^255-1
18

19
# Unsigned integers  
20
UInt8Column    # 0 to 255
21
UInt16Column   # 0 to 65,535
22
UInt32Column   # 0 to 2^32-1
23
UInt64Column   # 0 to 2^64-1
24
UInt128Column  # 0 to 2^128-1
25
UInt256Column  # 0 to 2^256-1
26

27
# Python mapping
28
# Int8-Int64 → Python int
29
# UInt8-UInt64 → Python int  
30
# Int128, Int256, UInt128, UInt256 → Python int (arbitrary precision)
31
```
32

33
### Floating Point Types
34

35
IEEE 754 floating point numbers with single and double precision.
36

37
```python { .api }
38
Float32Column  # 32-bit IEEE 754 floating point
39
Float64Column  # 64-bit IEEE 754 floating point
40

41
# Python mapping
42
# Float32 → Python float (may lose precision)
43
# Float64 → Python float
44
```
45

46
### String Types
47

48
Variable and fixed-length string types with configurable encoding support.
49

50
```python { .api }
51
StringColumn      # Variable-length UTF-8 strings
52
FixedStringColumn # Fixed-length byte arrays
53

54
# Python mapping
55
# String → Python str (UTF-8 by default, configurable encoding)
56
# FixedString → Python str (padded with null bytes)
57

58
# Encoding configuration (client settings)
59
settings = {
60
    'strings_encoding': 'utf-8',    # String encoding (default: utf-8)
61
    'strings_as_bytes': False,      # Return bytes instead of str
62
}
63
```
64

65
### Date and DateTime Types
66

67
Date and timestamp types with timezone support and extended ranges.
68

69
```python { .api }
70
DateColumn       # Date from 1900-01-01 to 2299-12-31
71
Date32Column     # Extended date range from 1900-01-01 to 2283-11-11
72
DateTimeColumn   # Unix timestamp with optional timezone
73

74
# Constructor for timezone-aware datetime
75
DateTimeColumn(timezone_name='UTC')           # UTC timezone
76
DateTimeColumn(timezone_name='Europe/London') # Named timezone
77

78
# Python mapping
79
# Date → datetime.date
80
# Date32 → datetime.date  
81
# DateTime → datetime.datetime (timezone-aware if specified)
82
```
83

84
### Boolean Type
85

86
Native boolean type support with true/false values.
87

88
```python { .api }
89
BoolColumn  # Boolean true/false values
90

91
# Python mapping
92
# Bool → Python bool
93
```
94

95
### UUID Type
96

97
Universally Unique Identifier type with automatic format handling.
98

99
```python { .api }
100
UUIDColumn  # 128-bit UUID values
101

102
# Python mapping  
103
# UUID → uuid.UUID object
104
# Accepts: UUID objects, hex strings with/without hyphens
105
```
106

107
### IP Address Types
108

109
Specialized types for IPv4 and IPv6 addresses with automatic validation.
110

111
```python { .api }
112
IPv4Column  # 32-bit IPv4 addresses
113
IPv6Column  # 128-bit IPv6 addresses
114

115
# Python mapping
116
# IPv4 → ipaddress.IPv4Address
117
# IPv6 → ipaddress.IPv6Address
118
# Accepts: IP address objects, string representations
119
```
120

121
### Decimal Types
122

123
High-precision decimal numbers with configurable precision and scale.
124

125
```python { .api }
126
DecimalColumn(precision, scale)  # Fixed-point decimal numbers
127

128
# Parameters
129
# precision: Total number of digits (1-76)
130
# scale: Number of digits after decimal point (0-precision)
131

132
# Examples
133
DecimalColumn(10, 2)  # Up to 10 digits, 2 after decimal (money)
134
DecimalColumn(18, 6)  # Up to 18 digits, 6 after decimal (scientific)
135

136
# Python mapping
137
# Decimal → decimal.Decimal (exact precision)
138
```
139

140
### Enum Types
141

142
Enumeration types mapping string values to integer codes.
143

144
```python { .api }
145
EnumColumn(enum_values)  # String-to-integer enumeration
146

147
# Parameters
148
# enum_values: Dict mapping string names to integer values
149
# Example: {'red': 1, 'green': 2, 'blue': 3}
150

151
# Python mapping
152
# Enum → str (enum name) or int (enum value)
153
```
154

155
### Array Types
156

157
Dynamic arrays containing elements of a single type with arbitrary nesting.
158

159
```python { .api }
160
ArrayColumn(inner_column)  # Arrays of any ClickHouse type
161

162
# Examples
163
ArrayColumn(Int32Column())           # Array of integers
164
ArrayColumn(StringColumn())          # Array of strings  
165
ArrayColumn(ArrayColumn(Float64Column()))  # Nested arrays
166

167
# Python mapping
168
# Array → Python list
169
# Supports arbitrary nesting: [[1, 2], [3, 4], [5, 6]]
170
```
171

172
### Tuple Types
173

174
Fixed-size heterogeneous tuples with named or unnamed elements.
175

176
```python { .api }
177
TupleColumn(inner_columns)  # Fixed-size heterogeneous tuples
178

179
# Parameters
180
# inner_columns: List of column types for tuple elements
181

182
# Examples
183
TupleColumn([Int32Column(), StringColumn()])           # (int, str)
184
TupleColumn([Float64Column(), Float64Column()])        # (float, float) 
185
TupleColumn([StringColumn(), ArrayColumn(Int32Column())])  # (str, [int])
186

187
# Python mapping
188
# Tuple → Python tuple
189
# Example: (42, 'hello') for Tuple(Int32, String)
190
```
191

192
### Map Types
193

194
Key-value associative containers with typed keys and values.
195

196
```python { .api }
197
MapColumn(key_column, value_column)  # Key-value maps
198

199
# Parameters  
200
# key_column: Column type for map keys
201
# value_column: Column type for map values
202

203
# Examples
204
MapColumn(StringColumn(), Int32Column())      # Map[str, int]
205
MapColumn(Int32Column(), ArrayColumn(StringColumn()))  # Map[int, List[str]]
206

207
# Python mapping
208
# Map → Python dict
209
# Example: {'key1': 123, 'key2': 456}
210
```
211

212
### Nested Types
213

214
Complex nested structures for hierarchical data representation.
215

216
```python { .api }
217
NestedColumn(inner_columns)  # Nested table structures
218

219
# Parameters
220
# inner_columns: Dict mapping column names to column types
221

222
# Example
223
NestedColumn({
224
    'user_id': UInt32Column(),
225
    'user_name': StringColumn(),
226
    'user_tags': ArrayColumn(StringColumn())
227
})
228

229
# Python mapping
230
# Nested → List of dicts with consistent structure
231
# Example: [
232
#     {'user_id': 1, 'user_name': 'Alice', 'user_tags': ['admin', 'user']},
233
#     {'user_id': 2, 'user_name': 'Bob', 'user_tags': ['user']}
234
# ]
235
```
236

237
### Nullable Types
238

239
Wrapper allowing NULL values for any ClickHouse type.
240

241
```python { .api }
242
NullableColumn(inner_column)  # NULL-aware wrapper for any type
243

244
# Examples
245
NullableColumn(Int32Column())     # Nullable integer
246
NullableColumn(StringColumn())    # Nullable string
247
NullableColumn(ArrayColumn(Int32Column()))  # Nullable array
248

249
# Python mapping
250
# Nullable → Python value or None
251
# Example: 42 or None for Nullable(Int32)
252
```
253

254
### Low Cardinality Types
255

256
Optimization for columns with low unique value count using dictionary encoding.
257

258
```python { .api }
259
LowCardinalityColumn(inner_column)  # Dictionary-encoded optimization
260

261
# Best for columns with < 10,000 unique values
262
# Examples
263
LowCardinalityColumn(StringColumn())  # Country names, categories
264
LowCardinalityColumn(EnumColumn({'A': 1, 'B': 2}))  # Small enums
265

266
# Python mapping
267
# LowCardinality → Same as inner column type
268
# Transparent optimization, no API differences
269
```
270

271
### JSON Type
272

273
Semi-structured JSON data with dynamic schema support.
274

275
```python { .api }
276
JSONColumn  # JSON objects and arrays
277

278
# Python mapping
279
# JSON → Python dict, list, or primitive types
280
# Supports nested structures: {'key': [1, 2, {'nested': True}]}
281
```
282

283
### Interval Types
284

285
Time interval types for duration calculations.
286

287
```python { .api }
288
IntervalYearColumn     # Year intervals
289
IntervalMonthColumn    # Month intervals  
290
IntervalWeekColumn     # Week intervals
291
IntervalDayColumn      # Day intervals
292
IntervalHourColumn     # Hour intervals
293
IntervalMinuteColumn   # Minute intervals
294
IntervalSecondColumn   # Second intervals
295

296
# Python mapping
297
# Interval → datetime.timedelta (where applicable)
298
# Year/Month intervals → custom interval objects (no standard Python equivalent)
299
```
300

301
### Special Types
302

303
Additional specialized types for specific use cases.
304

305
```python { .api }
306
NothingColumn  # Represents absence of data
307
NullColumn     # Always NULL values
308

309
# Aggregate function storage
310
SimpleAggregateFunctionColumn(function_name, inner_columns)
311

312
# Python mapping
313
# Nothing → None
314
# Null → None
315
# SimpleAggregateFunction → Depends on function type
316
```
317

318
### Geographic Type Aliases
319

320
Convenient aliases for geographic coordinate systems.
321

322
```python { .api }
323
# Type aliases using Tuple compositions
324
Point = TupleColumn([Float64Column(), Float64Column()])           # (x, y)
325
Ring = ArrayColumn(Point)                                        # Array of points
326
Polygon = ArrayColumn(Ring)                                      # Array of rings  
327
MultiPolygon = ArrayColumn(Polygon)                             # Array of polygons
328

329
# Python mapping
330
# Point → (float, float)
331
# Ring → [(x1, y1), (x2, y2), ...]
332
# Polygon → [[(x1, y1), (x2, y2), ...], [...]]  # outer ring + holes
333
# MultiPolygon → [[ring1, ring2], [ring3, ring4], ...]
334
```
335

336
## Type Conversion Examples
337

338
### Basic Type Usage
339

340
```python
341
from clickhouse_driver import Client
342

343
client = Client('localhost')
344

345
# Integer types
346
client.execute('CREATE TABLE test_ints (i8 Int8, u64 UInt64) ENGINE = Memory')
347
client.execute('INSERT INTO test_ints VALUES', [(-128, 18446744073709551615)])
348

349
# String and UUID
350
client.execute('''
351
    CREATE TABLE test_strings (
352
        name String,
353
        id UUID,
354
        fixed FixedString(10)
355
    ) ENGINE = Memory
356
''')
357

358
import uuid
359
data = [
360
    ('Alice', uuid.uuid4(), 'fixed_data'),
361
    ('Bob', uuid.uuid4(), 'test12345\x00')  # Null-padded to 10 bytes
362
]
363
client.execute('INSERT INTO test_strings VALUES', data)
364
```
365

366
### Date and DateTime Usage
367

368
```python
369
from datetime import date, datetime
370
import pytz
371

372
# Date types
373
client.execute('''
374
    CREATE TABLE test_dates (
375
        simple_date Date,
376
        extended_date Date32,
377
        timestamp DateTime,
378
        utc_time DateTime('UTC'),
379
        london_time DateTime('Europe/London')
380
    ) ENGINE = Memory
381
''')
382

383
utc = pytz.UTC
384
london = pytz.timezone('Europe/London')
385

386
data = [(
387
    date(2023, 1, 15),
388
    date(2100, 12, 31),
389
    datetime(2023, 1, 15, 14, 30, 0),
390
    datetime(2023, 1, 15, 14, 30, 0, tzinfo=utc),
391
    datetime(2023, 1, 15, 14, 30, 0, tzinfo=london)
392
)]
393

394
client.execute('INSERT INTO test_dates VALUES', data)
395
```
396

397
### Complex Types Usage
398

399
```python
400
# Arrays and tuples
401
client.execute('''
402
    CREATE TABLE test_complex (
403
        numbers Array(Int32),
404
        coordinates Tuple(Float64, Float64),
405
        nested_arrays Array(Array(String)),
406
        key_values Map(String, Int32)
407
    ) ENGINE = Memory
408
''')
409

410
data = [(
411
    [1, 2, 3, 4, 5],                                    # Array
412
    (40.7128, -74.0060),                               # Tuple (NYC coordinates)
413
    [['a', 'b'], ['c', 'd'], ['e']],                   # Nested array
414
    {'count': 100, 'sum': 500, 'max': 50}             # Map
415
)]
416

417
client.execute('INSERT INTO test_complex VALUES', data)
418
```
419

420
### Nullable Types Usage
421

422
```python
423
# Nullable columns
424
client.execute('''
425
    CREATE TABLE test_nullable (
426
        optional_number Nullable(Int32),
427
        optional_text Nullable(String),
428
        optional_array Nullable(Array(String))
429
    ) ENGINE = Memory
430
''')
431

432
data = [
433
    (42, 'hello', ['a', 'b']),        # All values present
434
    (None, 'world', None),            # Some nulls
435
    (100, None, ['x', 'y', 'z'])      # Mixed nulls
436
]
437

438
client.execute('INSERT INTO test_nullable VALUES', data)
439
```
440

441
### Decimal and IP Types Usage
442

443
```python
444
from decimal import Decimal
445
import ipaddress
446

447
client.execute('''
448
    CREATE TABLE test_special (
449
        price Decimal(10, 2),
450
        server_ip IPv4,
451
        client_ip IPv6
452
    ) ENGINE = Memory
453
''')
454

455
data = [(
456
    Decimal('99.99'),
457
    ipaddress.IPv4Address('192.168.1.1'),
458
    ipaddress.IPv6Address('2001:db8::1')
459
)]
460

461
client.execute('INSERT INTO test_special VALUES', data)
462
```
463

464
### Type Introspection
465

466
```python
467
# Get column types from query results
468
columns, rows = client.execute(
469
    'SELECT * FROM test_complex LIMIT 1',
470
    with_column_types=True
471
)
472

473
for name, clickhouse_type in columns:
474
    print(f"{name}: {clickhouse_type}")
475

476
# Output:
477
# numbers: Array(Int32)
478
# coordinates: Tuple(Float64, Float64)  
479
# nested_arrays: Array(Array(String))
480
# key_values: Map(String, Int32)
481
```