ClickHouse для TrueAsync: маппинг типов

Как типы колонок ClickHouse отображаются в PHP при чтении и что каждый тип принимает при вставке.

Маппинг типов ​

Как типы колонок ClickHouse отображаются в PHP-значения при чтении (результаты query()) и что каждый принимает при записи (insert/insertBatch).

Чтение: ClickHouse → PHP ​

ClickHousePHPПримечания
Int8…Int64, UInt8…UInt32int
UInt64int / floatзначения выше PHP_INT_MAX переполняются во float
Int128, UInt128stringдесятичная строка (без потерь)
Float32, Float64float
String, FixedStringstring
Boolbool
Enum8, Enum16stringметка (label)
UUIDstringканоническая запись 8-4-4-4-12
IPv4, IPv6stringтекстовый адрес
Decimal, Decimal32/64/128stringбез потерь
Date, Date32, DateTime, DateTime64DateTimeImmutableUTC; DateTime64 сохраняет дробную часть секунды
Array(T)listрекурсивно
Nullable(T)null | T
Tuple(...)listпозиционно
Map(K, V)arrayассоциативный
LowCardinality(String)stringвключая LowCardinality(Nullable(String)) → null|string

LowCardinality поверх нестроковых типов не поддерживается нижележащей clickhouse-cpp на чтении и не производится.

Запись: PHP → ClickHouse ​

Типы колонок берутся из серверного sample-блока INSERT; PHP-значение кодируется в этот тип.

ClickHouseПринимает (PHP)
Int*, UInt*int
Float32/64float или int
String, FixedStringstring
Boolbool
Date, Date32, DateTimeint (unix-секунды) или DateTimeInterface
DateTime64int/float секунды или DateTimeInterface (дробная часть сохраняется)
UUIDstring
IPv4, IPv6string (текстовый адрес)
Enum8, Enum16string-метка или int-значение
Decimal, Decimal32/64/128string (или число; парсится с масштабом колонки)
Nullable(T)null или значение T
Array(T)list (вложенные массивы и Array(Nullable(T)) поддерживаются)
Tuple(...)list, позиционно
Map(K, V)ассоциативный array

Колонки LowCardinality этот клиент пока не может писать (ограничение clickhouse-cpp). Вставляйте во внутренний тип или используйте INSERT … SELECT.

Примеры Date / DateTime ​

php
// Все три варианта пишут одну и ту же колонку DateTime:
$client->insert("t", ["ts"], [
    [1717761600],                                              // unix-секунды
    [new DateTimeImmutable('2026-06-07 12:00:00', new DateTimeZone('UTC'))],
]);

// DateTime64(3) сохраняет миллисекунды:
$client->insert("t64", ["ts"], [
    [new DateTimeImmutable('2026-06-07 12:00:00.500', new DateTimeZone('UTC'))],
]);

Вложенные примеры ​

php
$client->insert("nested", ["arr", "tup", "m"], [
    [
        [[1, 2], [3]],            // Array(Array(Int32))
        [42, "hi"],               // Tuple(UInt32, String)
        ["a" => 1, "b" => 2],     // Map(String, UInt32)
    ],
]);