Documentation de référence du module chdb_hook

​

Synopsis

# 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

​

Description

​

Chargement

• Explicitement, via la commande LOAD ; valable pour la durée d’une session :
  LOAD 'chdb_hook';
  
  La SQL Console de ClickHouse Cloud ne prend pas encore en charge la commande LOAD 'chdb_hook', mais celle-ci peut être exécutée via psql ou toute autre connexion à la base de données. Sinon, contactez votre interlocuteur Support pour l’ajouter à la configuration de votre service Postgres ; elle pourra ensuite être utilisée dans la SQL Console.
• Pour toutes les sessions, via le paramètre [session_preload_libraries], dans postgresql.conf :
  session_preload_libraries = chdb_hook
  
  Ou via ALTER SYSTEM :
  ALTER SYSTEM SET session_preload_libraries = 'chdb_hook';
  
  Ce paramètre peut également être défini base de données par base de données via ALTER DATABASE :
  ALTER DATABASE name SET session_preload_libraries = 'chdb_hook';
  
  Ou pour des utilisateurs et des groupes spécifiques via ALTER ROLE :
  ALTER ROLE name SET session_preload_libraries = 'chdb_hook';
  
• Au démarrage du serveur, via le paramètre [shared_preload_libraries], afin qu’il soit toujours disponible pour toutes les sessions et toutes les bases de données :
  shared_preload_libraries = chdb_hook
  

​

Surcharge de 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';

​

Privilèges

​

Schémas d’URL

​

Formats d’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}

​

Caractères génériques dans les chemins

• * : correspond à un nombre quelconque de caractères, à l’exception de /, y compris la chaîne vide.
• ? : correspond à un seul caractère quelconque.
• {groucho,harpo,chico} : substitue l’une des chaînes “groucho”, “harpo” ou “chico”. Ces chaînes peuvent contenir /.
• {N..M} : correspond à tout nombre >= N et <= M.
• ** : correspond de manière récursive à tous les fichiers d’un répertoire.

• 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';

​

Options

​

format :

​

structure

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

​

access_key et access_secret

• S3 : un [access key ID et access secret] AWS, souvent définis à l’aide des environment variables AWS_ACCESS_KEY_ID et AWS_SECRET_ACCESS_KEY
• GCS : un HMAC key and secret GCP
• Azure : un nom de storage account Azure et une access key

​

session_token

​

compression

• auto (par défaut)
• none
• gzip ou gz
• brotli ou br
• xz ou LZMA
• zstd ou zst
• lz4
• bz2
• snappy

​

timeout

​

encoding_check

• fail (par défaut) : lève une erreur
• remove supprime les octets invalides
• replace : avec l’encodage UTF-8, remplace les octets invalides par le caractère de remplacement Unicode (�) ; équivaut à remove pour les autres encodages
• truncate tronque le texte au premier octet invalide

​

Débogage

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');

​

Surcharge de CREATE TABLE

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

CREATE TABLE reviews () WITH (
    encoding_check = 'replace',
    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 logs () WITH (
    copy_from  = 's3://chdb-lakedata-public/logs/logs-2026-08-26.csv',
    format     = 'CSVWithNames',
    timeout    = 60000,
    fillfactor = 90
);

​

Limitations

• Impossible d’effectuer un COPY sur des relations dont les politiques de row-level security s’appliquent au rôle effectuant la copie. Postgres applique ces politiques en réécrivant COPY TO sous forme de requête, ce que chdb_hook ne prend pas en charge.
• Impossible d’effectuer un COPY FROM depuis une URL avec une clause WHERE.
• chDB ne dispose pas de tableau NULL : COPY TO stocke donc un tableau vide ([]) pour un NULL.
• chDB représente les équivalents de lseg, path ou polygon sous forme de tableaux ; les valeurs NULL de ces types sont donc elles aussi converties par COPY TO en tableau vide ([]).
• ClickHouse ne dispose pas de tableau NULL : COPY TO stocke donc un tableau vide ([]) pour un NULL.
• ClickHouse représente les équivalents de lseg, path ou polygon sous forme de tableaux ; les valeurs NULL de ces types sont donc elles aussi converties par COPY TO en tableau vide ([]).
• Les valeurs NULL produites pour une structure spécifiée qui ne définit pas la colonne comme Nullable seront émises sous forme de valeurs par défaut. Définissez toujours explicitement les colonnes nullables dans la structure pour éviter cette conversion.
• Un path ouvert dont le dernier point est identique au premier est émis comme un chemin fermé.
• Protobuf n’admet pas de valeur null dans un champ répété : il omet donc les valeurs NULL dans les tableaux.
• Le JSON type de chDB ne prend en charge que les objets JSON ; ne remplacez le mappage String par défaut de json et jsonb par JSON que si toutes les valeurs sont des objets JSON. (ClickHouse/ClickHouse#68428)
• Le JSON type de chDB ignore les null ; les clés d’objet dont la valeur est NULL seront omises en sortie. Ne remplacez le mappage String par défaut de json et jsonb par JSON que si les valeurs des objets ne sont pas null ou si leur perte est acceptable. (ClickHouse/ClickHouse#68428)
• Les formats JSON, JSONCompact et JSONColumnsWithMetadata valident toujours l’UTF-8 ; ils émettent donc les valeurs bytea avec des caractères de remplacement.
• COPY FROM interprète un champ Protobuf Nullable contenant une chaîne vide ou un zéro comme NULL. (chdb-io/chdb-core#152)
• COPY TO en Parquet supprime les NULL du null map propre à un Tuple Nullable. (ClickHouse/ClickHouse#112427)
• Les formats Parquet, Arrow, ArrowStream, ORC, Avro, Protobuf, ProtobufList, MsgPack et BSONEachRow n’ont aucun type correspondant au type time de Postgres ou Time64 de chDB. Configurez les colonnes time comme des String dans une structure explicite pour préserver leurs valeurs.
• La sortie Protobuf tronque les valeurs timestamp à la seconde.
• La sortie Protobuf ne prend pas en charge les dates antérieures au 1970-01-01. Configurez les colonnes time comme des String dans une structure explicite pour préserver leurs valeurs. (ClickHouse/ClickHouse#111860)

​

Types de données

​

De Postgres vers chDB

​

Conversion des timestamps

​

De chDB vers Postgres

​

Correspondances de types manuelles

CREATE TYPE event_status AS ENUM ('new', 'done');
CREATE TYPE event_point AS (x integer, y integer);
CREATE TYPE event_label AS (key text, value bigint);
CREATE TYPE event_item AS (id integer, name text);

CREATE TABLE events (
    status event_status,
    point  event_point,
    labels event_label[],
    items  event_item[]
);

COPY events FROM 's3://chdb-lakedata-public/examples/events.parquet' (
    structure $$
        status Enum8('new' = 1, 'done' = 2),
        point  Tuple(Int32, Int32),
        labels Map(String, Int64),
        items  Array(Tuple(id Int32, name String))
    $$
);

​

Encodage du texte

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

CREATE TABLE logs (req_id numeric(20,0), resource bytea) WITH (
    copy_from = 's3://chdb-lakedata-public/logs/logs-2026-08-26.parquet'
);

​

Paramètres

​

chdb_hook.max_memory

SET chdb_hook.max_memory = '1 GB';

• B (octets)
• kB (kilooctets)
• MB (mégaoctets)
• GB (gigaoctets)
• TB (téraoctets)

​

chdb_hook.max_threads

SET chdb_hook.max_threads = 4;

​

chdb_hook.max_parsing_threads

SET chdb_hook.max_parsing_threads = 2;

​

Politique de versionnage

• La major version est incrémentée en cas de changements d’API
• La minor version est incrémentée en cas de changements SQL rétrocompatibles
• La version de patch est incrémentée en cas de changements portant uniquement sur le binary

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

​

Auteurs

• David E. Wheeler
• serprex

​

Droits d’auteur