محرك جدول Paimon

يوفّر هذا المحرك تكاملًا للقراءة فقط مع جداول Apache Paimon الموجودة في Amazon S3 وAzure وHDFS والجداول المخزّنة محليًا.

يوفّر هذا المحرك تكاملًا للقراءة فقط مع جداول Apache Paimon الموجودة في Amazon S3 وAzure وHDFS والجداول المخزّنة محليًا. ويدعم قراءات اللقطات وعمليات القراءة التزايدية واستبعاد الأقسام الأساسي الذي يوفّره المحرك.

​

إنشاء جدول

لاحظ أن جدول Paimon يجب أن يكون موجودًا بالفعل في التخزين، إذ لا يدعم هذا الأمر معلمات DDL لإنشاء جدول جديد. يتطلب إنشاء جداول Paimon* تفعيل allow_experimental_paimon_storage_engine (وهو معطّل افتراضيًا)، لذا قم بتمكينه قبل تشغيل CREATE TABLE.

SET allow_experimental_paimon_storage_engine = 1;

CREATE TABLE paimon_table_s3
    ENGINE = PaimonS3(url,  [, access_key_id, secret_access_key] [,format] [,compression])

CREATE TABLE paimon_table_azure
    ENGINE = PaimonAzure(connection_string|storage_account_url, container_name, blobpath, [,account_name], [,account_key] [,format] [,compression_method])

CREATE TABLE paimon_table_hdfs
    ENGINE = PaimonHDFS(path_to_table, [,format] [,compression_method])

CREATE TABLE paimon_table_local
    ENGINE = PaimonLocal(path_to_table, [,format] [,compression_method])

​

وسائط المحرك

يتوافق وصف هذه الوسائط مع وصف الوسائط في المحركات S3 وAzureBlobStorage وHDFS وFile، كلٌّ بحسبه. يشير format إلى تنسيق ملفات البيانات في جدول Paimon.

يمكن تحديد معلمات المحرك باستخدام المجموعات المسماة

​

مثال

CREATE TABLE paimon_table ENGINE=PaimonS3('http://test.s3.amazonaws.com/clickhouse-bucket/test_table', 'test', 'test')

استخدام المجموعات المُسمّاة:

<clickhouse>
    <named_collections>
        <paimon_conf>
            <url>http://test.s3.amazonaws.com/clickhouse-bucket/</url>
            <access_key_id>test</access_key_id>
            <secret_access_key>test</secret_access_key>
        </paimon_conf>
    </named_collections>
</clickhouse>

CREATE TABLE paimon_table ENGINE=PaimonS3(paimon_conf, filename = 'test_table')

​

الإمكانات

• تتم عمليات قراءة اللقطات من أحدث لقطة للجدول.
• تتم عمليات القراءة التزايدية استنادًا إلى معرّف اللقطة المُعتمدة عند تفعيلها.
• استبعاد الأقسام عند تمكين use_paimon_partition_pruning.
• تحديث اختياري للبيانات الوصفية في الخلفية عند ضبطه.
• معرّف UUID ثابت للجدول عند استخدام قواعد بيانات Atomic/Replicated، مما يتيح وحدات الماكرو {uuid} في مسارات Keeper.

​

الإعدادات

يستخدم هذا المحرك الإعدادات نفسها المستخدمة في محركات تخزين الكائنات المقابلة، ويضيف إعدادات خاصة بـ Paimon:

• allow_experimental_paimon_storage_engine — يتيح إنشاء محركات الجداول Paimon وPaimonS3 وPaimonAzure وPaimonHDFS وPaimonLocal. القيمة الافتراضية: 0 (معطّل).
• paimon_incremental_read — يفعّل وضع القراءة التزايدية.
• paimon_metadata_refresh_interval_sec — الفاصل الزمني لتحديث البيانات الوصفية في الخلفية، بالثواني. عند ضبطه على قيمة أكبر من 0، تسحب مهمة تعمل في الخلفية أحدث لقطة ومخطط دوريًا من تخزين الكائنات. القيمة الافتراضية: 30.
• paimon_keeper_path — مسار Keeper لحالة القراءة التزايدية. يجب ضبطه وأن يكون فريدًا لكل جدول؛ ويدعم وحدات الماكرو مثل {database} و{table} و{uuid}.
• paimon_replica_name — اسم النسخة المتماثلة لحالة القراءة التزايدية. يجب ضبطه وأن يكون فريدًا لكل نسخة متماثلة؛ ويدعم وحدات الماكرو مثل {replica}.

​

أمثلة على القراءة التزايدية

القراءة التزايدية باستخدام حالة Keeper:

CREATE TABLE paimon_inc
ENGINE = PaimonS3(paimon_conf, filename = 'paimon_all_types')
SETTINGS
    paimon_incremental_read = 1,
    paimon_keeper_path = '/clickhouse/{database}/{uuid}',
    paimon_replica_name = '{replica}';

​

إعدادات على مستوى الاستعلام للقراءة التزايدية

الإعدادات التالية هي على مستوى الاستعلام (تُمرَّر عبر SELECT ... SETTINGS، وليس ضمن CREATE TABLE). وهي تتحكم في سلوك كل استعلام على حدة لعمليات القراءة التزايدية:

• paimon_target_snapshot_id — يقرأ فقط التغييرات الخاصة باللقطة المحددة. لا تتقدّم العلامة المائية المُعتمدة في Keeper، لذا يمكن إعادة قراءة اللقطة نفسها أي عدد من المرات. القيمة الافتراضية: -1 (معطّل).
• max_consume_snapshots — الحد الأقصى لعدد اللقطات التي يمكن استهلاكها في قراءة تزايدية واحدة. عندما يكون المصدر قد راكم عددًا كبيرًا من اللقطات غير المقروءة، يحدّ هذا الإعداد من عدد اللقطات التي تُستهلك في كل استعلام للتحكم في حجم الدفعة. 0 تعني عدم وجود حد. القيمة الافتراضية: 0.

قراءة لقطة مستهدفة — تُرجع دائمًا التغييرات الخاصة باللقطة 1، بغض النظر عن العلامة المائية الحالية:

SELECT count()
FROM paimon_inc
SETTINGS paimon_target_snapshot_id = 1;

تحديد عدد اللقطات في كل دفعة — إذا كانت هناك ثلاث لقطات جديدة قيد الانتظار، فلا تستهلك أكثر من اثنتين لكل استعلام:

SELECT count()
FROM paimon_inc
SETTINGS max_consume_snapshots = 2;

​

من Paimon إلى MergeTree عبر عرض مادي قابل للتحديث

يمكنك إنشاء مسار متكامل من المصدر إلى الوجهة يزامن البيانات باستمرار من جدول Paimon إلى جدول MergeTree باستخدام عرض مادي قابل للتحديث في وضع APPEND. في كل دورة تحديث، لا تُقرأ من Paimon إلا البيانات التزايدية الجديدة، ثم تُلحَق بجدول الوجهة.

الخطوة 1 — أنشئ جدول مصدر Paimon مع تمكين القراءة التزايدية وتحديث البيانات الوصفية.

يستخدم المثال أدناه PaimonLocal. استبدل المحرك بـ PaimonS3 أو PaimonAzure أو PaimonHDFS أو المحرك Paimon الذي يكتشف الإعدادات تلقائيًا، بحسب ما يناسب الواجهة الخلفية للتخزين لديك:

SET allow_experimental_paimon_storage_engine = 1;

-- Local storage
CREATE TABLE paimon_mv_source
ENGINE = PaimonLocal('/path/to/paimon/table')
SETTINGS
    paimon_incremental_read = 1,
    paimon_keeper_path = '/clickhouse/tables/{uuid}',
    paimon_replica_name = '{replica}',
    paimon_metadata_refresh_interval_sec = 1;

-- S3 storage (the `Paimon` engine defaults to the S3 implementation when no `disk` is specified)
CREATE TABLE paimon_mv_source
ENGINE = Paimon('http://minio:9000/bucket/path/to/table', 'access_key', 'secret_key')
SETTINGS
    paimon_incremental_read = 1,
    paimon_keeper_path = '/clickhouse/tables/{uuid}',
    paimon_replica_name = '{replica}',
    paimon_metadata_refresh_interval_sec = 1;

يضبط paimon_metadata_refresh_interval_sec الفاصل الزمني لتحديث البيانات الوصفية في الخلفية، بالثواني. وعندما تكون قيمته أكبر من 0، تسحب مهمة تعمل في الخلفية أحدث لقطة ومخطط من تخزين الكائنات بشكل دوري، بحيث تتمكن دورة تحديث MV من رؤية البيانات المُعتمدة حديثًا دون انتظار أن يؤدّي استعلام إلى تشغيل تحديث البيانات الوصفية. القيمة الافتراضية هي 30. استخدمه بحذر عند التعامل مع عدد كبير من الجداول لتجنّب الإفراط في استخدام تخزين الكائنات وعمليات الإدخال/الإخراج الخاصة بـ Keeper.

الخطوة 2 — أنشئ جدول الوجهة من نوع MergeTree (مع استنساخ المخطط من جدول Paimon):

CREATE TABLE paimon_mv_dest AS paimon_mv_source
ENGINE = MergeTree()
ORDER BY tuple();

الخطوة 3 — أنشئ العرض المادي القابل للتحديث:

CREATE MATERIALIZED VIEW paimon_mv
REFRESH EVERY 10 SECOND
APPEND
TO paimon_mv_dest
AS SELECT * FROM paimon_mv_source;

كل 10 ثوانٍ، ينفّذ الـ MV الاستعلام SELECT * FROM paimon_mv_source، الذي يعيد فقط الصفوف المُضافة منذ آخر لقطة تم اعتمادها، ويضيفها إلى paimon_mv_dest.

التنظيف:

SYSTEM STOP VIEW paimon_mv;
DROP VIEW IF EXISTS paimon_mv SYNC;
DROP TABLE IF EXISTS paimon_mv_dest SYNC;
DROP TABLE IF EXISTS paimon_mv_source SYNC;

أوقِف الـ MV قبل حذفها لمنع التحديث في الخلفية من تعطيل عمليات DDL.

​

القيود

• تتطلب القراءة التزايدية تهيئة Keeper ‏(ZooKeeper).
• تتطلب القراءة التزايدية ضبط paimon_keeper_path بحيث يكون فريدًا لكل جدول.
• يجب أن يكون paimon_replica_name فريدًا لكل نسخة متماثلة ضمن مسار Keeper نفسه.
• تستخدم القراءة التزايدية آلية تسليم من نوع at-most-once: إذ تُقدَّم اللقطة المعتمدة عند جمع ملفات البيانات، قبل استهلاك البيانات فعليًا. وإذا فشل الاستعلام بعد جمع الملفات، فلن تُعاد قراءة اللقطات التي تم تجاوزها عند إعادة المحاولة.
• محرك الجدول للقراءة فقط؛ ولا يدعم تعديل البيانات.
• لا تتعامل القراءة التزايدية مع حذف البيانات التاريخية من مصدر Paimon. إذا حُذفت بيانات Paimon من المصدر الأصلي أو جرى تحديثها، فلن تُزال تلقائيًا الصفوف المقابلة التي كُتبت بالفعل إلى جدول وجهة من نوع ClickHouse MergeTree. يجب عليك إصدار ALTER TABLE ... DELETE يدويًا على جدول MergeTree لتنظيف البيانات القديمة.

​

الأسماء البديلة

يكتشف محرك الجدول Paimon تلقائيًا الواجهة الخلفية للتخزين من إعداد disk، ثم يوجّه إلى PaimonS3 أو PaimonAzure أو PaimonLocal وفقًا لذلك. وعند عدم تحديد disk، يُستخدَم PaimonS3 افتراضيًا.

​

الأعمدة الافتراضية

• _path — مسار الملف. النوع: LowCardinality(String).
• _file — اسم الملف. النوع: LowCardinality(String).
• _size — حجم الملف بالبايت. النوع: Nullable(UInt64). إذا كان حجم الملف غير معروف، تكون القيمة NULL.
• _time — وقت آخر تعديل للملف. النوع: Nullable(DateTime). إذا كان الوقت غير معروف، تكون القيمة NULL.
• _etag — قيمة etag للملف. النوع: LowCardinality(String). إذا كانت قيمة etag غير معروفة، تكون القيمة NULL.

​

أنواع البيانات المدعومة

نوع البيانات في Paimon	نوع البيانات في ClickHouse
BOOLEAN	Int8
TINYINT	Int8
SMALLINT	Int16
INTEGER	Int32
BIGINT	Int64
FLOAT	Float32
DOUBLE	Float64
STRING,VARCHAR,BYTES,VARBINARY	String
DATE	Date
TIME(p),TIME	Time(‘UTC’)
TIMESTAMP(p) WITH LOCAL TIME ZONE	DateTime64
TIMESTAMP(p)	DateTime64(‘UTC’)
CHAR	FixedString(1)
BINARY(n)	FixedString(n)
DECIMAL(P,S)	Decimal(P,S)
ARRAY	Array
MAP	Map

​

التقسيم المدعوم

أنواع البيانات المدعومة في مفاتيح التقسيم في Paimon:

• CHAR
• VARCHAR
• BOOLEAN
• DECIMAL
• TINYINT
• SMALLINT
• INTEGER
• DATE
• TIME
• TIMESTAMP
• TIMESTAMP WITH LOCAL TIME ZONE
• BIGINT
• FLOAT
• DOUBLE