مشاركة عبر

استخدام UniForm لقراءة جداول Delta مع عملاء Iceberg

  • مقالة

يسمح لك Delta Lake Universal Format (UniForm) بقراءة جداول Delta مع عملاء قارئ Iceberg. تتطلب هذه الميزة Databricks Runtime 14.3 LTS أو أعلى.

هام

للحصول على وثائق لميزة جدول UniForm IcebergCompatV1 القديم، راجع Legacy UniForm IcebergCompatV1.

يمكنك تكوين اتصال خارجي ليكون كتالوج Unity بمثابة كتالوج Iceberg. راجع القراءة باستخدام نقطة نهاية كتالوج Unity Iceberg.

يستخدم UniForm Iceberg Zstandard بدلا من Snappy كمبرمج ضغط لملفات بيانات Parquet الأساسية.

إشعار

يتم تشغيل إنشاء بيانات تعريف UniForm بشكل غير متزامن على الحساب المستخدم لكتابة البيانات إلى جداول Delta، مما قد يزيد من استخدام موارد برنامج التشغيل.

كيف يعمل UniForm؟

يستفيد UniForm من حقيقة أن Delta Lake و Iceberg يتكونان من ملفات بيانات Parquet وطبقة بيانات التعريف. يقوم UniForm تلقائيا بإنشاء بيانات تعريف Iceberg بشكل غير متزامن، دون إعادة كتابة البيانات، بحيث يمكن لعملاء Iceberg قراءة جداول Delta. تقدم نسخة واحدة من ملفات البيانات تنسيقات متعددة.

المتطلبات

لتمكين UniForm Iceberg، يجب استيفاء المتطلبات التالية:

إشعار

لا يمكنك تمكين متجهات الحذف على جدول مع تمكين UniForm Iceberg.

يستخدم REORG لتعطيل متجهات الحذف ومسحها أثناء تمكين UniForm Iceberg على جدول موجود مع تمكين متجهات الحذف. راجع تمكين أو ترقية باستخدام REORG.

تمكين UniForm Iceberg

هام

يؤدي تمكين Delta UniForm إلى تعيين ميزة IcebergCompatV2جدول Delta ، وهي ميزة بروتوكول الكتابة. يمكن فقط للعملاء الذين يدعمون ميزة الجدول هذه الكتابة إلى الجداول الممكنة بواسطة UniForm. يجب استخدام Databricks Runtime 14.3 LTS أو أعلى للكتابة إلى جداول Delta مع تمكين هذه الميزة.

يمكنك إيقاف تشغيل UniForm عن طريق إلغاء تحديد delta.universalFormat.enabledFormats خاصية الجدول. لا يمكن التراجع عن الترقيات إلى إصدارات بروتوكول قارئ Delta Lake والكاتب.

يجب تعيين خصائص الجدول التالية لتمكين UniForm Iceberg:

'delta.enableIcebergCompatV2' = 'true'
'delta.universalFormat.enabledFormats' = 'iceberg'

عند تمكين UniForm لأول مرة، يبدأ إنشاء بيانات التعريف غير المتزامنة. يجب أن تكتمل هذه المهمة قبل أن يتمكن العملاء الخارجيون من الاستعلام عن الجدول باستخدام Iceberg. راجع التحقق من حالة إنشاء بيانات التعريف في Iceberg.

للحصول على قائمة بالقيود، راجع القيود.

التمكين أثناء إنشاء الجدول

يجب تمكين تعيين العمود لاستخدام UniForm Iceberg. يحدث هذا تلقائيا إذا قمت بتمكين UniForm Iceberg أثناء إنشاء الجدول، كما في المثال التالي:

CREATE TABLE T(c1 INT) TBLPROPERTIES(
  'delta.enableIcebergCompatV2' = 'true',
  'delta.universalFormat.enabledFormats' = 'iceberg');

تمكين عن طريق تغيير جدول موجود

في Databricks Runtime 15.4 LTS وما فوق، يمكنك تمكين أو ترقية UniForm Iceberg على جدول موجود باستخدام بناء الجملة التالي:

ALTER TABLE table_name SET TBLPROPERTIES(
  'delta.enableIcebergCompatV2' = 'true',
  'delta.universalFormat.enabledFormats' = 'iceberg');

تمكين أو ترقية باستخدام REORG

يمكنك استخدام REORG لتمكين UniForm Iceberg وإعادة كتابة ملفات البيانات الأساسية، كما في المثال التالي:

REORG TABLE table_name APPLY (UPGRADE UNIFORM(ICEBERG_COMPAT_VERSION=2));

استخدم REORG إذا كان أي مما يلي صحيحا:

  • تم تمكين متجهات الحذف في الجدول.
  • لقد قمت مسبقا بتمكين IcebergCompatV1 إصدار UniForm Iceberg.
  • تحتاج إلى القراءة من محركات Iceberg التي لا تدعم ملفات Parquet على غرار Hive، مثل Athena أو Redshift.

متى ينشئ UniForm بيانات تعريف جبل الجليد؟

يقوم Azure Databricks بتشغيل إنشاء بيانات التعريف بشكل غير متزامن بعد اكتمال معاملة كتابة Delta Lake. تستخدم عملية إنشاء بيانات التعريف هذه نفس الحساب الذي أكمل معاملة Delta.

إشعار

يمكنك أيضا تشغيل إنشاء بيانات تعريف Iceberg يدويا. راجع تشغيل تحويل بيانات تعريف Iceberg يدويا.

لتجنب زمن انتقال الكتابة المقترن بإنشاء بيانات التعريف، قد تقوم جداول Delta ذات التثبيتات المتكررة بتجميع عمليات تثبيت دلتا المتعددة في تثبيت واحد لبيانات تعريف Iceberg.

تضمن Delta Lake أن عملية إنشاء بيانات تعريف واحدة فقط قيد التقدم في أي وقت على مورد حساب معين. الالتزامات التي من شأنها أن تؤدي إلى عملية إنشاء بيانات تعريف متزامنة ثانية بنجاح إلى Delta، ولكن لا تؤدي إلى إنشاء بيانات تعريف Iceberg غير متزامنة. يمنع هذا زمن الانتقال المتتالي لإنشاء بيانات التعريف لأحمال العمل ذات التثبيتات المتكررة (من ثوان إلى دقائق بين عمليات التثبيت).

راجع إصدارات جدول Delta و Iceberg.

إصدارات جدول Delta و Iceberg

تسمح Delta Lake و Iceberg باستعلامات السفر عبر الوقت باستخدام إصدارات الجدول أو الطوابع الزمنية المخزنة في بيانات تعريف الجدول.

بشكل عام، لا تتوافق إصدارات جدول Delta مع إصدارات Iceberg إما بواسطة الطابع الزمني للتثبيت أو معرف الإصدار. للتحقق من إصدار جدول Delta الذي يتوافق مع إصدار معين من جدول Iceberg، يمكنك استخدام خصائص الجدول المقابلة. راجع التحقق من حالة إنشاء بيانات التعريف في Iceberg.

التحقق من حالة إنشاء بيانات التعريف في Iceberg

يضيف UniForm الحقول التالية إلى كتالوج Unity وبيانات تعريف جدول Iceberg لتتبع حالة إنشاء بيانات التعريف:

حقل بيانات التعريف ‏‏الوصف
converted_delta_version أحدث إصدار من جدول Delta الذي تم إنشاء بيانات تعريف Iceberg له بنجاح.
converted_delta_timestamp الطابع الزمني لأحدث تثبيت Delta الذي تم إنشاء بيانات تعريف Iceberg له بنجاح.

في Azure Databricks، يمكنك مراجعة حقول بيانات التعريف هذه عن طريق القيام بأحد الإجراءات التالية:

راجع وثائق عميل قارئ Iceberg لمعرفة كيفية مراجعة خصائص الجدول خارج Azure Databricks. بالنسبة إلى OSS Apache Spark، يمكنك مشاهدة هذه الخصائص باستخدام بناء الجملة التالي:

SHOW TBLPROPERTIES <table-name>;

تشغيل تحويل بيانات تعريف Iceberg يدويا

يمكنك تشغيل إنشاء بيانات تعريف Iceberg يدويا للحصول على أحدث إصدار من جدول Delta. تعمل هذه العملية بشكل متزامن، ما يعني أنه عند اكتمالها، تعكس محتويات الجدول المتوفرة في Iceberg أحدث إصدار من جدول Delta المتوفر عند بدء عملية التحويل.

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

  • ينتهي نظام المجموعة قبل نجاح إنشاء بيانات التعريف التلقائية.
  • يؤدي الخطأ أو فشل الوظيفة إلى مقاطعة إنشاء بيانات التعريف.
  • يكتب عميل لا يدعم UniForm Iceberg metadata gneration إلى جدول Delta.

استخدم بناء الجملة التالي لتشغيل إنشاء بيانات تعريف Iceberg يدويا:

MSCK REPAIR TABLE <table-name> SYNC METADATA

راجع جدول الإصلاح.

القراءة باستخدام مسار JSON لبيانات التعريف

يتطلب بعض عملاء Iceberg توفير مسار لملفات بيانات التعريف التي تم إصدارها لتسجيل جداول Iceberg الخارجية. في كل مرة يحول فيها UniForm إصدارا جديدا من جدول Delta إلى Iceberg، فإنه ينشئ ملف JSON لبيانات التعريف الجديدة.

يتضمن العملاء الذين يستخدمون مسارات JSON لبيانات التعريف لتكوين Iceberg BigQuery. راجع وثائق عميل قارئ Iceberg للحصول على تفاصيل التكوين.

تخزن Delta Lake بيانات تعريف Iceberg ضمن دليل الجدول، باستخدام النمط التالي:

<table-path>/metadata/<version-number>-<uuid>.metadata.json

في Azure Databricks، يمكنك مراجعة موقع بيانات التعريف هذا عن طريق القيام بأحد الإجراءات التالية:

  • مراجعة القسم الذي Delta Uniform Iceberg تم إرجاعه بواسطة DESCRIBE EXTENDED table_name.
  • مراجعة بيانات تعريف الجدول باستخدام مستكشف الكتالوج.
  • استخدام الأمر التالي مع واجهة برمجة تطبيقات REST:
GET api/2.1/unity-catalog/tables/<catalog-name>.<schame-name>.<table-name>

يتضمن الرد المعلومات التالية:

{
    ...
          "delta_uniform_iceberg": {
              "metadata_location":  "<cloud-storage-uri>/metadata/v<version-number>-<uuid>.metadata.json"
    }
}

هام

قد يتطلب عملاء قارئ Iceberg المستند إلى المسار تحديث مسارات JSON لبيانات التعريف وتحديثها يدويا لقراءة إصدارات الجدول الحالية. قد يواجه المستخدمون أخطاء عند الاستعلام عن جداول Iceberg باستخدام إصدارات قديمة حيث تتم إزالة ملفات بيانات Parquet من جدول Delta باستخدام VACUUM.

القراءة باستخدام نقطة نهاية كتالوج Unity Iceberg

يمكن لبعض عملاء Iceberg الاتصال بكتالوج Iceberg REST. يوفر كتالوج Unity تنفيذا للقراءة فقط لواجهة برمجة تطبيقات كتالوج Iceberg REST لجداول Delta مع تمكين UniForm باستخدام نقطة /api/2.1/unity-catalog/icebergالنهاية . راجع مواصفات Iceberg REST API للحصول على تفاصيل حول استخدام واجهة برمجة تطبيقات REST هذه.

العملاء المعروفين بدعم واجهة برمجة تطبيقات كتالوج Iceberg تشمل Apache Spark وFlink و Trino. راجع وثائق عميل قارئ Iceberg للحصول على تفاصيل التكوين.

المصادقة والتخويل

هناك متطلبان للوصول إلى البيانات المسجلة في كتالوج Unity باستخدام api/2.1/unity-catalog/iceberg نقطة النهاية من الخدمات الخارجية:

مثال على تكوين Apache Spark

فيما يلي مثال على الإعدادات المستخدمة لتكوين OSS Apache Spark لقراءة UniForm ك Iceberg:

"spark.sql.extensions": "org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions",
"spark.sql.catalog.unity": "org.apache.iceberg.spark.SparkCatalog",
"spark.sql.catalog.unity.type": "rest",
"spark.sql.catalog.unity.uri": "<api-root>/api/2.1/unity-catalog/iceberg",
"spark.sql.catalog.unity.token": "<your_personal_access_token>",
"spark.sql.catalog.unity.warehouse": "<uc_catalog_name>"

استبدل عنوان URL الكامل لمساحة العمل التي قمت فيها بإنشاء رمز الوصول الشخصي المميز ل <api-root>.

عند الاستعلام عن الجداول في كتالوج Unity باستخدام تكوينات Spark، ضع ما يلي في الاعتبار:

  • تستخدم معرفات الكائنات النمط unity.<schema-name>.<table-name>.

    يستخدم هذا النمط نفس مساحة الاسم ثلاثية المستويات المستخدمة في كتالوج Unity، ولكن مع استبدال اسم الكتالوج ب unity.

  • "spark.sql.extensions": "org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions" تحتاج فقط إذا كنت تقوم بتشغيل الإجراءات المخزنة الخاصة ب Iceberg.

  • إذا كنت تستخدم موفر سحابة للتخزين، يجب إضافة حزمة Iceberg الخاصة بالسحابة كحزم Spark:

    • AWS: org.apache.iceberg:iceberg-aws-bundle:<iceberg-version>
    • Azure: org.apache.iceberg:iceberg-azure-bundle:<iceberg-version>
    • GCP: org.apache.iceberg:iceberg-gcp-bundle:<iceberg-version>

    للحصول على التفاصيل، راجع وثائق تكامل Iceberg AWS ل Spark.

مثال متعرج لواجهة برمجة تطبيقات REST

يمكنك أيضا استخدام استدعاء REST API مثل استدعاء في مثال curl هذا لتحميل جدول:

curl -X GET -H "Authentication: Bearer $OAUTH_TOKEN" -H "Accept: application/json" \
https://<workspace-instance>/api/2.1/unity-catalog/iceberg/v1/catalogs/<uc_catalog_name>/namespaces/<uc_schema_name>/tables/<uc_table_name>

يجب أن تتلقى بعد ذلك استجابة مثل هذا:

{
  "metadata-location": "abfss://my-container@my-storage-account.dfs.core.windows.net/path/to/iceberg/table/metadata/file",
  "metadata": <iceberg-table-metadata-json>,
  "config": {
    "expires-at-ms": "<epoch-ts-in-millis>",
    "adls.sas-token.<storage-account-name>.dfs.core.windows.net": "<temporary-sas-token>"
  }
}

إشعار

expires-at-ms يشير الحقل في الاستجابة إلى وقت انتهاء صلاحية بيانات الاعتماد ولديه وقت انتهاء صلاحية افتراضي مدته ساعة واحدة. للحصول على أداء أفضل، اطلب من العميل تخزين بيانات الاعتماد مؤقتا حتى وقت انتهاء الصلاحية قبل طلب بيانات اعتماد جديدة.

القيود

توجد القيود التالية لكافة جداول UniForm:

  • لا يعمل UniForm على الجداول مع تمكين متجهات الحذف. راجع ما هي متجهات الحذف؟.
  • لا تدعم جداول Delta مع تمكين UniForm أنواعا VOID .
  • يمكن لعملاء Iceberg القراءة فقط من UniForm. عمليات الكتابة غير معتمدة.
  • قد يكون لدى عملاء قارئ Iceberg قيود فردية، بغض النظر عن UniForm. راجع الوثائق الخاصة بالعميل الذي اخترته.
  • يمكن لمستلمي Delta Sharing قراءة الجدول فقط على أنه Delta، حتى عند تمكين UniForm.
  • بعض ميزات جدول Delta Lake المستخدمة من قبل UniForm Iceberg غير مدعومة من قبل بعض عملاء قارئ Delta Sharing. راجع ما المقصود بمشاركة دلتا؟.

يعمل Change Data Feed لعملاء Delta عند تمكين UniForm، ولكن ليس لديه دعم في Iceberg.