Plan Interoperability and Related Serving Patterns

Interoperability in Release 23.26.3 and above

This section applies only to Native Iceberg tables written by Oracle AI Database 26ai. The following writer, catalog, and storage combinations have completed functional validation for Release 23.26.3 and above.

Writer Catalog Storage
Oracle AI Database 26ai Oracle AI Data Catalog OCI Object Storage, ZFS S3-compatible object storage
Oracle AI Database 26ai AWS Glue Data Catalog Amazon S3
Oracle AI Database 26ai Snowflake Open Catalog Amazon S3

Each row represents a “validated” writer, catalog, and storage combination. Where a row lists more than one storage option, each listed option was validated with the writer and catalog shown in that row. Do not mix components from different rows or infer support for a combination that is not listed.

Here “Validated” indicates that functional interoperability testing completed successfully for Native Iceberg table state written by Oracle AI Database with the listed catalog and storage combination. This matrix does not certify a specific external reader and does not describe Oracle access to Iceberg tables written by other engines.

To query Iceberg tables created by other engines, see Query an Inline External Iceberg Table. For Oracle AI Data Catalog availability and integration details, see Oracle AI Data Catalog.

Supported Types and Physical Format

The Oracle Database 26ai SQL reference documents the following Iceberg column types:

The table uses Iceberg v2 metadata and Parquet data files.

STRING values read by Oracle are limited to 4000 characters. Recheck the authoritative SQL reference for the exact release before adding a type or changing the consumer contract.

Note - Data types TIMESTAMP_NS and TIMESTAMPTZ_NS are not supported for Iceberg v2 tables.

Table Properties for Iceberg Tables

Oracle AI Database supports configuring Iceberg tables by using the WITH clause in the CREATE ICEBERG TABLE statement. Table properties control various aspects of Iceberg table behavior, including how data is written, read, and how table commits, snapshots, and table operations are managed.

A table property is specified as a property–value pair. The property is stored in the properties section of the Iceberg metadata.json file. Both the property name and value are represented as strings in the metadata file.
The property name typically follows a dot-separated format, such as: write.target-file-size-bytes

Table properties can be specified:

Table properties can be removed from an existing table using ALTER ICEBERG TABLE ... UNSET.

Categories of Table Properties

Supported properties belong to the following categories:

Note - If a property is not explicitly specified at the table level, its default property value is used.

Supported Table Properties

Following is the list of supported Write properties and property validations:

Property Default Value Description
write.metadata.metrics.default truncate(16) Specifies the statistics collected for columns during write operations. The supported values are:
- none — Does not collect statistics.
- truncate(len) — Collects the minimum and maximum values up to the specified length.
write.parquet.dictionary-size-bytes 2 MB Specifies the maximum dictionary size for each column, within the range of 8 KB and 4 MB. A value of 0 disables dictionary encoding.
write.target-file-size-bytes 512 MB Specifies the maximum target size of a Parquet data file.
write.parquet.row-group-size-bytes 128 MB Specifies the maximum size of a Parquet row group.
write.parquet.page-size-bytes 1 MB Specifies the maximum size of a Parquet page.

Property Specifications

A property name uses the following format: scope.category.option
For example, write.delete.target-file-size-bytes

In Oracle DDL:

If a property is not explicitly configured at the table level, Oracle uses the default value defined for that property.

Syntax

Specifying Properties During Table Creation

CREATE ICEBERG TABLE [schema.]table_name
(
    column_definition [, column_definition ]...
)
WITHIN CATALOG catalog_name
STORAGE LOCATION "storage_location"
WITH
(
    '<property>' : '<value>'
    [, '<property>' : '<value>' ]...
);


The ellipsis represents the column definitions and other applicable CREATE ICEBERG TABLE clauses. The current implementation handles double quotes only; if using single quotes, the quote is passed as part of the URI and causes an error.

Setting Properties on an Existing Table

ALTER ICEBERG TABLE [schema.]table_name
WITHIN CATALOG catalog_name
SET
(
    '<property>' : '<value>'
    [, '<property>' : '<value>' ]...
);

Unsetting Properties on an Existing Table

ALTER ICEBERG TABLE [schema.]table_name
WITHIN CATALOG catalog_name
UNSET
(
    '<property>'
    [, '<property>' ]...
);

Examples

Create a Table with Table Properties

CREATE ICEBERG TABLE iceberg_db.session_log
(
    session_id  STRING,
    created_at  TIMESTAMP
)
WITHIN CATALOG "GLUE_ORA40"
STORAGE LOCATION "s3://iceberg-db/session_log"
WITH
(
    'write.metadata.metrics.default'   : 'none',
    'write.target-file-size-bytes'     : '268435456',
    'write.parquet.dictionary-size-bytes' : '2097152'
);

This example:

The properties are stored in metadata.json as follows:

{
  "properties": {
    "write.metadata.metrics.default": "truncate(16)",
    "write.target-file-size-bytes": "268435456",
    "write.parquet.dictionary-size-bytes": "2097152"
  }
}

–Disable Dictionary Encoding–

CREATE ICEBERG TABLE iceberg_db.sales_data
(
    sale_id     NUMBER,
    sale_amount NUMBER
)
WITHIN CATALOG "GLUE_ORA40"
STORAGE LOCATION "s3://iceberg-db/sales_data"
WITH
(
    'write.parquet.dictionary-size-bytes' : '0'
);

Where a value of 0 disables dictionary encoding.

Set Properties for an Existing Table

ALTER ICEBERG TABLE iceberg_db.session_log
WITHIN CATALOG "GLUE_ORA40"
SET
(
    'write.metadata.metrics.default' : 'none',
    'write.parquet.page-size-bytes'  : '1048576'
);

If a property already exists, Oracle updates its value. If it does not exist, Oracle adds the property to the properties section of metadata.json.

Remove Properties from an Existing Table

ALTER ICEBERG TABLE iceberg_db.session_log
WITHIN CATALOG "GLUE_ORA40"
UNSET
(
    'write.parquet.page-size-bytes'
);

After the property is removed, future operations use the default behavior for that property.

Validating Table Properties

Oracle validates properties specified in both CREATE ICEBERG TABLE and ALTER ICEBERG TABLE statements. Property names and values listed under the “Supported Table Properties” section mentioned-above are supported.

An invalid property definition raises the error ORA-52904. Properties written to metadata.json by external Iceberg engines may not be supported by Oracle. Operations that do not explicitly specify or modify such properties ignore them.

Viewing Table Properties

Iceberg table properties are stored in the properties section of the table’s metadata.json file. You can use DBMS_CATALOG.GET_TABLE to retrieve the table metadata and JSON_QUERY to extract the properties:

DECLARE
    metadata_clob CLOB;
BEGIN
    metadata_clob := DBMS_CATALOG.GET_TABLE(
        catalog_name => 'GLUE_ORA40',
        schema_name  => 'ICEBERG_DEVS_DB',
        table_name   => 'EMP',
        column_flags => DBMS_CATALOG.FETCH_FULL_METADATA
    );

    DBMS_OUTPUT.PUT_LINE(
        JSON_QUERY(
            metadata_clob,
            '$.metadata.tableDetails.metadataDetails.metadata.properties'
            RETURNING CLOB PRETTY
        )
    );
END;
/

The output is similar to:

{
  "write.metadata.metrics.default": "truncate(16)",
  "write.target-file-size-bytes": "268435456",
  "write.parquet.dictionary-size-bytes": "2097152"
}

This enables users to inspect the effective table configuration and identify the properties explicitly stored for a table.

Usage Notes

Transaction, Naming, and SQL Restrictions

See CREATE ICEBERG TABLE for the authoritative restriction list for the installed release.

Coordinate Cross-Engine Access

Another Iceberg-compatible engine can access a committed table only when it:

Oracle credentials are database objects and are not shared with another engine.

Assign one operational owner for catalog commits and compatibility policy. Before allowing another writer, verify that it will not introduce partitioning, types, delete-file modes, schema changes, or table properties unsupported by the Oracle path. Test snapshot visibility after each engine change.

Related documentation: