الاستعلام عن جداول Apache Iceberg من Oracle Autonomous AI Database

Apache Iceberg صيغة جداول مفتوحة لبحيرات البيانات (lakehouses): ملفات بيانات Parquet (أو ORC وAvro) في تخزين الكائنات (object storage)، مع ملفات بيانات وصفية تتتبّع مخطط الجدول وأقسامه وإصداراته. ويستطيع Oracle Autonomous AI Database (المعروف سابقًا بـ Autonomous Database) قراءة جدول Iceberg في مكانه عبر جدول خارجي (external table). فتستعلم عن بيانات البحيرة وتربطها بجداولك بـ SQL عادي، دون نسخها إلى قاعدة البيانات.

متى يناسبك جدول Iceberg خارجي

• بياناتك موجودة أصلًا في بحيرة بيانات (lakehouse) يكتب فيها محرّك آخر (Spark أو Databricks أو Snowflake أو مهام AWS Glue أو BigQuery)، وتريد الاستعلام عنها من Autonomous AI Database.
• تريد ربط بيانات البحيرة بجداول القاعدة، للتقارير أو صفحات APEX أو التحليلات، دون بناء خط أنابيب (pipeline) لنسخها أولًا.
• تحتاج إلى القراءة فقط. فجدول Iceberg الخارجي يُستعلم عنه ولا يُعدَّل بـ DML، ويبقى المحرّك الذي يملك الجدول هو من يكتب فيه.
• أثقل استعلاماتك تصفّي على الأعمدة التي قُسّم الجدول على أساسها (تاريخ أو منطقة أو معرّف عميل أو مستأجر). وهذه هي الاستعلامات التي يفيدها تقليم الأقسام.

حمّل البيانات إلى جدول في القاعدة بدلًا من ذلك إذا كان يجب تحديثها من القاعدة، أو إذا كانت كل استعلاماتك تقرأ الجدول كله على أي حال.

كيف يعمل

كل تغيير على جدول Iceberg يُنشئ لقطة (snapshot): إصدار كامل من الجدول للقراءة فقط. ويسرد ملف البيانات الوصفية (مستند JSON) اللقطات ويحدّد الحالية منها. وتشير كل لقطة إلى قائمة manifest تسمّي ملفات manifest الخاصة بها. وتسرد ملفات manifest ملفات البيانات مع قيم أقسامها وإحصاءات أعمدتها. ويسجّل الكتالوج (AWS Glue وPolaris وUnity وغيرها) أي ملف بيانات وصفية هو الحالي. وعند إنشاء الجدول الخارجي يأخذ Autonomous AI Database أسماء الأعمدة وأنواعها من بيانات Iceberg الوصفية، فلا تمرّر قائمة أعمدة. وعند الاستعلام تقرأ القاعدة البيانات الوصفية أولًا، ثم ملفات البيانات التي تحتاج إليها فقط.

1. اختر بين الكتالوج والعمل بلا كتالوج

الكتالوجات والتخزين المدعومة

• AWS Glue مع Amazon S3. استخدم بيانات الاعتماد نفسها لـ S3 وGlue، وأبقِ الحاوية (bucket) والكتالوج في منطقة AWS نفسها.
• Snowflake Polaris مع Amazon S3 أو Azure ADLS Gen2، بمصادقة OAuth2 (client credentials) أو رمز آخر يدعمه Polaris. وتذكر أوراكل أن Snowflake Horizon Catalog يعمل بالخطوات نفسها.
• Databricks Unity Catalog مع Amazon S3 أو Azure ADLS Gen2، لجداول UniForm فقط: جداول Delta التي تكتب بيانات Iceberg الوصفية أيضًا. أما جداول Iceberg الخاصة بـ Unity (غير UniForm) فلا يمكن قراءتها بهذه الطريقة.
• Google Lakehouse runtime catalog (المعروف سابقًا بـ BigLake) مع Google Cloud Storage، لجداول Iceberg التي أنشأها BigQuery فقط، وللقراءة فقط.
• كتالوج Hadoop على OCI Object Storage (مثل الجداول التي تكتبها OCI Data Flow).
• ملف metadata.json مباشر على Amazon S3 أو Azure ADLS Gen2 أو OCI Object Storage.

2. جهّز المخطط والوصول الشبكي

• قاعدة Autonomous AI Database ومخطط (schema) يملك الجداول الخارجية.
• منح الدور DWROLE لذلك المخطط، فهو الدور القياسي للعمل مع DBMS_CLOUD.
• قوائم التحكم بالوصول الشبكي (ACL) لذلك المخطط: اتصال HTTPS صادر (المنفذ 443) إلى كل مضيف يحتاج إليه الجدول، مثل objectstorage.<region>.oraclecloud.com و<bucket>.s3.<region>.amazonaws.com وglue.<region>.amazonaws.com و<workspace>.azuredatabricks.net و<account>.snowflakecomputing.com و<storage-account>.blob.core.windows.net، أو biglake.googleapis.com وoauth2.googleapis.com و<bucket>.storage.googleapis.com. وأضف مضيف وكيل HTTPS (proxy) إن كنت تستخدمه. ولا يحتاج المستخدم الذي يكتفي بالاستعلام عن جدول قائم إلى أي ACL شبكي.
• بيانات اعتماد للتخزين لقراءة ملفات البيانات الوصفية وملفات البيانات، ويحتاج إليها كل إعداد.
• بيانات اعتماد للكتالوج أيضًا في كتالوجات REST (Polaris وUnity وGoogle). فيستخدم الجدول الخارجي عندها مجموعتين: credential_name للملفات وrest_auth_cred للكتالوج.
• موقع الجدول: نوع الكتالوج والمنطقة أو نقطة الاتصال (endpoint) ومسار الجدول، أو رابط ملف metadata.json.

-- From Oracle's documented syntax, not run. Run as ADMIN.
GRANT DWROLE TO <schema>;

-- Outbound HTTPS for the schema that CREATES the external table.
-- One call per host your configuration needs (see the host list above).
BEGIN
  DBMS_NETWORK_ACL_ADMIN.APPEND_HOST_ACE(
    host       => 'objectstorage.<region>.oraclecloud.com',
    lower_port => 443,
    upper_port => 443,
    ace        => xs$ace_type(
                    privilege_list => xs$name_list('http'),
                    principal_name => '<schema>',
                    principal_type => xs_acl.ptype_db));
END;
/

3. أنشئ بيانات اعتماد التخزين

أنشئ بيانات الاعتماد بحساب المخطط الذي سيملك الجدول الخارجي. لـ OCI Object Storage استخدم بيانات اعتماد OCI الأصلية: مفتاح توقيع API لا يحمل مفتاحه الخاص عبارة مرور (passphrase). ولـ S3 وGlue استخدم مفتاح الوصول والمفتاح السري (secret). ولـ ADLS Gen2 استخدم مفتاح حساب التخزين أو رمز SAS. ولـ Google Cloud Storage استخدم مفتاح وصول HMAC والمفتاح السري.

-- From Oracle's documented syntax, not run. Run as <schema>.

-- OCI Object Storage: OCI native (API signing key) credential
BEGIN
  DBMS_CLOUD.CREATE_CREDENTIAL(
    credential_name => 'OCI_CRED',
    user_ocid       => '<user_ocid>',
    tenancy_ocid    => '<tenancy_ocid>',
    private_key     => '<private_key_without_passphrase>',
    fingerprint     => '<key_fingerprint>');
END;
/

-- Amazon S3 (also used for AWS Glue): access key and secret
BEGIN
  DBMS_CLOUD.CREATE_CREDENTIAL(
    credential_name => 'S3_CRED',
    username        => '<aws_access_key_id>',
    password        => '<aws_secret_access_key>');
END;
/

4. أنشئ جدول Iceberg الخارجي

كل الصيغ تستدعي DBMS_CLOUD.CREATE_EXTERNAL_TABLE مع "protocol_type": "iceberg" داخل JSON الخاص بالمعامل format. لا تمرّر column_list ولا field_list: يجب أن يكونا NULL، لأن الأعمدة تأتي من بيانات Iceberg الوصفية. اختر الصيغة التي تطابق كتالوجك.

الخيار A: كتالوج AWS Glue

هذا شكل مثال أوراكل نفسه، الذي ينشئ ORDERS فوق جدول Glue باسم db.orders. ومع وجود كتالوج لا تمرّر file_uri_list.

-- From Oracle's documented syntax, not run.
BEGIN
  DBMS_CLOUD.CREATE_EXTERNAL_TABLE(
    table_name      => 'ORDERS',
    credential_name => 'S3_CRED',
    format          => '{
      "access_protocol": {
        "protocol_type": "iceberg",
        "protocol_config": {
          "iceberg_catalog_type": "aws_glue",
          "iceberg_glue_region": "<region>",
          "iceberg_table_path": ["<glue_database>.<glue_table>"]
        }
      }
    }'
  );
END;
/

الخيار B: ملف metadata.json واحد (بلا كتالوج)

وجّه file_uri_list إلى ملف metadata.json الخاص بالجدول، ولا تمرّر protocol_config. فيبقى الجدول مثبّتًا على تلك اللقطة.

-- From Oracle's documented syntax, not run.
BEGIN
  DBMS_CLOUD.CREATE_EXTERNAL_TABLE(
    table_name      => 'ORDERS_SNAPSHOT',
    credential_name => 'OCI_CRED',
    file_uri_list   => 'https://<bucket-or-container>/<path>/metadata.json',
    format          => '{"access_protocol": {"protocol_type": "iceberg"}}'
  );
END;
/

الخيار C: كتالوج Hadoop على OCI Object Storage

للجداول المكتوبة بكتالوج Hadoop (مثلًا عبر OCI Data Flow)، مرّر مجلد المستودع (warehouse) ومسار database.table.

-- From Oracle's documented syntax, not run.
BEGIN
  DBMS_CLOUD.CREATE_EXTERNAL_TABLE(
    table_name      => 'ORDERS_LAKE',
    credential_name => 'OCI_CRED',
    format          => '{
      "access_protocol": {
        "protocol_type": "iceberg",
        "protocol_config": {
          "iceberg_catalog_type": "hadoop",
          "iceberg_warehouse": "https://objectstorage.<region>.oraclecloud.com/n/<namespace>/b/<bucket>/o/<warehouse_folder>",
          "iceberg_table_path": "<database>.<table>"
        }
      }
    }'
  );
END;
/

الخيار D: كتالوج REST (Snowflake Polaris)

تحتاج كتالوجات REST إلى مجموعتين من بيانات الاعتماد. هذا شكل Polaris لدى أوراكل. أما Databricks Unity Catalog وGoogle Lakehouse runtime catalog فانسخ JSON المعامل format من أدلة البدء السريع لكل مزوّد في وثائق أوراكل، لأن JSON يختلف من كتالوج لآخر.

-- From Oracle's documented syntax, not run.
-- Catalog credential (OAuth2 client credentials)
BEGIN
  DBMS_CLOUD.CREATE_CREDENTIAL(
    credential_name => 'POLARIS_OAUTH',
    username        => '<client_id>',
    password        => '<client_secret>');
END;
/

-- credential_name reads the files; rest_auth_cred talks to the catalog
BEGIN
  DBMS_CLOUD.CREATE_EXTERNAL_TABLE(
    table_name      => 'SALES_POLARIS',
    credential_name => 'S3_CRED',
    format          => q'[{
      "access_protocol": {
        "protocol_type": "iceberg",
        "protocol_config": {
          "iceberg_catalog_type": "polaris",
          "rest_catalog_prefix": "<polaris_catalog_name>",
          "rest_catalog_endpoint": "https://<account>.snowflakecomputing.com/polaris/api/catalog",
          "rest_authentication": {
            "rest_auth_cred": "POLARIS_OAUTH",
            "rest_auth_endpoint": "https://<account>.snowflakecomputing.com/polaris/api/catalog/v1/oauth/tokens"
          },
          "table_path": ["<namespace>", "<table>"]
        }
      }
    }]'
  );
END;
/

5. تأكّد من أنه يعمل

الفحص السريع لدى أوراكل عدّ بسيط. فإذا أعاد رقمًا، فبيانات الاعتماد وقوائم ACL وموقع الجدول صحيحة. بعدها امنح صلاحية القراءة لمن يحتاج إليها.

-- From Oracle's documented syntax, not run.
SELECT COUNT(*) FROM orders;

-- Readers need SELECT on the table and DWROLE, not the network ACLs
GRANT SELECT ON orders TO <reader>;

6. استعلم، ودع تقليم الأقسام يتخطى الملفات

استعلم عن الجدول الخارجي كأي جدول آخر. ومنذ تحديث أوراكل في أكتوبر 2026 يستخدم Autonomous AI Database أيضًا البيانات الوصفية للأقسام في ملفات manifest الخاصة بـ Iceberg ليتخطى ملفات البيانات التي لا يمكن أن تحتوي صفًا مطابقًا. لا شيء تفعّله ولا صياغة جديدة. ولا تعرّف أقسام أوراكل على الجدول الخارجي، ولا تُضاف قيم الأقسام إلى نتائجك. وتبقى النتائج كما لو مُسح الجدول كاملًا؛ الذي يتغير هو الملفات المقروءة فقط.

• يحدث التقليم عندما يحمل الاستعلام شرطًا مدعومًا على عمود المصدر في Iceberg: العمود الذي بُني عليه تحويل الأقسام (partition transform). فصفِّ على customer_id، لا على رقم الدلو (bucket).
• مثال أوراكل: الجدول orders مقسّم وفق bucket(4, customer_id). والشرط WHERE customer_id = 202 يقع في الدلو 1، فلا تُقرأ إلا ملفات بيانات الدلو 1.
• الشرط الذي لا يصل إلى جدول Iceberg إلا عبر ربط (join) لا يُضمن أن يؤدي إلى التقليم، وتنبّه أوراكل إلى عدم افتراض ذلك.

-- From Oracle's documented syntax, not run.
-- orders is partitioned in Iceberg by bucket(4, customer_id)

-- Prunes: supported filter on the partition source column
SELECT * FROM orders WHERE customer_id = 202;

-- May not prune: the value only reaches orders through the join
SELECT o.*
FROM   orders o JOIN customers c ON c.customer_id = o.customer_id
WHERE  c.customer_id = 202;

-- Same rows (inner equi-join), plus a direct filter that can prune
SELECT o.*
FROM   orders o JOIN customers c ON c.customer_id = o.customer_id
WHERE  c.customer_id = 202
AND    o.customer_id = 202;

-- From Oracle's documented syntax, not run.
-- SQLcl or SQL*Plus: show the elapsed time of each statement
SET TIMING ON

SELECT COUNT(*)
FROM   orders o JOIN customers c ON c.customer_id = o.customer_id
WHERE  c.customer_id = 202;

SELECT COUNT(*)
FROM   orders o JOIN customers c ON c.customer_id = o.customer_id
WHERE  c.customer_id = 202
AND    o.customer_id = 202;

يعتمد الزمن المنقضي على بياناتك وتوزيع ملفاتك وقاعدتك، فاختبر على جداولك أنت. لا تنشر أوراكل رقمًا لمقدار التسريع في هذه الميزة، ولا ننشر نحن رقمًا كذلك.

السفر عبر الزمن (اختياري)

توثّق أوراكل أيضًا السفر عبر الزمن (time travel) لجداول Iceberg الخارجية: تقرأ عبارة AS OF TIMESTAMP أحدث لقطة في الوقت الذي تحدده أو قبله. وهي مدعومة مع Databricks وAWS Glue وكتالوج Hadoop على OCI Object Storage. وتسرد DBMS_CLOUD.ICEBERG_TABLE_HISTORY اللقطات المتاحة للاختيار. ويجب أن تبقى البيانات الوصفية للقطة وملفات بياناتها موجودة، فاللقطات التي أزالتها صيانة Iceberg بعد انتهاء صلاحيتها (expired) لا يمكن قراءتها. وإذا حدّدت وقتًا أقدم من السجل الذي تراه القاعدة فستحصل على خطأ، ويجب أن يطابق مخطط الجدول الخارجي مخطط اللقطة.

-- From Oracle's documented syntax, not run.
-- 1. List the snapshots Iceberg still keeps
SELECT snapshot_id, committed_at
FROM   TABLE(DBMS_CLOUD.ICEBERG_TABLE_HISTORY('ORDERS'))
ORDER  BY committed_at;

-- 2. Read the table as it was at a point in time
SELECT COUNT(*)
FROM   orders
AS OF TIMESTAMP TO_TIMESTAMP_TZ('<yyyy-mm-dd hh24:mi:ss> UTC', 'YYYY-MM-DD HH24:MI:SS TZR');

القيود

تتعامل الجهات الكاتبة مع تغييرات الصفوف بإحدى طريقتين: فطريقة copy-on-write تعيد كتابة ملفات البيانات المتأثرة، أما طريقة merge-on-read فتُبقي الملفات القديمة وتكتب بجانبها ملفات حذف (delete files) صغيرة. وهذا الفرق مهم للقيد الأول.

• التغييرات بنمط merge-on-read: إذا سجّلت الجهة الكاتبة عمليات الحذف أو التحديث في ملفات حذف منفصلة، تفشل استعلاماتك بخطأ. أما الجداول التي تستخدم copy-on-write فتعمل.
• تغيير المخطط: مخطط الجدول الخارجي ثابت منذ إنشائه. فإذا تغيّر مخطط Iceberg فأعد إنشاء الجدول الخارجي.
• جداول البيانات الوصفية المباشرة لا تتقدم: تبقى على اللقطة الموجودة في ملف metadata.json الخاص بها. أعد إنشاءها على ملف أحدث لترى البيانات الجديدة.
• لا DML: يُستعلم عن جدول Iceberg الخارجي ولا يُحدَّث.
• كتالوجات REST المعتمدة: الكتالوجان الوحيدان من نوع REST اللذان اعتمدتهما أوراكل رسميًا للقراءة هما Snowflake Polaris وDatabricks Unity Catalog، وUnity لجداول UniForm فقط. ويقتصر دعم Google على جداول Iceberg التي أنشأها BigQuery في GCS.
• بيانات الاعتماد والكتالوجات: راجع التحذير في الخطوة 2 والقائمة المدعومة في الخطوة 1.
• السفر عبر الزمن: فقط مع Databricks وAWS Glue وكتالوج Hadoop على OCI، وللقطات التي ما زالت محفوظة فقط.

حل المشكلات

• ظهور ORA-20000: Failed to generate column list أو ORA-24247: network access denied by access control list (ACL) عند إنشاء الجدول: ينقص المخطط المالك عادةً ACL لأحد المضيفين. راجع كل مضيف، بما فيها وكيل HTTPS، ونقطتي اتصال الحاوية الإقليمية وغير الإقليمية في S3. وإذا كانت قوائم ACL صحيحة فراجع بيانات الاعتماد.
• تفشل استعلامات على جدول كان يعمل بالأمس: تحقّق مما إذا بدأت الجهة الكاتبة إنتاج ملفات حذف بنمط merge-on-read، أو تغيّر مخطط Iceberg. وفي حال تغيّر المخطط أعد إنشاء الجدول الخارجي.
• البيانات الجديدة لا تظهر: إذا كان الجدول يشير إلى ملف metadata.json فهو مثبّت على تلك اللقطة. أعد إنشاءه على الملف الأحدث، أو انتقل إلى جدول عبر كتالوج.
• أخطاء AWS Glue: تأكّد أن الحاوية وكتالوج Glue في المنطقة نفسها، وأن بيانات اعتماد واحدة تعمل للاثنين.
• توقف Google Lakehouse runtime catalog عن العمل: ربما انتهت صلاحية رمز bearer. حدّث بيانات الاعتماد برمز جديد، أو استخدم البريد الإلكتروني لحساب الخدمة مع مفتاحه الخاص.
• لا تحسّن في السرعة: تأكّد أن الشرط على عمود المصدر للأقسام في جدول Iceberg نفسه، لا على جدول مربوط فقط. وقارن بالاستعلام نفسه مع القيمة الحرفية (literal) على عمود المصدر.

قائمة التحقق

1. اختر بين الكتالوج (للإنتاج) والعمل بلا كتالوج: مجلد مستودع Hadoop، أو ملف metadata.json واحد (لقطة ثابتة).
2. تأكّد أن زوج الكتالوج والتخزين لديك ضمن قائمة أوراكل المدعومة.
3. امنح المخطط الذي ينشئ الجدول الدور DWROLE وقوائم ACL لاتصال HTTPS إلى كل مضيف.
4. أنشئ بيانات اعتماد التخزين، وبيانات اعتماد للكتالوج في كتالوجات REST. واستخدم القيم البديلة (placeholders) في كل ما تشاركه.
5. أنشئ الجدول الخارجي مع "protocol_type": "iceberg" وبلا قائمة أعمدة.
6. شغّل SELECT COUNT(*)، ثم امنح SELECT للقرّاء.
7. صفِّ على عمود المصدر للأقسام، ولا تعتمد على الشروط القادمة عبر الربط لتحقيق التقليم.
8. نسّق مع الجهة الكاتبة للجدول: ألّا تُنتج ملفات حذف بنمط merge-on-read، وأن تُبلغك قبل أي تغيير في المخطط.
9. قِس زمن أثقل استعلاماتك مع شرط على عمود المصدر وبدونه.

الخلاصة القصيرة لقاعدة التقليم: ملاحظة تقليم أقسام Iceberg. المصادر: Query Apache Iceberg Tables وDBMS_CLOUD subprograms وWhat's New for Autonomous AI Database Serverless.

اختبر فهمك