clickhouse-driver-http 0.1.0

Lightweight HTTP client for ClickHouse

ClickHouse HTTP Driver (clickhouse-driver-http)

Lightweight Python HTTP client for ClickHouse with minimal dependencies.

Installation

pip install clickhouse-driver-http

Quick Start

from clickhouse_driver_http import ClickHouseHTTP

# Initialize client (supports both int/string ports)
client = ClickHouseHTTP(
    host="localhost",          # Required
    port=8123,                # Default: 8123 (can be string "8123")
    username="default",       # Default: "default"
    password="",              # Default: ""
    database="default",       # Default: "default"
    timeout=300,              # Default: 300s
    max_retries=3,            # Default: 3
    compression=False         # Default: False
)

# Execute query (returns raw tuples)
result = client.execute("SELECT now() AS current_time, version()")

# Get DataFrame (pandas required)
df = client.query_to_df("""
    SELECT table, engine 
    FROM system.tables 
    WHERE database = currentDatabase()
    LIMIT 5
""")

Key Features

• HTTP Interface - No native protocol dependency
• External Tables - Pass data directly in queries
• Smart Batching - Automatic chunking for large results
• Error Resilient - Built-in retry mechanism
• Pandas Support - Direct DataFrame conversion

Advanced Examples

External Tables

data = {
    'users': [
        {'user_id': 1, 'name': 'Alice'},
        {'user_id': 2, 'name': 'Bob'}
    ]
}

external = [{
    'name': 'ext_users',
    'structure': [('user_id', 'UInt32'), ('name', 'String')],
    'data': data['users']
}]

df = client.query_to_df("""
    SELECT u.name, count() as logins
    FROM ext_users u
    JOIN system.query_log q ON q.user = u.name
    GROUP BY u.name
""", external_tables=external)

Batch Processing

# Processes in 100k row batches with auto-retry
large_df = client.query_to_df(
    "SELECT * FROM billion_row_table",
    batch_size=100000,  # Initial batch size
    memory_safe=True    # Enables memory limits
)

Configuration Reference

Parameter	Type	Default	Description
host	str	-	Server hostname or IP
port	int/str	8123	HTTP interface port
username	str	"default"	Authentication username
password	str	""	Authentication password
database	str	"default"	Default database context
timeout	int	300	Query timeout in seconds
max_retries	int	3	Connection retry attempts
compression	bool	False	Enable gzip/deflate compression
verify_ssl	bool	True	Verify SSL certificates

License

MIT License - See LICENSE for full text.

Note: Requires Python 3.7+ and requests package. Pandas needed for DataFrame support.