Skip to main content

A ClickHouse client for Python, with a command-line interface.

Project description

pych-client

Coverage Tests Status PyPI

pych-client is a ClickHouse client for Python built on top of httpx. It targets the HTTP interface and offers the following features:

  • Sync (ClickHouseClient) and async (AsyncClickHouseClient) clients.
  • Streaming requests and responses.
  • Load credentials from environment variables, or from a configuration file.

Installation

# Default Python JSON parser:
pip install pych-client
# Faster orjson parser:
pip install pych-client[orjson]

Usage

from pych_client import AsyncClickHouseClient, ClickHouseClient

# See "Credential provider chain" for more information on credential specification.
credentials = dict(
    base_url="http://localhost:8123",
    database="default",
    username="default",
    password=""
)

# The client can be used directly, or as a context manager.
# The context manager will ensure that the HTTP client resources
# are properly cleaned-up on exit.
with ClickHouseClient(**credentials) as client:
    # `.bytes()` and `.text()` return the raw response content from the database.
    # `.json()` sets the format to `JSONEachRow` and parse the response content.
    client.bytes("SELECT arrayJoin([1, 2, 3]) AS a")
    # b'1\n2\n3\n'
    client.text("SELECT arrayJoin([1, 2, 3]) AS a")
    # '1\n2\n3\n'
    client.json("SELECT arrayJoin([1, 2, 3]) AS a")
    # [{'a': 1}, {'a': 2}, {'a': 3}]

    # `.iter_bytes()`, `.iter_text()` and `.iter_json()` return the response content
    # as it is received from the database, without buffering the entire response.
    # `.iter_text()` iterates on the line of the response.
    list(client.iter_bytes("SELECT arrayJoin([1, 2, 3]) AS a"))
    # [b'1\n2\n3\n', b'']
    list(client.iter_text("SELECT arrayJoin([1, 2, 3]) AS a"))
    # ['1', '2', '3']
    list(client.iter_json("SELECT arrayJoin([1, 2, 3]) AS a"))
    # [{'a': 1}, {'a': 2}, {'a': 3}]

    # In addition to the query, the following arguments can be set:
    # - `params`: a mapping of query parameters to their values.
    # - `data`: a bytes, string or an interator of bytes to send in the request body.
    # - `settings`: ClickHouse settings (e.g. `{"default_format": "JSONEachRow"`).
    params = {"table": "test_pych"}
    client.text('''
        CREATE TABLE {table:Identifier} (a Int64, b Int64)
        ENGINE MergeTree() ORDER BY (a, b)
    ''', params)
    client.text("INSERT INTO {table:Identifier} VALUES", params, "(1, 2)")
    client.text("INSERT INTO {table:Identifier} VALUES", params, [b"(3, 4)", b"(5, 6)"])
    client.json("SELECT * FROM {table:Identifier} ORDER BY a", params)
    # [{'a': '1', 'b': '2'}, {'a': '3', 'b': '4'}, {'a': '5', 'b': '6'}]

# `AsyncClickHouseClient` offers the same methods:
async with AsyncClickHouseClient(**credentials) as client:
    # Example usage for `.json()` and `.iter_json()`:
    await client.json("SELECT arrayJoin([1, 2, 3]) AS a")
    # [{'a': 1}, {'a': 2}, {'a': 3}]
    async for row in client.iter_json("SELECT arrayJoin([1, 2, 3]) AS a"):
        ...

Command-line interface

pych-client --help

Credential provider chain

The client looks for credentials in a way similar to the AWS SDK:

  1. If one of base_url, database, username or password is specified, these values will be used.
  2. If none of the previous values are specified, and one of PYCH_BASE_URL, PYCH_DATABASE, PYCH_USERNAME or PYCH_PASSWORD environment variables are present, these values will be used.
  3. If none of the previous values are specified, and the file ~/.config/pych-client/credentials.json exists, the fields base_url, database and username and password will be used.
  4. If none of the previous values are specified, the values http://localhost:8213, default and default will be used.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pych_client-0.4.0.tar.gz (9.0 kB view details)

Uploaded Source

Built Distribution

pych_client-0.4.0-py3-none-any.whl (11.7 kB view details)

Uploaded Python 3

File details

Details for the file pych_client-0.4.0.tar.gz.

File metadata

  • Download URL: pych_client-0.4.0.tar.gz
  • Upload date:
  • Size: 9.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.2 CPython/3.12.0

File hashes

Hashes for pych_client-0.4.0.tar.gz
Algorithm Hash digest
SHA256 72ae66e6cb44811194699ed3f832490b3573d09ba6abaefc57cdd85b57c59129
MD5 b96049935d82c95215777591da7a9758
BLAKE2b-256 8a7a52eb113befa203a32493cc767b7be4fa57f42da80de5d8ae6bf9f20efaaf

See more details on using hashes here.

File details

Details for the file pych_client-0.4.0-py3-none-any.whl.

File metadata

  • Download URL: pych_client-0.4.0-py3-none-any.whl
  • Upload date:
  • Size: 11.7 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/4.0.2 CPython/3.12.0

File hashes

Hashes for pych_client-0.4.0-py3-none-any.whl
Algorithm Hash digest
SHA256 95a8b7d5d9256cda39ce31ca8aae8dacd655eb1209faa811c7e4ed823cd684f5
MD5 e464fb2beeb871e94f5d11be2ef53863
BLAKE2b-256 c6ee3777a585c235b2348ff4fca7f0f92b543798e3b9a3855689f60b65fbd4fc

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page