الوثائق المرجعية لوحدة 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}

​

عناوين HDFS URL

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

​

أنماط المسار (Path Wildcards)

• *: تطابق أي عدد من المحارف عدا /، بما في ذلك السلسلة الفارغة.
• ?: تطابق محرفًا واحدًا أيًا كان.
• {groucho,harpo,chico}: تستبدل أي من السلاسل “groucho” و”harpo” و “chico”. وقد تحتوي هذه السلاسل على /.
• {N..M}: تطابق أي رقم >= N و<= M.
• **: تطابق تعاوديًا جميع الملفات في الـ directory.

• 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: access key ID and access secret خاص بـ AWS، ويُعرَّفان غالبًا عبر environment variables AWS_ACCESS_KEY_ID وAWS_SECRET_ACCESS_KEY
• GCS: HMAC key and secret خاص بـ GCP
• Azure: اسم Azure Storage account وaccess key

​

session_token

​

compression

• auto (الافتراضي)
• none
• gzip أو gz
• brotli أو br
• xz أو LZMA
• zstd أو zst
• lz4
• bz2
• snappy

​

timeout

​

Debugging

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 على العلاقات التي تنطبق عليها سياسات row-level security الخاصة بالدور الذي يقوم بالنسخ. إذ يطبّق Postgres هذه السياسات عن طريق إعادة كتابة COPY TO في صورة استعلام، وهو ما لا يدعمه chdb_hook.
• لا يوجد في ClickHouse مصفوفة NULL، لذا يخزّن COPY TO مصفوفة فارغة ([]) بدلاً من قيمة NULL.
• يمثّل ClickHouse ما يعادل lseg أو path أو polygon على هيئة مصفوفات؛ وبالتالي فإن قيم NULL من هذه الأنواع يَنسخها COPY TO أيضاً كمصفوفة فارغة ([]).
• قيم NULL المُخرَجة وفق structure محددة لا تُعرِّف العمود على أنه Nullable ستُخرَج بقيمها الافتراضية. لذا عرّف دائماً الأعمدة القابلة لقيم NULL بشكل صريح في structure لتجنّب هذا التحويل.
• المسار 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 في structure صريحة للحفاظ على قيمها.
• يقتطع إخراج Protobuf قيم timestamp إلى مستوى الثانية.
• لا يدعم إخراج Protobuf التواريخ السابقة لـ 1970-01-01. هيّئ أعمدة time كـ String في structure صريحة للحفاظ على قيمها. (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;

​

سياسة الإصدارات

• يزيد رقم الإصدار الرئيسي (major version) عند حدوث تغييرات في واجهة برمجة التطبيقات
• يزيد رقم الإصدار الفرعي (minor version) عند حدوث تغييرات SQL متوافقة مع الإصدارات السابقة
• يزيد رقم إصدار التصحيح (patch) عند التغييرات التي تمسّ الملف الثنائي (binary) وحده

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

​

المؤلفون

• David E. Wheeler
• serprex

​

حقوق النشر