Справочная документация по модулю chdb_hook

​

Краткое описание

# LOAD 'chdb_hook';
LOAD

# CREATE TABLE times (
    id     INT NOT NULL,
    months INT NOT NULL,
    days   INT NOT NULL
);
CREATE TABLE

# COPY times FROM 's3://datasets-documentation/my-test-bucket-768/{some,another}_prefix/some_file_{1..3}.csv';
COPY 18

​

Описание

​

Загрузка

• Явно, командой LOAD; действует на протяжении сеанса:
  LOAD 'chdb_hook';
  
  SQL Console в ClickHouse Cloud пока не поддерживает команду LOAD 'chdb_hook', однако её можно выполнить через psql или любое другое подключение к базе данных. Либо обратитесь к своему представителю службы поддержки, чтобы её добавили в конфигурацию вашего сервиса Postgres, после чего её можно будет использовать в SQL Console.
• Для всех сеансов — с помощью настройки [session_preload_libraries] в postgresql.conf:
  session_preload_libraries = chdb_hook
  
  Или через ALTER SYSTEM:
  ALTER SYSTEM SET session_preload_libraries = 'chdb_hook';
  
  Эту настройку можно задать и на уровне отдельной базы данных с помощью ALTER DATABASE:
  ALTER DATABASE name SET session_preload_libraries = 'chdb_hook';
  
  Или для конкретных пользователей и групп с помощью ALTER ROLE:
  ALTER ROLE name SET session_preload_libraries = 'chdb_hook';
  
• При запуске сервера — с помощью настройки [shared_preload_libraries], чтобы расширение всегда было доступно во всех сеансах и базах данных:
  shared_preload_libraries = chdb_hook
  

​

Перегрузка COPY

CREATE TABLE times (
    id     INT PRIMARY KEY,
    months INT NOT NULL,
    days   INT NOT NULL
);

COPY times FROM 's3://datasets-documentation/my-test-bucket-768/some_prefix/some_file_1.csv';

​

Привилегии

​

Схемы URL

​

Форматы URL

​

File

file:///tmp/users.parquet

​

HTTP

https://datasets-documentation.s3.eu-west-3.amazonaws.com/my-test-bucket-768/some_prefix/some_file_1.csv

​

S3

s3://{bucket}/{path}

s3://{bucket}.s3.{region}.amazonaws.com/{path}

​

GCS

gs://storage.googleapis.com/{bucket}/{path}

gs://{bucket}/{path}

​

Azure Blob Storage

az://{account}.blob.core.windows.net/{container}/{blob}

az://{host}/{container}/{blob}

​

Azure ABFS

abfs://{container}@{account}.dfs.core.windows.net/{blob}

​

URL-адреса HDFS

hdfs://{host}/{path}
hdfs://{host}:{port}/{path}

​

Подстановочные шаблоны в путях

• *: соответствует произвольному количеству символов, кроме /, включая пустую строку.
• ?: соответствует любому одиночному символу.
• {groucho,harpo,chico}: подставляет любую из строк «groucho», «harpo» и «chico». Строки могут содержать /.
• {N..M}: соответствует любому числу >= N и <= M.
• **: рекурсивно соответствует всем файлам в каталоге.

• https://clickhouse-public-datasets.s3.amazonaws.com/my-test-bucket-768/some_prefix/some_file_1.csv
• https://clickhouse-public-datasets.s3.amazonaws.com/my-test-bucket-768/some_prefix/some_file_2.csv
• https://clickhouse-public-datasets.s3.amazonaws.com/my-test-bucket-768/some_prefix/some_file_3.csv
• https://clickhouse-public-datasets.s3.amazonaws.com/my-test-bucket-768/another_prefix/some_file_1.csv
• https://clickhouse-public-datasets.s3.amazonaws.com/my-test-bucket-768/another_prefix/some_file_2.csv
• https://clickhouse-public-datasets.s3.amazonaws.com/my-test-bucket-768/another_prefix/some_file_3.csv

CREATE TABLE times (
    id     INT NOT NULL,
    months INT NOT NULL,
    days   INT NOT NULL
);

COPY times FROM 's3://datasets-documentation/my-test-bucket-768/{some,another}_prefix/some_file_{1..3}.csv';

​

Параметры

​

format:

​

structure

COPY users TO 'file:///tmp/users.parquet' (
    structure 'id Int64, name String, age Nullable(UInt8), attributes JSON'
);

​

access_key и access_secret

• S3: AWS [ключ доступа ID и access secret], которые чаще всего задаются переменными окружения AWS_ACCESS_KEY_ID и AWS_SECRET_ACCESS_KEY
• GCS: GCP HMAC key and secret
• Azure: имя Azure Storage account и [ключ доступа]

​

session_token

​

compression

• auto (по умолчанию)
• none
• gzip или gz
• brotli или br
• xz или LZMA
• zstd или zst
• lz4
• bz2
• snappy

​

timeout

​

Отладка

ERROR:  chdb: error executing chDB query
DETAIL:  Code: 53. DB::Exception: Requested type of column p doesn't match parquet schema
CONTEXT:  query: SELECT * FROM file({path:String}, {format:String}, {structure:String})
STATEMENT:  COPY "users" FROM 'file:///tmp/users.data' (format 'Parquet');

2026-08-08 09:41:06.842 EDT [59940] LOG:  executing chDB query
2026-08-08 09:41:06.842 EDT [59940] DETAIL:  query: SELECT * FROM file({path:String}, {format:String}, {structure:String})
2026-08-08 09:41:06.842 EDT [59940] CONTEXT:  params: { path: "/tmp/users.data", format: "Parquet", structure: "user_id Nullable(Int64), username Nullable(String), password Nullable(String)" }
2026-08-08 09:41:06.842 EDT [59940] STATEMENT:  COPY "users" FROM 'file:///tmp/users.data' (format 'Parquet');

​

Перегрузка CREATE TABLE

CREATE TABLE reviews () WITH (
    structure_from = 's3://datasets-documentation/amazon_reviews/amazon_reviews_2015.snappy.parquet'
);

CREATE TABLE reviews () WITH (
    copy_from = 's3://datasets-documentation/amazon_reviews/amazon_reviews_2015.snappy.parquet'
);

CREATE TABLE times (
    id     INT NOT NULL,
    months INT NOT NULL,
    days   INT NOT NULL
) WITH (copy_from = 's3://datasets-documentation/my-test-bucket-768/some_prefix/some_file_1.csv');

CREATE TABLE users () WITH (
    copy_from     = 's3://my-bucket/users.csv',
    access_key    = 'AKIAIOSFODNN7EXAMPLE',
    access_secret = 'wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY',
    format        = 'CSVWithNames',
    fillfactor    = 90
);

​

Ограничения

• Невозможно выполнить COPY для отношений с политиками [безопасность на уровне строк], которые применяются к копирующей роли. Postgres применяет такие политики, переписывая COPY TO в запрос, а chdb_hook этого не поддерживает.
• В ClickHouse нет NULL-массива, поэтому вместо NULL COPY TO сохраняет пустой массив ([]).
• ClickHouse представляет эквиваленты lseg, path и polygon в виде массивов, поэтому NULL-значения этих типов при COPY TO также превращаются в пустой массив ([]).
• Если в заданной структуре столбец не определён как Nullable, NULL-значения будут выведены как значения по умолчанию. Всегда явно определяйте столбцы с типом Nullable в структуре, чтобы избежать такого преобразования.
• Незамкнутый path, последняя точка которого совпадает с первой, выводится как замкнутый путь.
• В Protobuf в повторяющемся поле нет null, поэтому NULL-значения в массивах опускаются.
• JSON type в chDB поддерживает только объекты JSON; заменяйте отображение по умолчанию String для json и jsonb на JSON только в том случае, если все значения являются объектами JSON. (ClickHouse/ClickHouse#68428)
• JSON type в chDB игнорирует null: ключи объекта со значениями NULL будут опущены при выводе. Заменяйте отображение по умолчанию String для json и jsonb на JSON только в том случае, если значения объекта не равны null либо их потеря допустима. (ClickHouse/ClickHouse#68428)
• Форматы JSON, JSONCompact и JSONColumnsWithMetadata всегда проверяют UTF-8, поэтому выводят значения bytea с символами замены.
• COPY FROM читает поле Protobuf Nullable, содержащее пустую строку или ноль, как NULL. (chdb-io/chdb-core#152)
• COPY TO в Parquet отбрасывает NULL из собственного null map типа Nullable Tuple. (ClickHouse/ClickHouse#112427)
• В форматах Parquet, Arrow, ArrowStream, ORC, Avro, Protobuf, ProtobufList, MsgPack и BSONEachRow нет типа, соответствующего time в Postgres или Time64 в chDB. Чтобы сохранить значения, задавайте столбцы time как String в явной структуре.
• Вывод Protobuf усекает значения временных меток до секунд.
• Вывод Protobuf не поддерживает даты ранее 1970-01-01. Чтобы сохранить значения, задавайте столбцы time как String в явной структуре. (ClickHouse/ClickHouse#111860)
• Форматы CSVWithNames и CSVWithNamesAndTypes в настоящее время не могут импортировать NULL-значения box или circle. (ClickHouse/ClickHouse#115523)

​

Типы данных

​

Postgres в chDB

​

Преобразование временных меток

​

chDB в Postgres

​

Кодирование текста

ERROR:  invalid byte sequence for encoding "UTF8": 0x00

CREATE TABLE logs (id bigint, payload bytea) WITH (
    copy_from = 's3://my-bucket/logs.parquet'
);

​

Настройки

​

chdb_hook.max_memory

SET chdb_hook.max_memory = '1 GB';

• B (байты)
• kB (килобайты)
• MB (мегабайты)
• GB (гигабайты)
• TB (терабайты)

​

chdb_hook.max_threads

SET chdb_hook.max_threads = 4;

​

chdb_hook.max_parsing_threads

SET chdb_hook.max_parsing_threads = 2;

​

Политика версионирования

• Мажорная версия увеличивается при изменениях API
• Минорная версия увеличивается при обратно совместимых изменениях SQL
• Патч-версия увеличивается при изменениях, затрагивающих только бинарный файл

SELECT version FROM pg_get_loaded_modules() WHERE module_name = 'chdb_hook';

​

Авторы

• David E. Wheeler
• serprex

​

Авторские права