# aiochclient
[](https://badge.fury.io/py/aiochclient)
[](https://github.com/maximdanilchenko/aiochclient/actions/workflows/tests.yml)
[](https://aiochclient.readthedocs.io/en/latest/?badge=latest)
[](https://codecov.io/gh/maximdanilchenko/aiochclient)
[](https://github.com/ambv/black)
An async http(s) ClickHouse client for python 3.6+ supporting type
conversion in both directions, streaming, lazy decoding on select queries, and a
fully typed interface.
## Table of Contents
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Documentation](#documentation)
- [Type Conversion](#type-conversion)
- [Connection Pool Settings](#connection-pool-settings)
- [Notes on Speed](#notes-on-speed)
## Installation
You can use it with either
[aiohttp](https://github.com/aio-libs/aiohttp) or
[httpx](https://github.com/encode/httpx) http connectors.
To use with `aiohttp` install it with command:
```
> pip install aiochclient[aiohttp]
```
Or `aiochclient[aiohttp-speedups]` to install with extra speedups.
To use with `httpx` install it with command:
```
> pip install aiochclient[httpx]
```
Or `aiochclient[httpx-speedups]` to install with extra speedups.
Installing with `[*-speedups]` adds the following:
- [cChardet](https://pypi.python.org/pypi/cchardet) for `aiohttp` speedup
- [aiodns](https://pypi.python.org/pypi/aiodns) for `aiohttp` speedup
- [ciso8601](https://github.com/closeio/ciso8601) for ultra-fast datetime
parsing while decoding data from ClickHouse for `aiohttp` and `httpx`.
Additionally the installation process attempts to use Cython for a speed boost
(roughly 30% faster).
## Quick Start
### Connecting to ClickHouse
`aiochclient` needs `aiohttp.ClientSession` or `httpx.AsyncClient` to connect to ClickHouse:
```python
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
```
### Querying the database
```python
await client.execute(
"CREATE TABLE t (a UInt8, b Tuple(Date, Nullable(Float32))) ENGINE = Memory"
)
```
For INSERT queries you can pass values as `*args`. Values should be
iterables:
```python
await client.execute(
"INSERT INTO t VALUES",
(1, (dt.date(2018, 9, 7), None)),
(2, (dt.date(2018, 9, 8), 3.14)),
)
```
For fetching all rows at once use the
[`fetch`](https://aiochclient.readthedocs.io/en/latest/api.html#aiochclient.ChClient.fetch)
method:
```python
all_rows = await client.fetch("SELECT * FROM t")
```
For fetching first row from result use the
[`fetchrow`](https://aiochclient.readthedocs.io/en/latest/api.html#aiochclient.ChClient.fetchrow)
method:
```python
row = await client.fetchrow("SELECT * FROM t WHERE a=1")
assert row[0] == 1
assert row["b"] == (dt.date(2018, 9, 7), None)
```
You can also use
[`fetchval`](https://aiochclient.readthedocs.io/en/latest/api.html#aiochclient.ChClient.fetchval)
method, which returns first value of the first row from query result:
```python
val = await client.fetchval("SELECT b FROM t WHERE a=2")
assert val == (dt.date(2018, 9, 8), 3.14)
```
With async iteration on the query results stream you can fetch multiple
rows without loading them all into memory at once:
```python
async for row in client.iterate(
"SELECT number, number*2 FROM system.numbers LIMIT 10000"
):
assert row[0] * 2 == row[1]
```
Use `fetch`/`fetchrow`/`fetchval`/`iterate` for SELECT queries and `execute` or
any of last for INSERT and all another queries.
### Working with query results
All fetch queries return rows as lightweight, memory efficient objects. _Before
v`1.0.0` rows were only returned as tuples._ All rows have a full mapping interface, where you can
get fields by names or indexes:
```python
row = await client.fetchrow("SELECT a, b FROM t WHERE a=1")
assert row["a"] == 1
assert row[0] == 1
assert row[:] == (1, (dt.date(2018, 9, 8), 3.14))
assert list(row.keys()) == ["a", "b"]
assert list(row.values()) == [1, (dt.date(2018, 9, 8), 3.14)]
```
## Documentation
To check out the [api docs](https://aiochclient.readthedocs.io/en/latest/api.html),
visit the [readthedocs site.](https://aiochclient.readthedocs.io/en/latest/).
## Type Conversion
`aiochclient` automatically converts types from ClickHouse to python types and
vice-versa.
| ClickHouse type | Python type |
|:---------------------|:------------------------|
| `Bool` | `bool` |
| `UInt8` | `int` |
| `UInt16` | `int` |
| `UInt32` | `int` |
| `UInt64` | `int` |
| `UInt128` | `int` |
| `UInt256` | `int` |
| `Int8` | `int` |
| `Int16` | `int` |
| `Int32` | `int` |
| `Int64` | `int` |
| `Int128` | `int` |
| `Int256` | `int` |
| `Float32` | `float` |
| `Float64` | `float` |
| `String` | `str` |
| `FixedString` | `str` |
| `Enum8` | `str` |
| `Enum16` | `str` |
| `Date` | `datetime.date` |
| `DateTime` | `datetime.datetime` |
| `DateTime64` | `datetime.datetime` |
| `Decimal` | `decimal.Decimal` |
| `Decimal32` | `decimal.Decimal` |
| `Decimal64` | `decimal.Decimal` |
| `Decimal128` | `decimal.Decimal` |
| `IPv4` | `ipaddress.IPv4Address` |
| `IPv6` | `ipaddress.IPv6Address` |
| `UUID` | `uuid.UUID` |
| `Nothing` | `None` |
| `Tuple(T1, T2, ...)` | `Tuple[T1, T2, ...]` |
| `Array(T)` | `List[T]` |
| `Nullable(T)` | `None` or `T` |
| `LowCardinality(T)` | `T` |
| `Map(T1, T2)` | `Dict[T1, T2]` |
| `Nested(T1, T2, ...)` | `List[Tuple[T1, T2, ...], Tuple[T1, T2, ...]]` |
## Connection Pool Settings
`aiochclient` uses the
[aiohttp.TCPConnector](https://docs.aiohttp.org/en/stable/client_advanced.html#limiting-connection-pool-size)
to determine pool size. By default, the pool limit is 100 open connections.
## Notes on Speed
It's highly recommended using `uvloop` and installing `aiochclient` with
speedups for the sake of speed. Some recent benchmarks on our
machines without parallelization:
- 180k-220k rows/sec on SELECT
- 50k-80k rows/sec on INSERT
_Note: these benchmarks are system dependent_
Raw data
{
"_id": null,
"home_page": "https://github.com/maximdanilchenko/aiochclient",
"name": "aiochclient",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "clickhouse async python aiohttp httpx",
"author": "Danilchenko Maksim",
"author_email": "dmax.dev@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/6e/91/222d9e03e3d57573b727f916e2ee4c9ad06a9940d4f5630037893cd74ad1/aiochclient-2.6.0.tar.gz",
"platform": null,
"description": "# aiochclient\n\n[](https://badge.fury.io/py/aiochclient)\n[](https://github.com/maximdanilchenko/aiochclient/actions/workflows/tests.yml)\n[](https://aiochclient.readthedocs.io/en/latest/?badge=latest)\n[](https://codecov.io/gh/maximdanilchenko/aiochclient)\n[](https://github.com/ambv/black)\n\n\nAn async http(s) ClickHouse client for python 3.6+ supporting type\nconversion in both directions, streaming, lazy decoding on select queries, and a\nfully typed interface.\n\n## Table of Contents\n\n- [Installation](#installation)\n- [Quick Start](#quick-start)\n- [Documentation](#documentation)\n- [Type Conversion](#type-conversion)\n- [Connection Pool Settings](#connection-pool-settings)\n- [Notes on Speed](#notes-on-speed)\n\n## Installation\n\nYou can use it with either\n[aiohttp](https://github.com/aio-libs/aiohttp) or\n[httpx](https://github.com/encode/httpx) http connectors.\n\nTo use with `aiohttp` install it with command:\n\n```\n> pip install aiochclient[aiohttp]\n```\n\nOr `aiochclient[aiohttp-speedups]` to install with extra speedups.\n\nTo use with `httpx` install it with command:\n\n```\n> pip install aiochclient[httpx]\n```\n\nOr `aiochclient[httpx-speedups]` to install with extra speedups.\n\nInstalling with `[*-speedups]` adds the following:\n\n- [cChardet](https://pypi.python.org/pypi/cchardet) for `aiohttp` speedup\n- [aiodns](https://pypi.python.org/pypi/aiodns) for `aiohttp` speedup\n- [ciso8601](https://github.com/closeio/ciso8601) for ultra-fast datetime\n parsing while decoding data from ClickHouse for `aiohttp` and `httpx`.\n\nAdditionally the installation process attempts to use Cython for a speed boost\n(roughly 30% faster).\n\n## Quick Start\n\n### Connecting to ClickHouse\n\n`aiochclient` needs `aiohttp.ClientSession` or `httpx.AsyncClient` to connect to ClickHouse:\n\n```python\nfrom aiochclient import ChClient\nfrom aiohttp import ClientSession\n\n\nasync def main():\n async with ClientSession() as s:\n client = ChClient(s)\n assert await client.is_alive() # returns True if connection is Ok\n\n```\n\n### Querying the database\n\n```python\nawait client.execute(\n \"CREATE TABLE t (a UInt8, b Tuple(Date, Nullable(Float32))) ENGINE = Memory\"\n)\n```\n\nFor INSERT queries you can pass values as `*args`. Values should be\niterables:\n\n```python\nawait client.execute(\n \"INSERT INTO t VALUES\",\n (1, (dt.date(2018, 9, 7), None)),\n (2, (dt.date(2018, 9, 8), 3.14)),\n)\n```\n\nFor fetching all rows at once use the\n[`fetch`](https://aiochclient.readthedocs.io/en/latest/api.html#aiochclient.ChClient.fetch)\nmethod:\n\n```python\nall_rows = await client.fetch(\"SELECT * FROM t\")\n```\n\nFor fetching first row from result use the\n[`fetchrow`](https://aiochclient.readthedocs.io/en/latest/api.html#aiochclient.ChClient.fetchrow)\nmethod:\n\n```python\nrow = await client.fetchrow(\"SELECT * FROM t WHERE a=1\")\n\nassert row[0] == 1\nassert row[\"b\"] == (dt.date(2018, 9, 7), None)\n```\n\nYou can also use\n[`fetchval`](https://aiochclient.readthedocs.io/en/latest/api.html#aiochclient.ChClient.fetchval)\nmethod, which returns first value of the first row from query result:\n\n```python\nval = await client.fetchval(\"SELECT b FROM t WHERE a=2\")\n\nassert val == (dt.date(2018, 9, 8), 3.14)\n```\n\nWith async iteration on the query results stream you can fetch multiple\nrows without loading them all into memory at once:\n\n```python\nasync for row in client.iterate(\n \"SELECT number, number*2 FROM system.numbers LIMIT 10000\"\n):\n assert row[0] * 2 == row[1]\n```\n\nUse `fetch`/`fetchrow`/`fetchval`/`iterate` for SELECT queries and `execute` or\nany of last for INSERT and all another queries.\n\n### Working with query results\n\nAll fetch queries return rows as lightweight, memory efficient objects. _Before\nv`1.0.0` rows were only returned as tuples._ All rows have a full mapping interface, where you can\nget fields by names or indexes:\n\n```python\nrow = await client.fetchrow(\"SELECT a, b FROM t WHERE a=1\")\n\nassert row[\"a\"] == 1\nassert row[0] == 1\nassert row[:] == (1, (dt.date(2018, 9, 8), 3.14))\nassert list(row.keys()) == [\"a\", \"b\"]\nassert list(row.values()) == [1, (dt.date(2018, 9, 8), 3.14)]\n```\n\n## Documentation\n\nTo check out the [api docs](https://aiochclient.readthedocs.io/en/latest/api.html),\nvisit the [readthedocs site.](https://aiochclient.readthedocs.io/en/latest/).\n\n## Type Conversion\n\n`aiochclient` automatically converts types from ClickHouse to python types and\nvice-versa.\n\n\n| ClickHouse type | Python type |\n|:---------------------|:------------------------|\n| `Bool` | `bool` |\n| `UInt8` | `int` |\n| `UInt16` | `int` |\n| `UInt32` | `int` |\n| `UInt64` | `int` |\n| `UInt128` | `int` |\n| `UInt256` | `int` |\n| `Int8` | `int` |\n| `Int16` | `int` |\n| `Int32` | `int` |\n| `Int64` | `int` |\n| `Int128` | `int` |\n| `Int256` | `int` |\n| `Float32` | `float` |\n| `Float64` | `float` |\n| `String` | `str` |\n| `FixedString` | `str` |\n| `Enum8` | `str` |\n| `Enum16` | `str` |\n| `Date` | `datetime.date` |\n| `DateTime` | `datetime.datetime` |\n| `DateTime64` | `datetime.datetime` |\n| `Decimal` | `decimal.Decimal` |\n| `Decimal32` | `decimal.Decimal` |\n| `Decimal64` | `decimal.Decimal` |\n| `Decimal128` | `decimal.Decimal` |\n| `IPv4` | `ipaddress.IPv4Address` |\n| `IPv6` | `ipaddress.IPv6Address` |\n| `UUID` | `uuid.UUID` |\n| `Nothing` | `None` |\n| `Tuple(T1, T2, ...)` | `Tuple[T1, T2, ...]` |\n| `Array(T)` | `List[T]` |\n| `Nullable(T)` | `None` or `T` |\n| `LowCardinality(T)` | `T` |\n| `Map(T1, T2)` | `Dict[T1, T2]` |\n| `Nested(T1, T2, ...)` | `List[Tuple[T1, T2, ...], Tuple[T1, T2, ...]]` |\n\n\n## Connection Pool Settings\n\n`aiochclient` uses the\n[aiohttp.TCPConnector](https://docs.aiohttp.org/en/stable/client_advanced.html#limiting-connection-pool-size)\nto determine pool size. By default, the pool limit is 100 open connections.\n\n## Notes on Speed\n\nIt's highly recommended using `uvloop` and installing `aiochclient` with\nspeedups for the sake of speed. Some recent benchmarks on our\nmachines without parallelization:\n\n- 180k-220k rows/sec on SELECT\n- 50k-80k rows/sec on INSERT\n\n_Note: these benchmarks are system dependent_\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Async http clickhouse client for python 3.6+",
"version": "2.6.0",
"project_urls": {
"Homepage": "https://github.com/maximdanilchenko/aiochclient"
},
"split_keywords": [
"clickhouse",
"async",
"python",
"aiohttp",
"httpx"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "6e91222d9e03e3d57573b727f916e2ee4c9ad06a9940d4f5630037893cd74ad1",
"md5": "580cb4ac12aa8522e6ed522a64b3238f",
"sha256": "c8f7b846cea0792489b3ad981e2b2678a0c4f0ab5555c648367e33008aba28e4"
},
"downloads": -1,
"filename": "aiochclient-2.6.0.tar.gz",
"has_sig": false,
"md5_digest": "580cb4ac12aa8522e6ed522a64b3238f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 242447,
"upload_time": "2024-02-13T16:44:42",
"upload_time_iso_8601": "2024-02-13T16:44:42.385780Z",
"url": "https://files.pythonhosted.org/packages/6e/91/222d9e03e3d57573b727f916e2ee4c9ad06a9940d4f5630037893cd74ad1/aiochclient-2.6.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-13 16:44:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "maximdanilchenko",
"github_project": "aiochclient",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "sqlparse",
"specs": [
[
">=",
"0.4.4"
]
]
}
],
"lcname": "aiochclient"
}
JSON
