Supported types¶
Each ClickHouse type is deserialized to a corresponding Python type when SELECT queries are prepared. When serializing INSERT queries, clickhouse-driver accepts a broader range of Python types. The following ClickHouse types are supported by clickhouse-driver:
DateTime(‘timezone’)¶
Timezone support is new in version 0.0.11.
INSERT types: datetime
, int
, long
.
Integers are interpreted as seconds without timezone (UNIX timestamps). Integers can be used when insertion of datetime column is a bottleneck.
SELECT type: datetime
.
Setting use_client_time_zone is taken into consideration.
String/FixedString(N)¶
INSERT types: str
/basestring
, bytearray
, bytes
. See note below.
SELECT type: str
/basestring
, bytes
. See note below.
String column is encoded/decoded using UTF-8 encoding.
String column can be returned without decoding. Return values are bytes:
>>> settings = {'strings_as_bytes': True} >>> rows = client.execute( ... 'SELECT * FROM table_with_strings', ... settings=settings ... )
If a column has FixedString type, upon returning from SELECT it may contain trailing zeroes in accordance with ClickHouse’s storage format. Trailing zeroes are stripped by driver for convenience.
During SELECT, if a string cannot be decoded with UTF-8 encoding, it will return as bytes
.
During INSERT, if strings_as_bytes
setting is not specified and string cannot be encoded with UTF-8
,
a UnicodeEncodeError
will be raised.
Enum8/16¶
INSERT types: Enum
, int
, long
, str
/basestring
.
SELECT type: str
/basestring
.
>>> from enum import IntEnum >>> >>> class MyEnum(IntEnum): ... foo = 1 ... bar = 2 ... >>> client.execute('DROP TABLE IF EXISTS test') [] >>> client.execute(''' ... CREATE TABLE test ... ( ... x Enum8('foo' = 1, 'bar' = 2) ... ) ENGINE = Memory ... ''') [] >>> client.execute( ... 'INSERT INTO test (x) VALUES', ... [{'x': MyEnum.foo}, {'x': 'bar'}, {'x': 1}] ... ) >>> client.execute('SELECT * FROM test') [('foo',), ('bar',), ('foo',)]
For Python 2.7, enum34 package is used.
Currently clickhouse-driver can’t handle empty enum value due to Python’s Enum mechanics. Enum member name must be not empty. See issue and workaround.
Array(T)¶
SELECT type: tuple
.
>>> client.execute('DROP TABLE IF EXISTS test') [] >>> client.execute( ... 'CREATE TABLE test (x Array(Int32)) ' ... 'ENGINE = Memory' ... ) [] >>> client.execute( ... 'INSERT INTO test (x) VALUES', ... [{'x': [10, 20, 30]}, {'x': [11, 21, 31]}] ... ) >>> client.execute('SELECT * FROM test') [((10, 20, 30),), ((11, 21, 31),)]