Read Iceberg Tables

Direct Metadata Access

Use Direct Metadata for an Explicit Table Version

Use direct metadata only for testing, troubleshooting, debugging, or a deliberately fixed and reproducible table version. For production access that must follow the authoritative table state, use a catalog-managed path described in Select a Catalog Implementation.

Note - Do not use direct metadata as the normal production access path. A direct metadata.json URI pins the Oracle definition to one Iceberg metadata version and does not follow later catalog commits automatically.

For details about Oracle syntax, metadata locations, and restrictions for direct Apache Iceberg access, see Access Apache Iceberg with ORACLE_BIGDATA.

Create a Persistent External Iceberg Table

The following example creates a local external table from a producer-supplied metadata URI. Oracle derives the Iceberg schema; do not provide an independent column_list or field_list.

BEGIN
  DBMS_CLOUD.CREATE_EXTERNAL_TABLE(
    table_name => 'CUSTOMERS_ICEBERG',
    credential_name => 'ICEBERG_DATA_CREDENTIAL',
    file_uri_list => '<supported-object-store-uri>/customers/metadata/00001.metadata.json',
    format => '{"access_protocol":{"protocol_type":"iceberg"}}'
  );
END;
/

Use a URI format and storage combination supported by the selected Oracle AI Database deployment. The credential must read the supplied metadata file and every manifest, data file, and supported delete file selected through that metadata.

Query the table with normal SQL

SELECT customer_id, email, signup_date
FROM customers_iceberg
WHERE signup_date >= DATE '2026-01-01';

Query an Inline External Iceberg Table

Use an inline external table when the Iceberg mapping is required by only one statement. The definition is placed in FROM EXTERNAL (...) and is discarded when the statement completes.

The following direct-metadata example declares the complete compatible Oracle column definition for the sample Iceberg schema:

SELECT customer_id, first_name, last_name, email, signup_date
FROM EXTERNAL (
       (
         customer_id NUMBER,
         first_name VARCHAR2(64),
         last_name VARCHAR2(64),
         email VARCHAR2(64),
         signup_date DATE
       )
       TYPE ORACLE_BIGDATA
       ACCESS PARAMETERS (
         com.oracle.bigdata.fileformat=parquet
         com.oracle.bigdata.credential.name=ICEBERG_DATA_CREDENTIAL
         com.oracle.bigdata.access_protocol=iceberg
       )
       LOCATION ('iceberg:<supported-object-store-uri>/customers/metadata/00001.metadata.json')
     ) customers_iceberg
WHERE signup_date >= DATE '2026-01-01';

The declared Oracle columns must remain compatible with the resolved Iceberg schema. The URI form, credential, and access parameters remain deployment- and provider-specific.

The supported access parameters differ for direct metadata, AWS Glue, and Iceberg REST implementations. Use the exact inline syntax in the ORACLE BIGDATA Apache Iceberg documentation; do not translate a persistent DBMS_CLOUD JSON example into inline syntax by inference.

Mounted Catalog Access

Select a Catalog Implementation

For production access, use the catalog-managed path and select the implementation that owns the authoritative table metadata. A mounted catalog resolves the current table metadata by logical name instead of pinning a database definition to one metadata.json object.

Catalog Implementation	Connection Model	Database Mount Procedure	`catalog_type` parameter	Credential Boundary
Oracle AI Data Catalog (AI Lakehouse)	Oracle-managed Iceberg REST catalog	`DBMS_CATALOG`.`MOUNT_ICEBERG`	`ICEBERG_ORACLE`	Catalog credential and data-storage credential
AWS Glue	AWS Glue catalog integration	`DBMS_CATALOG.MOUNT_DATA_CATALOG`	`AWS_GLUE` through the `data_catalog_type` parameter	An explicit AWS identity must authorize catalog metadata and the referenced object-storage data; region and credential restrictions are path-specific.
Snowflake Polaris	Polaris Iceberg REST implementation	`DBMS_CATALOG.MOUNT_ICEBERG`	`ICEBERG_POLARIS`	Catalog OAuth or bearer credential plus a separate data-storage credential
Databricks Unity Catalog	Unity Catalog Iceberg REST implementation	`DBMS_CATALOG`.`MOUNT_ICEBERG`	`ICEBERG_UNITY`	Catalog OAuth or bearer credential plus a separate data-storage credential

Oracle AI Data Catalog in this table is an operational Iceberg catalog. It is distinct from the enterprise AI Catalog role described in Chapter 3.

Local Catalog (`DBMS_CATALOG`) Implementation

To perform write operations on Iceberg tables, Oracle uses the local Catalog infrastructure.

A local Catalog consisting of the DBMS_CATALOG PL/SQL package and supporting catalog objects, provides a unified interface for accessing external data catalogs, such as AWS Glue. Before accessing an Iceberg table, you must mount the external catalog in an Oracle AI Database. Once mounted, Iceberg tables are referenced using the @catalog syntax, which is similar to Oracle AI database links. For example,

SELECT * FROM sales.orders@GLUE_CAT;

Oracle uses mounted catalog to retrieve Iceberg table metadata, locate the current table snapshot, and commit metadata updates after DML operations.

For details about Oracle catalog types and mount parameters, see DBMS_CATALOG.
For the Oracle enterprise catalog option, see Oracle AI Data Catalog.

Mount the Authoritative Catalog

Use the provider-specific DBMS_CATALOG procedure and documented parameter values. Do not substitute a generic catalog-type value.

The following pattern shows the Oracle-managed Iceberg catalog integration. Replace placeholders with values from the deployment-specific catalog documentation.

BEGIN
  DBMS_CATALOG.MOUNT_ICEBERG(
    catalog_name => 'ICEBERG_CAT',
    endpoint => '<oracle-catalog-endpoint>',
    catalog_credential => 'ICEBERG_CATALOG_CREDENTIAL',
    data_storage_credential => 'ICEBERG_DATA_CREDENTIAL',
    catalog_type => 'ICEBERG_ORACLE'
  );
END;
/

AWS Glue uses a different procedure and configuration model:

BEGIN
  DBMS_CATALOG.MOUNT_DATA_CATALOG(
    catalog_name => 'GLUE_CAT',
    data_catalog_type => 'AWS_GLUE',
    data_catalog_region => 'us-west-2',
    data_catalog_credential => 'AWS_CATALOG_CREDENTIAL',
    data_storage_credential => 'AWS_DATA_CREDENTIAL'
  );
END;
/

For Polaris and Unity, use the implementation-specific MOUNT_ICEBERG catalog type and configuration documented for the release. A successful mount proves metadata connectivity; it does not prove that the storage credential can read the table files.

Query a Mounted Iceberg Table

Reference the source schema, table, and database-local catalog name:

SELECT order_id, order_date, amount
FROM sales.orders@iceberg_cat
WHERE order_date >= DATE '2026-01-01';

Oracle first resolves SALES.ORDERS in ICEBERG_CAT, then follows the table metadata and reads the selected storage objects. If the object is discoverable but the query fails, validate the data-storage credential and its local mapping before remounting the catalog.

Refresh Catalog Metadata

DBMS_CATALOG metadata cache and Lake Cache are different. Use the provider-supported catalog cache operation when namespaces, table definitions, or current metadata locations are stale. Use Lake Cache procedures only for cached table data.

Flush or prefill catalog metadata deliberately and validate the affected table after the operation. Repeatedly flushing a healthy cache increases remote planning work and does not repair storage authorization.

For details about the supported catalog refresh operations and parameters, see DBMS_CATALOG.

Vector Search on External Iceberg Tables (Vector on Ice)

Oracle AI Database supports IVF vector indexes on documented external Iceberg tables in object storage. The index is file-local: Oracle can build an IVF index partition for each underlying data file, which enables incremental index maintenance as Iceberg snapshots change. This makes approximate nearest-neighbor search practical without copying the entire vector dataset into a database table.

Scope and Prerequisites

This capability applies to the documented external Iceberg table path. Do not infer support for Native Iceberg tables or every mounted-catalog path from this section.
The Iceberg table must be non-partitioned and use the Copy-on-Write table property.
The Oracle external table requires a single-column key declared PRIMARY KEY RELY DISABLE; the corresponding source column must be unique and not null.
Enable the hidden external-table columns required by the documented vector-index procedure before creating the index. Use the released procedure and privileges for the selected deployment.
IVF indexes with included columns are not supported for external Iceberg tables.

Choose the Freshness Model

External-table Reference	Freshness behavior	Operational implication
Snapshot Reference using a `metadata.json` URI	The external table and index are bound to the referenced Iceberg snapshot.	After a new Iceberg commit, repoint, or recreate the external table for the new metadata and rebuild the index.
Catalog reference	Queries resolve the latest committed Iceberg snapshot. When index maintenance is still catching up, Oracle can combine a partial file-local IVF index with data-file scans.	Results remain evaluated against the current snapshot, while index maintenance incrementally adds structures for new files.

Run a k-ANN Query

SELECT id,       VECTOR_DISTANCE(embedding, '[0,1,7]', COSINE) AS distanceFROM product_embeddings_xtORDER BY distanceFETCH FIRST 5 ROWS ONLY;

Validate the index on representative data and inspect the execution plan before treating it as the chosen access path. For full creation, validation, and maintenance procedures, see IVF Indexing on External Iceberg Tables.