or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

client-interface.mdcompression.mddata-types.mddbapi-interface.mderror-handling.mdindex.mdresults-processing.md
tile.json

tessl/pypi-clickhouse-driver

Python driver with native interface for ClickHouse database providing high-performance connectivity and comprehensive data type support.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/clickhouse-driver@0.2.x

To install, run

npx @tessl/cli install tessl/pypi-clickhouse-driver@0.2.0

index.mddocs/

ClickHouse Driver

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.

Package Information

  • Package Name: clickhouse-driver
  • Language: Python
  • Installation: pip install clickhouse-driver
  • Optional Dependencies:
    • LZ4 compression: pip install clickhouse-driver[lz4]
    • ZSTD compression: pip install clickhouse-driver[zstd]
    • NumPy integration: pip install clickhouse-driver[numpy]

Core Imports

Standard client interface:

from clickhouse_driver import Client

DB API 2.0 interface:

from clickhouse_driver import connect

Basic Usage

Using the Client Interface

from clickhouse_driver import Client

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

# Execute queries
rows = client.execute('SELECT version()')
print(rows)

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

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

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

# Disconnect
client.disconnect()

Using the DB API 2.0 Interface

from clickhouse_driver import connect

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

# Execute queries
cursor.execute('SELECT version()')
result = cursor.fetchone()
print(result)

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

# Query with fetchall
cursor.execute('SELECT * FROM test')
rows = cursor.fetchall()
print(rows)

# Close resources
cursor.close()
conn.close()

Architecture

The driver provides two complementary interfaces:

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

Capabilities

Client Interface

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

class Client:
    def __init__(self, host='localhost', port=9000, database='', user='default', 
                 password='', client_name='python-driver', **kwargs): ...
    def execute(self, query, params=None, with_column_types=False, 
                external_tables=None, query_id=None, settings=None, 
                types_check=False, columnar=False): ...
    def execute_with_progress(self, query, params=None, **kwargs): ...
    def execute_iter(self, query, params=None, **kwargs): ...
    def disconnect(self): ...

Client Interface

DB API 2.0 Interface

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

def connect(dsn=None, host=None, user='default', password='', 
            port=9000, database='', **kwargs):
    """Create a new database connection."""

class Connection:
    def cursor(self, cursor_factory=None): ...
    def close(self): ...
    def commit(self): ...  # No-op
    def rollback(self): ...  # No-op

class Cursor:
    def execute(self, operation, parameters=None): ...
    def executemany(self, operation, seq_of_parameters): ...
    def fetchone(self): ...
    def fetchmany(self, size=None): ...
    def fetchall(self): ...

DB API Interface

Data Types and Columns

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.

# Integer types: Int8, Int16, Int32, Int64, Int128, Int256, UInt8, UInt16, UInt32, UInt64, UInt128, UInt256
# Float types: Float32, Float64  
# String types: String, FixedString
# Date/Time types: Date, Date32, DateTime (with timezone)
# Special types: UUID, IPv4, IPv6, Bool
# Container types: Array, Tuple, Map, Nested
# Advanced types: LowCardinality, JSON, Decimal, Enum

Data Types

Error Handling

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.

# Core exceptions
class Error(Exception): ...
class ServerException(Error): ...
class NetworkError(Error): ...
class TypeMismatchError(Error): ...

# DB API 2.0 exceptions  
class DatabaseError(Error): ...
class OperationalError(DatabaseError): ...
class ProgrammingError(DatabaseError): ...
class DataError(DatabaseError): ...

Error Handling

Query Results and Data Processing

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

class QueryResult:
    """Standard query result storage."""

class IterQueryResult:
    """Streaming query result iterator."""

class ProgressQueryResult:
    """Query result with progress information."""

Results Processing

Compression and Performance

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

# Compression support (requires extras)
# LZ4: pip install clickhouse-driver[lz4] 
# ZSTD: pip install clickhouse-driver[zstd]

Compression

Types

# Connection settings type
ConnectionSettings = Dict[str, Any]

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

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

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

# Column information tuple
ColumnInfo = Tuple[str, str]  # (name, type)