كتالوج REST | ClickHouse Docs

ميزة Beta

يدعم ClickHouse التكامل مع عدة catalogs‏ (Unity وGlue وREST وPolaris وغيرها). سيرشدك هذا الدليل خلال الخطوات اللازمة للاستعلام عن بياناتك باستخدام ClickHouse ومواصفة كتالوج REST.

كتالوج REST هي مواصفة موحّدة لواجهة برمجة تطبيقات خاصة بـ Iceberg catalogs، وتدعمها منصات متعددة، منها:

بيئات التطوير المحلية (باستخدام إعدادات docker-compose)
الخدمات المُدارة مثل Tabular.io
تنفيذات كتالوج REST ذاتية الاستضافة

إعداد بيئة التطوير المحلية

لأغراض التطوير والاختبار المحليَّين، يمكنك استخدام إعداد REST catalog مُشغَّل ضمن حاويات. ويُعد هذا النهج مثاليًا للتعلّم، وبناء النماذج الأوّلية، وبيئات التطوير.

المتطلبات الأساسية

Docker وDocker Compose: تأكد من أن Docker مُثبّت ويعمل
إعداد تجريبي: يمكنك استخدام إعدادات docker-compose مختلفة (انظر صور Docker البديلة أدناه)

إعداد كتالوج REST محلي

يمكنك استخدام تطبيقات مختلفة لـ كتالوج REST تعمل داخل حاويات، مثل Databricks docker-spark-iceberg، إذ يوفّر بيئة متكاملة تضم Spark + Iceberg + كتالوج REST باستخدام docker-compose، ما يجعله خيارًا مثاليًا لاختبار تكاملات Iceberg.

الخطوة 1: أنشئ مجلدًا جديدًا لتشغيل المثال فيه، ثم أنشئ ملف docker-compose.yml مستخدمًا الإعدادات من Databricks docker-spark-iceberg.

الخطوة 2: بعد ذلك، أنشئ ملف docker-compose.override.yml وضع فيه إعدادات حاوية ClickHouse التالية:

version: '3.8'

services:
  clickhouse:
    image: clickhouse/clickhouse-server:25.5.6
    container_name: clickhouse
    user: '0:0'  # Ensures root permissions
    ports:
      - "8123:8123"
      - "9002:9000"
    volumes:
      - ./clickhouse:/var/lib/clickhouse
      - ./clickhouse/data_import:/var/lib/clickhouse/data_import  # Mount dataset folder
    networks:
      - iceberg_net
    environment:
      - CLICKHOUSE_DB=default
      - CLICKHOUSE_USER=default
      - CLICKHOUSE_DO_NOT_CHOWN=1
      - CLICKHOUSE_PASSWORD=

الخطوة 3: قم بتشغيل الأمر التالي لبدء الخدمات:

docker compose up

الخطوة 4: انتظر حتى تصبح جميع الخدمات جاهزة. يمكنك الاطلاع على السجلات:

docker-compose logs -f

الاتصال بـ كتالوج REST المحلي

اتصل بحاوية ClickHouse لديك:

docker exec -it clickhouse clickhouse-client

ثم أنشئ اتصال قاعدة البيانات مع كتالوج REST:

SET allow_database_iceberg = 1;

CREATE DATABASE demo
ENGINE = DataLakeCatalog('http://rest:8181/v1', 'admin', 'password')
SETTINGS 
    catalog_type = 'rest', 
    storage_endpoint = 'http://minio:9000/lakehouse', 
    warehouse = 'demo'

الاستعلام عن جداول كتالوج REST باستخدام ClickHouse

بعد إعداد الاتصال، يمكنك البدء في الاستعلام عبر كتالوج REST. على سبيل المثال:

USE demo;

SHOW TABLES;

إذا كان إعدادك يتضمن بيانات نموذجية (مثل بيانات سيارات الأجرة)، فمن المفترض أن ترى جداول مثل:

┌─name──────────┐
│ default.taxis │
└───────────────┘

Note

إذا لم تظهر أي جداول، فعادةً ما يعني ذلك أحد الأمور التالية:

لم تُنشئ بيئة Spark الجداول النموذجية بعد
لم تكتمل تهيئة خدمة كتالوج REST بعد
لم تكتمل بعد عملية تحميل البيانات النموذجية

يمكنك التحقق من سجلات Spark لمعرفة مدى تقدّم إنشاء الجداول:

docker-compose logs spark

لاستعلام أحد الجداول (إذا كان متاحًا):

SELECT count(*) FROM `default.taxis`;

┌─count()─┐
│ 2171187 │
└─────────┘

لفحص تعريف الجدول (DDL):

SHOW CREATE TABLE `default.taxis`;

┌─statement─────────────────────────────────────────────────────────────────────────────────────┐
│ CREATE TABLE demo.`default.taxis`                                                             │
│ (                                                                                             │
│     `VendorID` Nullable(Int64),                                                               │
│     `tpep_pickup_datetime` Nullable(DateTime64(6)),                                           │
│     `tpep_dropoff_datetime` Nullable(DateTime64(6)),                                          │
│     `passenger_count` Nullable(Float64),                                                      │
│     `trip_distance` Nullable(Float64),                                                        │
│     `RatecodeID` Nullable(Float64),                                                           │
│     `store_and_fwd_flag` Nullable(String),                                                    │
│     `PULocationID` Nullable(Int64),                                                           │
│     `DOLocationID` Nullable(Int64),                                                           │
│     `payment_type` Nullable(Int64),                                                           │
│     `fare_amount` Nullable(Float64),                                                          │
│     `extra` Nullable(Float64),                                                                │
│     `mta_tax` Nullable(Float64),                                                              │
│     `tip_amount` Nullable(Float64),                                                           │
│     `tolls_amount` Nullable(Float64),                                                         │
│     `improvement_surcharge` Nullable(Float64),                                                │
│     `total_amount` Nullable(Float64),                                                         │
│     `congestion_surcharge` Nullable(Float64),                                                 │
│     `airport_fee` Nullable(Float64)                                                           │
│ )                                                                                             │
│ ENGINE = Iceberg('http://minio:9000/lakehouse/warehouse/default/taxis/', 'admin', '[HIDDEN]') │
└───────────────────────────────────────────────────────────────────────────────────────────────┘

تحميل البيانات من بحيرة البيانات لديك إلى ClickHouse

إذا كنت بحاجة إلى تحميل بيانات من كتالوج REST إلى ClickHouse، فابدأ بإنشاء جدول ClickHouse محلي:

CREATE TABLE taxis
(
    `VendorID` Int64,
    `tpep_pickup_datetime` DateTime64(6),
    `tpep_dropoff_datetime` DateTime64(6),
    `passenger_count` Float64,
    `trip_distance` Float64,
    `RatecodeID` Float64,
    `store_and_fwd_flag` String,
    `PULocationID` Int64,
    `DOLocationID` Int64,
    `payment_type` Int64,
    `fare_amount` Float64,
    `extra` Float64,
    `mta_tax` Float64,
    `tip_amount` Float64,
    `tolls_amount` Float64,
    `improvement_surcharge` Float64,
    `total_amount` Float64,
    `congestion_surcharge` Float64,
    `airport_fee` Float64
)
ENGINE = MergeTree()
PARTITION BY toYYYYMM(tpep_pickup_datetime)
ORDER BY (VendorID, tpep_pickup_datetime, PULocationID, DOLocationID);

ثم حمّل البيانات من الجدول في REST catalog عبر INSERT INTO SELECT:

INSERT INTO taxis 
SELECT * FROM demo.`default.taxis`;