كتالوج REST

في هذا الدليل، سنأخذك عبر خطوات الاستعلام عن بياناتك باستخدام ClickHouse وكتالوج REST.

يعمل التكامل مع كتالوج REST مع جداول Iceberg فقط. يدعم هذا التكامل AWS S3 وغيره من موفري خدمات التخزين السحابي.

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

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

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

نظرًا إلى أن هذه الميزة لا تزال تجريبية، ستحتاج إلى تمكينها باستخدام: SET allow_database_iceberg = 1;

​

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

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

​

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

1. Docker وDocker Compose: تأكد من أن Docker مُثبّت ويعمل
2. إعداد تجريبي: يمكنك استخدام إعدادات 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 تحميل بيانات العينة إلى جداول Iceberg أولاً. تأكد من أن بيئة Spark قد أنشأت الجداول وعبّأتها بالبيانات قبل محاولة الاستعلام عنها عبر ClickHouse. ويعتمد توفر الجداول على إعداد docker-compose المستخدم والبرامج النصية لتحميل بيانات العينة.

​

الاتصال بـ كتالوج 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 │
└───────────────┘

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

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

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

docker-compose logs spark

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

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

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

علامات الاقتباس المعكوسة مطلوبة

علامات الاقتباس المعكوسة مطلوبة لأن ClickHouse لا يدعم أكثر من مساحة أسماء واحدة.

لفحص تعريف الجدول (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`;