GitHub

ClickhouseDriver

API reference for ClickhouseDriver.

Requests to one server (see the module).

Attributes

AttributeTypeDescription
http_client= http_client
connection= connection
connection_id= str(uuid.uuid4())

Functions

__init__

__init__(http_client, connection) -> None
ParameterTypeDescription
http_clientHttpClientService[HttpClientError]
connectionConnection
def __init__(
    self, http_client: HttpClientService[HttpClientError], connection: Connection
) -> None:
    self.http_client = http_client
    self.connection = connection
    self.connection_id = str(uuid.uuid4())

ping

ping() -> Effect[None, ClickhouseRequestError]

GET /ping, the body drained; a failure is logged at WARN.

Returns Effect[None, ClickhouseRequestError]

def ping(self) -> Effect[None, ClickhouseRequestError]:
    """``GET /ping``, the body drained; a failure is logged at
    ``WARN``."""

    def build() -> Effect[None, ClickhouseRequestError]:
        request = http_request.get(self.connection.url + "/ping", headers=self._headers({}))
        return self._send(request).flat_map(lambda response: response.bytes_).as_void()

    pinged = suspend(build)
    if not self.connection.logs("WARN"):
        return pinged
    annotations = {
        "module": "Connection",
        "connection_id": self.connection_id,
        "query_id": str(uuid.uuid4()),
    }
    return pinged.tap_error(
        lambda error: log_warning("Ping: HTTP request error.", error).annotate_logs(annotations)
    )

query

query(query, *, format='JSON', **options) -> Effect[ResultSet, ClickhouseRequestError]

query with FORMAT <format> appended; its parameters go in a multipart body under use_multipart_params (or, once long, use_multipart_params_auto).

ParameterTypeDescription
querystr
formatDataFormat = 'JSON'
optionsUnpack[RequestOptions] = {}

Returns Effect[ResultSet, ClickhouseRequestError]

def query(
    self, query: str, *, format: DataFormat = "JSON", **options: Unpack[RequestOptions]
) -> Effect[ResultSet, ClickhouseRequestError]:
    """``query`` with ``FORMAT <format>`` appended; its parameters go in
    a multipart body under ``use_multipart_params`` (or, once long,
    ``use_multipart_params_auto``)."""
    query_id = self._query_id(options.get("query_id"))
    body = f"{_trim(query)} \nFORMAT {format}"
    connection = self.connection

    def build() -> Effect[HttpClientResponse, ClickhouseRequestError]:
        settings = self._settings(options, compressed=True)
        has_params = bool(options.get("query_params"))
        multipart = has_params and connection.use_multipart_params
        entries = None
        if has_params and not multipart and connection.use_multipart_params_auto:
            entries = self._param_entries(options)
            if form_encoded_length(entries) > MAX_URL_BIND_PARAM_LENGTH:
                multipart, entries = True, None
        request = http_request.post(
            connection.url + "/",
            url_params=self._url_params(
                query_id, options, settings, param_entries=entries, params_in_url=not multipart
            ),
            headers=self._headers(options),
        )
        asked = settings.get("enable_http_compression")
        request = self._accept(
            request, (connection.decompress_response or "gzip") if _is_one(asked) else None
        )
        if multipart:
            boundary = f"----clickhouse-js-{uuid.uuid4()}"
            parts = {"query": body, **dict(self._param_entries(options))}
            request = request.body_text(
                _multipart(parts, boundary), f"multipart/form-data; boundary={boundary}"
            )
        else:
            request = request.body_text(body, "text/plain; charset=UTF-8")
        return self._send(request)

    sent = self._logged("Query", query_id, options, suspend(build))
    return sent.map(
        lambda response: ResultSet(response, query_id, format, connection.json.parse)
    )

command

command(query, **options) -> Effect[CommandResult, ClickhouseRequestError]

query as written; its body is drained.

ParameterTypeDescription
querystr
optionsUnpack[RequestOptions] = {}

Returns Effect[CommandResult, ClickhouseRequestError]

def command(
    self, query: str, **options: Unpack[RequestOptions]
) -> Effect[CommandResult, ClickhouseRequestError]:
    """``query`` as written; its body is drained."""
    query_id = self._query_id(options.get("query_id"))

    def done(response: HttpClientResponse) -> Effect[CommandResult, HttpClientError]:
        result = CommandResult(query_id, _summary(response.headers), response.headers)
        return response.bytes_.as_(result)

    sent = self._run_exec(_trim(query), query_id, options)
    return self._logged("Command", query_id, options, sent).flat_map(done)

exec

exec(query, **options) -> Effect[ResultSet, ClickhouseRequestError]

query as written (with its own FORMAT); read the body through the ResultSet.

ParameterTypeDescription
querystr
optionsUnpack[RequestOptions] = {}

Returns Effect[ResultSet, ClickhouseRequestError]

def exec(
    self, query: str, **options: Unpack[RequestOptions]
) -> Effect[ResultSet, ClickhouseRequestError]:
    """``query`` as written (with its own ``FORMAT``); read the body
    through the ``ResultSet``."""
    query_id = self._query_id(options.get("query_id"))
    sent = self._run_exec(_trim(query), query_id, options)
    return self._logged("Exec", query_id, options, sent).map(
        lambda response: ResultSet(response, query_id, None, self.connection.json.parse)
    )

insert

insert(*, table, values, format='JSONCompactEachRow', columns=None, **options) -> Effect[InsertResult, ClickhouseRequestError]

INSERT INTO <table> [(columns)] FORMAT <format> with values as its data. An empty list of rows sends nothing.

ParameterTypeDescription
tablestr
valuesInsertValues
formatDataFormat = 'JSONCompactEachRow'
columnsInsertColumns | None = None
optionsUnpack[RequestOptions] = {}

Returns Effect[InsertResult, ClickhouseRequestError]

def insert(
    self,
    *,
    table: str,
    values: InsertValues,
    format: DataFormat = "JSONCompactEachRow",
    columns: InsertColumns | None = None,
    **options: Unpack[RequestOptions],
) -> Effect[InsertResult, ClickhouseRequestError]:
    """``INSERT INTO <table> [(columns)] FORMAT <format>`` with
    ``values`` as its data. An empty list of rows sends nothing."""
    if isinstance(values, Sequence) and not isinstance(values, (str, bytes)) and not values:
        return succeed(InsertResult(False, ""))
    query_id = self._query_id(options.get("query_id"))
    query = f"INSERT INTO {table.strip()}{_columns(columns)} FORMAT {format}"

    def done(response: HttpClientResponse) -> Effect[InsertResult, HttpClientError]:
        result = InsertResult(True, query_id, _summary(response.headers), response.headers)
        return response.bytes_.as_(result)

    sent = self._with_body(values, format, query_id, options, query).flat_map(done)
    return self._logged("Insert", query_id, options, sent)