aiochclient

Rows returned by fetch methods are lightweight, memory-efficient objects that support both name-based and index-based access. They also support mapping interfaces like .keys(), .values(), and slicing.

row = await client.fetchrow("SELECT a, b FROM t WHERE a=1")

assert row["a"] == 1          # Access by name
assert row[0] == 1            # Access by index
assert row[:] == (1, val)     # Slicing (returns tuple)
assert list(row.keys()) == ["a", "b"]
assert list(row.values()) == [1, val]

You can install aiochclient using pip. If you already have it installed and want to upgrade to the latest version, use the -U flag.

$ pip install aiochclient
# To update:
$ pip install -U aiochclient

To achieve maximum performance with aiochclient, follow these best practices:

1. Use Binary Engines: Use native=True for bulk SELECT/INSERT and binary=True for iterate() streaming.
2. Install Speedups: Use pip install aiochclient[*-speedups] to include ciso8601 for fast datetime parsing.
3. Build Cython: Ensure the Cython extension is built during installation for a ~30% speed boost.
4. Use uvloop: Use uvloop as the asyncio event loop policy.

To use aiochclient, you must provide an existing aiohttp.ClientSession or httpx.AsyncClient instance to the ChClient constructor. You can verify the connection using the is_alive() method.

from aiochclient import ChClient
from aiohttp import ClientSession

async def main():
    async with ClientSession() as s:
        client = ChClient(s)
        assert await client.is_alive()  # returns True if connection is Ok

To verify your connection, you can use ChClient with an aiohttp.ClientSession to call is_alive(). By default, this attempts to connect to localhost:8123 using the default user.

import asyncio
from aiochclient import ChClient
from aiohttp import ClientSession

async def main():
    async with ClientSession() as s:
        client = ChClient(s)
        alive = await client.is_alive()
        print(f"Is ClickHouse alive? -> {alive}")

if __name__ == '__main__':
    asyncio.run(main())

To reproduce the throughput comparisons against other Python ClickHouse clients, run the provided benchmark script. The benchmarks measure serialization/deserialization costs using a single connection without async parallelism to isolate CPU/encoding performance from IO concurrency.

Benchmark Configuration:

• Workload: A Memory engine table with mixed types (UInt32, Int64, Float64, String, Date, DateTime, Array(String), Nullable(Int32)).
• SELECT: SELECT * of 50,000 rows, fully materialized into Python objects.
• INSERT: Bulk-insert of 50,000 rows (table truncated before each run).
• Metric: Throughput calculated as rows per best wall-clock time over 8 sequential runs.

python benchmarks_vs_libs.py

You can choose between aiohttp or httpx as the underlying HTTP connector. It is recommended to install the *-speedups extra for better performance, which includes ciso8601 for fast datetime parsing, and aiodns/faust-cchardet for aiohttp speedups.

For aiohttp:

pip install aiochclient[aiohttp]
# Or with speedups:
pip install aiochclient[aiohttp-speedups]

For httpx:

pip install aiochclient[httpx]
# Or with speedups:
pip install aiochclient[httpx-speedups]

Performance measurements for aiochclient (specifically throughput for columnar decoding) are sensitive to background CPU load. High background CPU usage (e.g., security scanners, virtualization overhead like Docker/QEMU) can significantly reduce absolute throughput numbers.

When evaluating performance, note that:

• The optimization for GC management provides a consistent performance boost regardless of system load.
• Throughput figures reported in documentation (e.g., ~1.0M rows/sec) are typically achieved on idle machines. Under heavy load, these numbers will decrease, but the relative performance gain from the library's optimizations remains consistent.