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}):
Noneis\N(NULLinside an array, tuple or map)boolis1/0(TRUE/FALSEinside a container)int,float(nan,+inf,-inf),Decimalas numbersstrandUUIDwith tabs, newlines, quotes and backslashes escaped (quoted inside a container)- an aware
datetimeas Unix seconds, with microseconds when it has them (inside a container, its UTC date'YYYY-MM-DD', which every date and time type accepts); adateasYYYY-MM-DD - a
listortupleas an array,TupleParamas a tuple, aMappingas a map
Any other value, and a naive datetime, is a TypeError.
Types#
| Type | Definition | Description |
|---|---|---|
Setting | type Setting = bool | int | float | str | Mapping[str, str] | A ClickHouse setting's value; a mapping is a map setting
( |
Settings | type Settings = Mapping[str, Setting] | ClickHouse settings by name ( |
Classes#
Functions#
format_query_param#
format_query_param(value) -> strvalue as the text of a query parameter (see the module).
| Parameter | Type | Description |
|---|---|---|
value | object |
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) -> strvalue 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).
| Parameter | Type | Description |
|---|---|---|
value | Setting |
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) -> strThe 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.
| Parameter | Type | Description |
|---|---|---|
value | object |
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"