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';
  
  ClickHouse Cloud SQL 콘솔은 아직 LOAD 'chdb_hook' 명령을 지원하지 않지만, psql이나 다른 데이터베이스 연결을 통해 실행할 수 있습니다. 그렇지 않은 경우 지원 담당자에게 문의하여 Postgres 서비스 구성에 추가하면, 이후 SQL 콘솔에서도 사용할 수 있습니다.
• 모든 세션에 적용하려면 postgresql.conf에서 [session_preload_libraries] 설정을 사용하십시오:
  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}

​

HDFS URL

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 및 액세스 시크릿]으로, 보통 AWS_ACCESS_KEY_ID 및 AWS_SECRET_ACCESS_KEY 환경 변수로 정의됩니다
• GCS: GCP [HMAC 키 및 시크릿]
• Azure: Azure 스토리지 계정 이름 및 [액세스 키]

​

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

​

제한 사항

• 복사를 수행하는 역할에 적용되는 row-level security 정책이 있는 릴레이션은 COPY할 수 없습니다. Postgres는 COPY TO를 쿼리로 다시 작성하는 방식으로 이러한 정책을 적용하는데, chdb_hook은 이를 지원하지 않습니다.
• ClickHouse에는 NULL 배열이 없으므로, COPY TO는 NULL을 빈 배열([])로 저장합니다.
• ClickHouse는 lseg, path, polygon에 해당하는 값을 배열로 표현합니다. 따라서 이러한 타입의 NULL 값도 COPY TO 시 빈 배열([])로 출력됩니다.
• 지정된 structure에서 해당 컬럼을 Nullable로 정의하지 않으면 NULL 값은 기본값으로 출력됩니다. 이러한 변환을 방지하려면 structure에 널 허용 컬럼을 항상 명시적으로 정의하십시오.
• 마지막 점이 첫 번째 점과 같은 열린 path는 닫힌 경로로 출력됩니다.
• Protobuf의 반복 필드에는 null이 없으므로 배열의 NULL 값은 생략됩니다.
• chDB JSON type은 JSON 객체만 지원합니다. 모든 값이 JSON 객체인 경우에만 json 및 jsonb의 기본 String 매핑을 JSON으로 재정의하십시오. (ClickHouse/ClickHouse#68428)
• chDB JSON type은 null을 무시하므로, NULL 값을 가진 객체 키는 출력 시 생략됩니다. 객체 값이 null이 아니거나 그 값의 손실을 허용할 수 있는 경우에만 json 및 jsonb의 기본 String 매핑을 JSON으로 재정의하십시오. (ClickHouse/ClickHouse#68428)
• JSON, JSONCompact, JSONColumnsWithMetadata 포맷은 항상 UTF-8을 검사하므로, bytea 값을 대체 문자로 치환하여 출력합니다.
• COPY FROM은 빈 문자열이나 0을 포함하는 Protobuf Nullable 필드를 NULL로 읽습니다. (chdb-io/chdb-core#152)
• Parquet으로의 COPY TO는 Nullable Tuple 자체의 null map에서 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)
• CSVWithNames 및 CSVWithNamesAndTypes 포맷은 현재 NULL box 또는 circle 값을 가져올 수 없습니다. (ClickHouse/ClickHouse#115523)

​

데이터 타입

​

Postgres to 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

​

저작권