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 コマンドによる明示的なロード。session が続く間のみ有効です:
  LOAD 'chdb_hook';
  
  ClickHouse Cloud の SQL Console は現時点では LOAD 'chdb_hook' コマンドに対応していませんが、psql やその他の database connection 経由であれば実行できます。 そうでない場合は、サポート担当者に連絡して Postgres service の configuration に追加してもらってください。追加後は SQL Console でも使用できるようになります。
• すべての sessions を対象とする場合は、postgresql.conf で [session_preload_libraries] SETTING を指定します:
  session_preload_libraries = chdb_hook
  
  または ALTER SYSTEM を使用します:
  ALTER SYSTEM SET session_preload_libraries = 'chdb_hook';
  
  この SETTING は ALTER DATABASE を使って database 単位で設定することもできます:
  ALTER DATABASE name SET session_preload_libraries = 'chdb_hook';
  
  また、ALTER ROLE を使って特定のユーザーやグループに対して設定することもできます:
  ALTER ROLE name SET session_preload_libraries = 'chdb_hook';
  
• [shared_preload_libraries] SETTING により server 起動時にロードする方法。すべての sessions と databases から常に利用できるようになります:
  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';

​

Privileges

​

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}

​

HDFS URL

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

​

パスのワイルドカード

• *: / を除く任意の文字に任意個数一致します (空文字列を含む) 。
• ?: 任意の1文字に一致します。
• {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 の [access key ID と access secret]。多くの場合、環境変数 AWS_ACCESS_KEY_ID および AWS_SECRET_ACCESS_KEY で指定します
• GCS: GCP の HMACキーとシークレット
• Azure: Azure ストレージアカウント名と access key

​

session_token

​

compression

• auto (デフォルト)
• none
• gzip または gz
• brotli または br
• xz または LZMA
• zstd または zst
• lz4
• bz2
• snappy

​

timeout

​

encoding_check

• fail (デフォルト) : エラーを発生させます
• remove: 無効なバイトを削除します
• replace: UTF-8 エンコーディングの場合は、無効なバイトを Unicode の置換文字 (�) に置き換えます。その他のエンコーディングでは remove と同じ動作になります
• truncate: 最初に現れた無効なバイトの位置でテキストを切り詰めます

​

デバッグ

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

​

制限事項

• コピーを実行するロールに適用される row-level security policies が設定された relation は COPY できません。Postgres はこうした policies を適用する際に COPY TO をクエリへ書き換えますが、chdb_hook はこれをサポートしていません。
• WHERE 句を指定して URL から COPY FROM することはできません。
• chDB には NULL の Array が存在しないため、COPY TO は NULL を空の Array ([]) として格納します。
• chDB は lseg、path、polygon に相当するものを Array として表現します。そのため、これらの型の NULL 値も COPY TO では空の Array ([]) になります。
• ClickHouse には NULL の Array が存在しないため、COPY TO は NULL を空の Array ([]) として格納します。
• ClickHouse は lseg、path、polygon に相当するものを Array として表現します。そのため、これらの型の NULL 値も COPY TO では空の Array ([]) になります。
• 指定した structure でカラムが Nullable として定義されていない場合、NULL 値はそのデフォルト値として出力されます。この変換を避けるため、structure では nullable columns を必ず明示的に定義してください。
• 最後の点が最初の点と一致する開いた path は、閉じた path として出力されます。
• Protobuf の repeated field には null が存在しないため、Array 内の NULL 値は省略されます。
• chDB の JSON type は JSON オブジェクトのみをサポートします。json および jsonb のデフォルトの String マッピングを JSON で上書きするのは、すべての値が JSON オブジェクトである場合に限ってください。(ClickHouse/ClickHouse#68428)
• chDB の JSON type は null を無視するため、NULL 値を持つオブジェクトのキーは出力時に省略されます。json および jsonb のデフォルトの String マッピングを JSON で上書きするのは、オブジェクトの値が null でない場合、またはその欠落が許容できる場合に限ってください。(ClickHouse/ClickHouse#68428)
• JSON、JSONCompact、JSONColumnsWithMetadata フォーマットは常に UTF-8 を検証するため、bytea 値は 置換文字 を含んだ形で出力されます。
• COPY FROM は、空文字列またはゼロを含む Protobuf の Nullable フィールドを NULL として読み取ります。(chdb-io/chdb-core#152)
• Parquet への COPY TO は、Nullable Tuple 自身の null マップから NULL を削除します。(ClickHouse/ClickHouse#112427)
• Parquet、Arrow、ArrowStream、ORC、Avro、Protobuf、ProtobufList、MsgPack、BSONEachRow の各フォーマットには、Postgres の time や chDB の Time64 に対応する型がありません。値を保持するには、明示的な structure で time カラムを String として設定してください。
• Protobuf 出力では timestamp 値が秒単位に切り捨てられます。
• Protobuf 出力は 1970-01-01 より前の日付をサポートしません。値を保持するには、明示的な structure で time カラムを String として設定してください。(ClickHouse/ClickHouse#111860)

​

データ型

​

Postgres から chDB へ

​

Timestamp 変換

​

chDB から Postgres へ

​

手動での型マッピング

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

​

テキストエンコーディング

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

​

設定

​

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;

​

Versioning Policy

• major version は API の変更時にインクリメントされます
• minor version は後方互換性のある SQL の変更時にインクリメントされます
• patch バージョンは binary のみの変更時にインクリメントされます

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

​

著者

• David E. Wheeler
• serprex

​

著作権