Consultar Tabelas de Iceberg do Apache

• Iceberg nativo da Unity (REST): Não suportado.

  Solução alternativa: Use Delta + UniForm para publicar uma view legível por Iceberg por meio do ponto final REST do Iceberg do Unity Catalog.

• Catálogos REST certificados: O ADB é certificado com Snowflake Polaris e Databricks Unity Catalog (somente UniForm) para acesso de leitura ao Iceberg.

• Vending de credencial do catálogo: Não suportado.

  Não há suporte para venda automática baseada em função nativa da nuvem, como suposição automática de função ou credenciais temporárias emitidas pelo STS. Use chaves de acesso/segredo explícitas ou tokens estáticos.)

• Credenciais do AWS ARN: não suportadas. Os ARNs da função do IAM e AssumeRole via ARN não são aceitos.

• Tabelas de Iceberg particionadas não são suportadas; apenas tabelas não particionadas são permitidas.
• Atualizações no nível da linha (intercalação na leitura): Não suportado. Se os metadados do Iceberg referenciarem arquivos de exclusão, as consultas falharão.

• O esquema de uma tabela externa fixa é determinado na criação e deve se alinhar à versão do esquema Iceberg nos metadados. Se o esquema do Iceberg for atualizado, a tabela externa deverá ser recriada.

• Nenhum deslocamento de tempo de consulta: Não há suporte para a consulta por snapshot, versão ou timestamp.
• Non_catalog somente: Novos instantâneos não são selecionados automaticamente. Para ler um instantâneo específico, direcione o instantâneo metadata.json e recrie a tabela externa.

• Alinhamento da credencial: As mesmas credenciais devem ser usadas para o AWS S3 e o AWS Glue.
• Colocalização da região: Os buckets do S3 e o catálogo do AWS Glue devem estar na mesma região da AWS.

• rest_auth_cred: autentica com o serviço de catálogo (por exemplo, Unity ou Polaris).

• credential_name: autentica-se no armazenamento de objetos no qual residem os dados e metadados do Iceberg.

• Uma tabela Delta criada com o UniForm para que os clientes Iceberg possam lê-la.

• Arquivos de tabela no Azure ADLS Gen2 ou AWS S3.

• Privilégios do Unity Catalog para acesso externo (por exemplo, acesso a dados externos ativado); conceda EXTERNAL USE SCHEMA ao seu principal).

• Auth: OAuth2 (recomendado) ou Token de Acesso Pessoal (para testes rápidos).

• Configurar ACLs de rede: Antes de criar uma tabela externa que use o Catálogo do Databricks Unity com dados armazenados no Armazenamento Blob do Azure, você deve conceder ao esquema Oracle permissão para fazer conexões HTTPS de saída com os serviços necessários do Azure. Como o Oracle Database bloqueia o acesso à rede por padrão, você deve atualizar a ACL (Network Access Control List) para permitir que o esquema atinja:

  • O espaço de trabalho do Databricks, que hospeda APIs do Unity Catalog e pontos finais de token/autenticação.

  • A conta de Armazenamento do Azure, que armazena os metadados e os arquivos de dados da tabela Iceberg.

  Exemplo de configuração de ACLs de rede

  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;
  /

  Substitua os seguintes placeholders:

  • <workspace>: O nome do espaço de trabalho do Databricks usado no URL do Azure Databricks.
  • <storage-account>: O nome da conta do Armazenamento do Azure que contém metadados e arquivos de dados do Iceberg.
  • <schema>: O esquema Oracle que executará o DBMS_CLOUD.CREATE_EXTERNAL_TABLE e exigirá acesso HTTPS.

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;

• Catálogo e endpoint da Polaris Iceberg disponíveis para a sua conta.

• Arquivos de tabela acessíveis em seu armazenamento de objetos (S3/ADLS, conforme aplicável).

• Auth: OAuth2 recomendado (credenciais do cliente) ou outro mecanismo de token suportado pelo Polaris.

• Antes de criar uma tabela externa que acesse um catálogo do Iceberg armazenado no Snowflake e no Amazon S3, o esquema do banco de dados deve ter permissão para fazer conexões HTTPS de saída com esses serviços. O Oracle Database restringe o acesso à rede por padrão; portanto, você deve atualizar a ACL (Network Access Control List) para permitir que o esquema atinja:

  • Seus pontos finais de conta do Snowflake, usados para acesso ao catálogo, autenticação e troca de tokens

  • O ponto final regional do Amazon S3 no qual os metadados e os arquivos de dados do Iceberg são armazenados

  • (Opcional) O ponto final S3 não regional, exigido por algumas APIs da AWS e operações de pesquisa de região

  Exemplo de configuração de ACLs de rede

  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;
  /

  Substitua os seguintes placeholders:

  • <account>: Identificador da sua conta do Snowflake.

  • <schema>: O esquema que precisa de acesso HTTPS de saída.

  • <bucket>: O nome do bucket do Amazon S3 que contém os dados e metadados do Iceberg.

  • <region>: A região da AWS na qual o bucket S3 está hospedado.

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;

• Catálogo de Dados de Colagem com a tabela Iceberg registrada (objetos S3 acessíveis).

  Nome da região para Cola (por exemplo, us-east-1).

• Autenticação: Chave/segredo de acesso para S3; Acesso de cola por meio da configuração do catálogo.

• A venda de credenciais por meio do AWS ARN não é suportada. As credenciais explícitas devem ser fornecidas.

• Antes de criar uma tabela externa que use o AWS Glue como catálogo Iceberg e o Amazon S3 como camada de armazenamento, o esquema Oracle deve receber permissão para fazer solicitações HTTPS de saída para esses serviços da AWS. O Oracle Database restringe o acesso à rede por padrão; portanto, você deve atualizar a ACL (Network Access Control List) para permitir que o esquema atinja:

  • AWS Glue, que fornece a API do catálogo Iceberg

  • O ponto final regional S3, no qual os metadados e os arquivos de dados do Iceberg são armazenados

  • O ponto final S3 não regional, que é necessário para determinadas APIs da AWS e operações de pesquisa de região

  Exemplo de configuração de ACLs de rede

  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;
  /

  Substitua os seguintes placeholders:

  • <region>: A região da AWS na qual a Glue e o bucket S3 estão localizados.

  • <bucket>: O nome do bucket S3 que armazena dados do Iceberg e arquivos de metadados.

  • <schema> : O esquema Oracle que executa o DBMS_CLOUD.CREATE_EXTERNAL_TABLE e requer acesso HTTPS.

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;

• Você pode acessar o manifesto raiz do Iceberg da tabela (metadata.json) no seu armazenamento de objetos (ADLS/S3/OCI).
• Esse caminho é point-in-time. Para seguir novos snapshots, recrie a tabela externa.

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;
/