Apache Iceberg-Tabellen abfragen

• Unity Native Iceberg (REST): Wird nicht unterstützt.

  Problemumgehung: Verwenden Sie Delta + UniForm, um eine Iceberg-lesbare Ansicht über den Iceberg-REST-Endpunkt von Unity Catalog zu veröffentlichen.

• Zertifizierte REST-Kataloge: ADB ist mit Snowflake Polaris und Databricks Unity Catalog (nur UniForm) für Iceberg-Lesezugriff zertifiziert.

• Katalogzugangsdaten-Vending: Nicht unterstützt.

  Cloud-natives rollenbasiertes Vending, wie automatische Rollenannahme oder temporäre von STS ausgestellte Zugangsdaten, wird nicht unterstützt. Verwenden Sie explizite Zugriffs-/Secret-Keys oder statische Token.)

• AWS-ARN-Zugangsdaten: Nicht unterstützt. IAM-Rollen-ARNs und AssumeRole über ARN werden nicht akzeptiert.

• Partitionierte Iceberg-Tabellen werden nicht unterstützt. Nur nicht partitionierte Tabellen sind zulässig.
• Updates auf Zeilenebene (Merge-on-Read): Nicht unterstützt. Wenn Iceberg-Metadaten Dateien löschen, schlagen Abfragen fehl.

• Das Schema einer festen externen Tabelle wird bei der Erstellung bestimmt und muss mit der Iceberg-Schemaversion in den Metadaten übereinstimmen. Wenn das Iceberg-Schema aktualisiert wird, muss die externe Tabelle neu erstellt werden.

• Keine Abfragezeitreise: Die Abfrage nach Snapshot, Version oder Zeitstempel wird nicht unterstützt.
• Nur Non_catalog: Neue Snapshots werden nicht automatisch ausgewählt. Um einen bestimmten Snapshot zu lesen, zielen Sie darauf ab, dass der Snapshot die externe Tabelle metadata.json und neu erstellen enthält.

• Zugangsdatenausrichtung: Für AWS S3 und AWS Glue müssen dieselben Zugangsdaten verwendet werden.
• Region Co-Location: S3-Buckets und der AWS Glue-Katalog müssen sich in derselben AWS-Region befinden.

• rest_auth_cred: authentifiziert sich beim Katalogservice (z.B. Unity oder Polaris).

• credential_name: authentifiziert sich beim Objektspeicher, in dem sich die Iceberg-Daten und -Metadaten befinden.

• Eine mit UniForm erstellte Delta-Tabelle, damit Iceberg-Clients sie lesen können.

• Tabellendateien in Azure ADLS Gen2 oder AWS S3.

• Unity-Katalogberechtigungen für externen Zugriff (z.B. "Externer Datenzugriff aktiviert") und EXTERNAL USE SCHEMA für Ihren Principal erteilen.

• Authentifizierung: OAuth2 (empfohlen) oder persönliches Zugriffstoken (für Schnelltests).

• Netzwerk-ACLs konfigurieren: Bevor Sie eine externe Tabelle erstellen, die Databricks Unity Catalog mit Daten verwendet, die in Azure Blob Storage gespeichert sind, müssen Sie dem Oracle-Schema die Berechtigung erteilen, ausgehende HTTPS-Verbindungen zu den erforderlichen Azure-Services herzustellen. Da Oracle Database standardmäßig den Netzwerkzugriff blockiert, müssen Sie die Network Access Control-Liste (ACL) aktualisieren, damit das Schema Folgendes erreichen kann:

  • Der Databricks-Workspace, der Unity Catalog-APIs und Token-/Authentifizierungsendpunkte hostet.

  • Der Azure Storage-Account, in dem die Metadaten und Datendateien der Iceberg-Tabelle gespeichert werden.

  Beispiel für die Konfiguration von Netzwerk-ACLs

  BEGIN
     -- Databricks workspace (Unity Catalog and token endpoint)
     DBMS_NETWORK_ACL_ADMIN.APPEND_HOST_ACE(
        host           => '<workspace>.azuredatabricks.net',
        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
                          )
     );
  
     -- Azure Storage (metadata and data files)
     DBMS_NETWORK_ACL_ADMIN.APPEND_HOST_ACE(
        host           => '<storage-account>.blob.core.windows.net',
        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;
  /

  Ersetzen Sie die folgenden Platzhalter:

  • <workspace>: Der Databricks-Workspace-Name, der in Ihrer Azure-Databricks-URL verwendet wird.
  • <storage-account>: Der Azure Storage-Accountname, der Iceberg-Metadaten und -Datendateien enthält.
  • <schema>: Das Oracle-Schema, das DBMS_CLOUD.CREATE_EXTERNAL_TABLE ausführt und HTTPS-Zugriff erfordert.

USE CATALOG <your_catalog>;
USE SCHEMA  <your_schema>;

CREATE TABLE customers_iceberg (
  id   INT,
  name STRING
)
TBLPROPERTIES(
  'delta.columnMapping.mode'='name',
  'delta.enableIcebergCompatV2'='true',
  'delta.universalFormat.enabledFormats'='iceberg'
);

INSERT INTO customers_iceberg (id, name) VALUES
  (1,'Alice'), (2,'Bob'), (3,'Carol');

BEGIN
  BEGIN DBMS_CLOUD.DROP_CREDENTIAL('AZURE_BLOB_CRED'); EXCEPTION WHEN OTHERS THEN NULL; END;
  DBMS_CLOUD.CREATE_CREDENTIAL(
    credential_name => 'AZURE_BLOB_CRED',
    username        => '<storage-account-or-sas-username>',
    password        => '<storage-key-or-sas-token>'
  );
END;
/

-- Databricks service principal (client_id / client_secret)
BEGIN
  BEGIN DBMS_CLOUD.DROP_CREDENTIAL('UNITY_OAUTH'); EXCEPTION WHEN OTHERS THEN NULL; END;
  DBMS_CLOUD.CREATE_CREDENTIAL(
    credential_name => 'UNITY_OAUTH',
    username        => '<client_id>',
    password        => '<client_secret>'
  );
END;
/

BEGIN
  DBMS_CLOUD.CREATE_EXTERNAL_TABLE(
    table_name      => 'CUSTOMERS_ICEBERG',
    credential_name => 'AZURE_BLOB_CRED',
    format          => '{
      "access_protocol": {
        "protocol_type": "iceberg-rest",
        "protocol_config": {
          "iceberg_catalog_type": "unity",
          "rest_catalog_endpoint": "https://<workspace-host>/api/2.1/unity-catalog/iceberg",
          "rest_authentication": {
            "rest_auth_cred": "UNITY_OAUTH",
            "rest_auth_endpoint": "https://<workspace-host>/oidc/v1/token"
          },
          "table_path": ["<your_catalog>","<your_schema>","customers_iceberg"]
        }
      }
    }'
  );
END;
/
SELECT COUNT(*) FROM CUSTOMERS_ICEBERG;

BEGIN
  BEGIN DBMS_CLOUD.DROP_CREDENTIAL('UNITY_PAT'); EXCEPTION WHEN OTHERS THEN NULL; END;
  DBMS_CLOUD.CREATE_CREDENTIAL(
    credential_name => 'UNITY_PAT',
    username        => 'token',
    password        => '<dapiXXXXXXXXXXXXXXXXXXXXXXXX>'
  );
END;
/

BEGIN
  DBMS_CLOUD.CREATE_EXTERNAL_TABLE(
    table_name      => 'CUSTOMERS_ICEBERG',
    credential_name => 'AZURE_BLOB_CRED',
    format          => '{
      "access_protocol": {
        "protocol_type": "iceberg-rest",
        "protocol_config": {
          "iceberg_catalog_type": "unity",
          "rest_catalog_endpoint": "https://<workspace-host>/api/2.1/unity-catalog/iceberg",
          "rest_authentication": { "rest_auth_cred": "UNITY_PAT" },
          "table_path": ["<your_catalog>","<your_schema>","customers_iceberg"]
        }
      }
    }'
  );
END;
/
SELECT COUNT(*) FROM CUSTOMERS_ICEBERG;

• Polaris Iceberg Katalog und Endpunkt für Ihren Account verfügbar.

• Tabellendateien, auf die in Ihrem Objektspeicher zugegriffen werden kann (S3/ADLS, sofern zutreffend).

• Auth: OAuth2 empfohlen (Clientzugangsdaten) oder ein anderer von Polaris unterstützter Tokenmechanismus.

• Bevor Sie eine externe Tabelle erstellen, die auf einen Iceberg-Katalog zugreift, der in Snowflake und Amazon S3 gespeichert ist, muss das Datenbankschema berechtigt sein, ausgehende HTTPS-Verbindungen zu diesen Services herzustellen. Oracle Database schränkt den Netzwerkzugriff standardmäßig ein. Daher müssen Sie die Network Access Control-Liste (ACL) aktualisieren, damit das Schema Folgendes erreichen kann:

  • Ihre Snowflake-Accountendpunkte, die für Katalogzugriff, Authentifizierung und Tokenaustausch verwendet werden

  • Der regionale Endpunkt von Amazon S3, an dem Iceberg Metadaten und Datendateien gespeichert werden

  • (Optional) Der nicht-regionale S3-Endpunkt, der für einige AWS-APIs und Regions-Lookup-Vorgänge erforderlich ist

  Beispiel für die Konfiguration von Netzwerk-ACLs

  BEGIN
  
     -- Allow HTTPS access to your Snowflake account (Polaris and token endpoints)
     DBMS_NETWORK_ACL_ADMIN.APPEND_HOST_ACE(
        host           => '<account>.snowflakecomputing.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
                          )
     );
  
     -- Allow HTTPS access to the S3 bucket (regional endpoint for data/metadata)
     DBMS_NETWORK_ACL_ADMIN.APPEND_HOST_ACE(
        host           => '<bucket>.s3.<region>.amazonaws.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
                          )
     );
  
     -- Optional: non-regional S3 endpoint (used for some APIs/region lookup)
     DBMS_NETWORK_ACL_ADMIN.APPEND_HOST_ACE(
        host           => '<bucket>.s3.amazonaws.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;
  /

  Ersetzen Sie die folgenden Platzhalter:

  • <account>: Ihre Snowflake-Account-ID.

  • <schema>: Das Schema, das ausgehenden HTTPS-Zugriff benötigt.

  • <bucket>: Der Name des Amazon S3-Buckets, der die Iceberg-Daten und -Metadaten enthält.

  • <region>: Die AWS-Region, in der der Bucket S3 gehostet wird.

BEGIN
  DBMS_CLOUD.CREATE_EXTERNAL_TABLE(
    table_name      => 'SALES_POLARIS',
    credential_name => 'S3_CRED',
    format          => '{
      "access_protocol": {
        "protocol_type": "iceberg-rest",
        "protocol_config": {
          "iceberg_catalog_type": "polaris",
          "rest_catalog_endpoint": "<https://<your-polaris-endpoint>/...>",
          "rest_authentication": {
            "rest_auth_cred": "POLARIS_OAUTH",
            "rest_auth_endpoint": "<https://<your-oauth-token-endpoint>>"
          },
          "table_path": ["<db>","<schema>","<table>"]
        }
      }
    }'
  );
END;
/

SELECT COUNT(*) FROM SALES_POLARIS;

• Kleben Sie den Datenkatalog mit der registrierten Iceberg-Tabelle (S3-Objekte zugänglich).

  Regionsname für Kleber (z.B. us-east-1).

• Auth: Zugriff auf Schlüssel/Secret für S3; Glue-Zugriff über Katalogkonfiguration.

• Zugangsdaten-Vending über AWS ARN wird nicht unterstützt. Explizite Zugangsdaten müssen angegeben werden.

• Bevor Sie eine externe Tabelle erstellen, die AWS Glue als Iceberg-Katalog und Amazon S3 als Speicherebene verwendet, muss dem Oracle-Schema die Berechtigung erteilt werden, ausgehende HTTPS-Anforderungen an diese AWS-Services auszuführen. Oracle Database schränkt den Netzwerkzugriff standardmäßig ein. Daher müssen Sie die Network Access Control-Liste (ACL) aktualisieren, damit das Schema Folgendes erreichen kann:

  • AWS Glue, das die Iceberg-Katalog-API bereitstellt

  • Der regionale Endpunkt S3, in dem Iceberg-Metadaten und Datendateien gespeichert werden

  • Der nichtregionale S3-Endpunkt, der für bestimmte AWS-APIs und Regions-Lookup-Vorgänge erforderlich ist

  Beispiel für die Konfiguration von Netzwerk-ACLs

  BEGIN
  
     -- AWS Glue (catalog API)
     DBMS_NETWORK_ACL_ADMIN.APPEND_HOST_ACE(
        host           => 'glue.<region>.amazonaws.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
                          )
     );
  
     -- S3 bucket (regional endpoint for data and metadata files)
     DBMS_NETWORK_ACL_ADMIN.APPEND_HOST_ACE(
        host           => '<bucket>.s3.<region>.amazonaws.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
                          )
     );
  
     -- Optional: non-regional S3 endpoint (used for some APIs or region lookup)
     DBMS_NETWORK_ACL_ADMIN.APPEND_HOST_ACE(
        host           => '<bucket>.s3.amazonaws.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;
  /

  Ersetzen Sie die folgenden Platzhalter:

  • <region>: Die AWS-Region, in der sich Glue und der Bucket S3 befinden.

  • <bucket>: Der Name des S3-Buckets, der Iceberg-Daten- und Metadatendateien speichert.

  • <schema>: Das Oracle-Schema, das DBMS_CLOUD.CREATE_EXTERNAL_TABLE ausführt und HTTPS-Zugriff erfordert.

BEGIN
  DBMS_CLOUD.CREATE_EXTERNAL_TABLE(
    table_name      => 'ORDERS_GLUE',
    credential_name => 'S3_CRED',
    format          => '{
      "access_protocol": {
        "protocol_type": "iceberg",
        "protocol_config": {
          "iceberg_catalog_type": "aws_glue",
          "iceberg_glue_region": "us-east-1",
          "table_path": ["<database>","<table>"]
        }
      }
    }'
  );
END;
/

SELECT COUNT(*) FROM ORDERS_GLUE;

• Sie können im Objektspeicher (ADLS/S3/OCI) auf das Iceberg-Root-Manifest (metadata.json) der Tabelle zugreifen.
• Dieser Pfad lautet Point-in-Time. Um neuen Snapshots zu folgen, erstellen Sie die externe Tabelle neu.

BEGIN
  DBMS_CLOUD.CREATE_EXTERNAL_TABLE(
    table_name      => 'CUSTOMERS_META',
    credential_name => 'STORE_CRED',
    file_uri_list   => 'https://<bucket-or-container>/<path>/metadata.json',
    format          => '{"access_protocol":{"protocol_type":"iceberg"}}'
  );
END;
/

BEGIN
  DBMS_CLOUD.CREATE_EXTERNAL_TABLE (
    table_name       => 'iceberg_parquet_time_dim3',
    credential_name  => 'OCI_CRED',
    format           => '{
      "access_protocol": {
        "protocol_type": "iceberg",
        "protocol_config": {
          "iceberg_catalog_type": "hadoop",
          "iceberg_lakehouse": "https://objectstorage.uk-cardiff-1.oraclecloud.com/n/my-tenancy/b/my-iceberg-bucket/o/iceberg",
          "iceberg_table_path": "db.icebergTablePy"
        }
      }
    }'
  );
END;
/