clickhouse-driver · Python Simple Repository Browser

Project Links

Meta

Author: Konstantin Lebedev

Requires Python: >=3.9, <4

Classifiers

Development Status

4 - Beta

Environment

Console

Intended Audience

Developers
Information Technology

License

OSI Approved :: MIT License

Operating System

OS Independent

Programming Language

SQL
Python :: 3
Python :: 3.9
Python :: 3.10
Python :: 3.11
Python :: 3.12
Python :: 3.13
Python :: 3.14
Python :: Implementation :: PyPy

Topic

Database
Software Development
Software Development :: Libraries
Software Development :: Libraries :: Application Frameworks
Software Development :: Libraries :: Python Modules
Scientific/Engineering :: Information Analysis

ClickHouse Python Driver

https://img.shields.io/pypi/v/clickhouse-driver.svg

https://coveralls.io/repos/github/mymarilyn/clickhouse-driver/badge.svg?branch=master

https://img.shields.io/pypi/l/clickhouse-driver.svg

https://img.shields.io/pypi/pyversions/clickhouse-driver.svg

https://img.shields.io/pypi/dm/clickhouse-driver.svg

ClickHouse Python Driver with native (TCP) interface support.

Asynchronous wrapper is available here: https://github.com/mymarilyn/aioch

Features

External data for query processing.
Query settings.
Compression support.
TLS support.
Types support:
- Float32/64
- [U]Int8/16/32/64/128/256
- Date/Date32/DateTime(‘timezone’)/DateTime64(‘timezone’)
- String/FixedString(N)
- Enum8/16
- Array(T)
- Nullable(T)
- Bool
- UUID
- Decimal
- IPv4/IPv6
- LowCardinality(T)
- SimpleAggregateFunction(F, T)
- Tuple(T1, T2, …)
- Nested
- Map(key, value)
Query progress information.
Block by block results streaming.
Reading query profile info.
Receiving server logs.
Multiple hosts support.
Python DB API 2.0 specification support.
Optional NumPy arrays support.

Documentation

Documentation is available at https://clickhouse-driver.readthedocs.io.

Usage

There are two ways to communicate with server:

using pure Client;
using DB API.

Pure Client example:

>>> from clickhouse_driver import Client
>>>
>>> client = Client('localhost')
>>>
>>> client.execute('SHOW TABLES')
[('test',)]
>>> client.execute('DROP TABLE IF EXISTS test')
[]
>>> client.execute('CREATE TABLE test (x Int32) ENGINE = Memory')
[]
>>> client.execute(
...     'INSERT INTO test (x) VALUES',
...     [{'x': 100}]
... )
1
>>> client.execute('INSERT INTO test (x) VALUES', [[200]])
1
>>> client.execute(
...     'INSERT INTO test (x) '
...     'SELECT * FROM system.numbers LIMIT %(limit)s',
...     {'limit': 3}
... )
[]
>>> client.execute('SELECT sum(x) FROM test')
[(303,)]

DB API example:

>>> from clickhouse_driver import connect
>>>
>>> conn = connect('clickhouse://localhost')
>>> cursor = conn.cursor()
>>>
>>> cursor.execute('SHOW TABLES')
>>> cursor.fetchall()
[('test',)]
>>> cursor.execute('DROP TABLE IF EXISTS test')
>>> cursor.fetchall()
[]
>>> cursor.execute('CREATE TABLE test (x Int32) ENGINE = Memory')
>>> cursor.fetchall()
[]
>>> cursor.executemany(
...     'INSERT INTO test (x) VALUES',
...     [{'x': 100}]
... )
>>> cursor.rowcount
1
>>> cursor.executemany('INSERT INTO test (x) VALUES', [[200]])
>>> cursor.rowcount
1
>>> cursor.execute(
...     'INSERT INTO test (x) '
...     'SELECT * FROM system.numbers LIMIT %(limit)s',
...     {'limit': 3}
... )
>>> cursor.rowcount
0
>>> cursor.execute('SELECT sum(x) FROM test')
>>> cursor.fetchall()
[(303,)]

License

ClickHouse Python Driver is distributed under the MIT license.

Wheel compatibility matrix

Platform	CPython 3.8	CPython 3.9	CPython 3.10	CPython 3.11	CPython 3.12	CPython 3.13	CPython 3.14	PyPy 3.9 (pp73)	PyPy 3.10 (pp73)	PyPy 3.11 (pp73)
macosx_10_13_x86_64
macosx_10_15_x86_64
macosx_10_9_x86_64
macosx_11_0_arm64
manylinux2014_aarch64
manylinux2014_ppc64le
manylinux2014_s390x
manylinux2014_x86_64
manylinux_2_17_aarch64
manylinux_2_17_ppc64le
manylinux_2_17_s390x
manylinux_2_17_x86_64
manylinux_2_28_aarch64
manylinux_2_28_ppc64le
manylinux_2_28_s390x
manylinux_2_28_x86_64
musllinux_1_2_aarch64
musllinux_1_2_ppc64le
musllinux_1_2_s390x
musllinux_1_2_x86_64
win32
win_amd64