GitHub

API reference for params.

Values as ClickHouse's HTTP interface reads them: query parameters (param_<name> URL entries, as @clickhouse/client's formatQueryParams writes them), settings, and the type a value is bound as when no type is given.

A parameter is text the server parses as its placeholder's type ({p1: Int64}):

  • None is \N (NULL inside an array, tuple or map)
  • bool is 1 / 0 (TRUE / FALSE inside a container)
  • int, float (nan, +inf, -inf), Decimal as numbers
  • str and UUID with tabs, newlines, quotes and backslashes escaped (quoted inside a container)
  • an aware datetime as Unix seconds, with microseconds when it has them (inside a container, its UTC date 'YYYY-MM-DD', which every date and time type accepts); a date as YYYY-MM-DD
  • a list or tuple as an array, TupleParam as a tuple, a Mapping as a map

Any other value, and a naive datetime, is a TypeError.

Types

TypeDefinitionDescription
Settingtype Setting = bool | int | float | str | Mapping[str, str]

A ClickHouse setting's value; a mapping is a map setting ({'system.numbers':'number != 3'}).

Settingstype Settings = Mapping[str, Setting]

ClickHouse settings by name ({"max_threads": 4}).

Classes

Functions

format_query_param

format_query_param(value) -> str

value as the text of a query parameter (see the module).

ParameterTypeDescription
valueobject

Returns str

def format_query_param(value: object) -> str:  # noqa: PLR0911, PLR0912
    """``value`` as the text of a query parameter (see the module)."""
    match value:
        case None:
            return "\\N"
        case bool():
            return "1" if value else "0"
        case int():
            return str(value)
        case float():
            if math.isnan(value):
                return "nan"
            if math.isinf(value):
                return "+inf" if value > 0 else "-inf"
            return js_number(value)
        case Decimal():
            return str(value)
        case str() | uuid.UUID():
            return str(value).translate(_ESCAPES)
        case datetime():
            return _unix_seconds(value)
        case date():
            return value.isoformat()
        case list() | tuple():
            items = cast("Sequence[object]", value)
            return "[" + ",".join(_in_container(item) for item in items) + "]"
        case TupleParam():
            return "(" + ",".join(_in_container(item) for item in value.values) + ")"
        case Mapping():
            entries = cast("Mapping[object, object]", value)
            return (
                "{"
                + ",".join(f"{_in_container(k)}:{_in_container(v)}" for k, v in entries.items())
                + "}"
            )
        case _:
            raise TypeError(f"Unsupported value in query parameters: [{value!r}].")

format_setting

format_setting(value) -> str

value as the text of a setting (@clickhouse/client's formatQuerySettings). A map's keys and values are string literals, with quotes and backslashes escaped (@clickhouse/client writes them as they are).

ParameterTypeDescription
valueSetting

Returns str

def format_setting(value: Setting) -> str:
    """``value`` as the text of a setting (``@clickhouse/client``'s
    ``formatQuerySettings``). A map's keys and values are string literals, with quotes and
    backslashes escaped (``@clickhouse/client`` writes them as they are)."""
    match value:
        case bool():
            return "1" if value else "0"
        case int() | float():
            return js_number(value)
        case str():
            return value
        case _:
            return "{" + ",".join(f"{_quote(k)}:{_quote(v)}" for k, v in value.items()) + "}"

type_of

type_of(value) -> str

The ClickHouse type a value is bound as when no type is given (Effect's typeFromUnknown): Bool, Int64 (UInt64 or Int256 past it), Float64, DateTime (DateTime64(6) with microseconds), Date, Array(<type of the first item>), else String.

ParameterTypeDescription
valueobject

Returns str

def type_of(value: object) -> str:  # noqa: PLR0911
    """The ClickHouse type a value is bound as when no type is given (Effect's
    ``typeFromUnknown``): ``Bool``, ``Int64`` (``UInt64`` or ``Int256`` past it),
    ``Float64``, ``DateTime`` (``DateTime64(6)`` with microseconds),
    ``Date``, ``Array(<type of the first item>)``, else ``String``."""
    match value:
        case bool():
            return "Bool"
        case int():
            return (
                "Int64"
                if -_INT64 <= value < _INT64
                else "UInt64"
                if 0 <= value < _UINT64
                else "Int256"
            )
        case float():
            return "Float64"
        case datetime():
            return "DateTime" if value.microsecond == 0 else "DateTime64(6)"
        case date():
            return "Date"
        case list() | tuple():
            items = cast("Sequence[object]", value)
            return f"Array({type_of(items[0] if items else None)})"
        case _:
            return "String"