Please use the form below to provide your feedback. Because your feedback is valuable to us, the information you submit in this form is recorded in our issue tracking system (JIRA), which is publicly available. You can track the status of your feedback using the ticket number displayed in the dialog once you submit the form.

Iceberg Tables

  • concept
Enterprise Analytics provides read-only query access to Apache Iceberg tables through external catalogs, enabling unified queries across data lake and operational data without moving data.

Apache Iceberg is a high-performance open table format for large-scale analytic datasets. Enterprise Analytics connects to Iceberg catalogs to query Iceberg tables stored in external object storage — such as AWS S3, GCS, and Azure Blob Storage — using existing links for authentication.

To get started, use CREATE CATALOG to register an Iceberg catalog, then use CREATE EXTERNAL COLLECTION to expose individual Iceberg tables for querying.

Iceberg Concepts

Catalog

An Iceberg catalog is a metadata registry that maps table names to their metadata files. It manages table locations and handles create, drop, load, and list operations on tables.

In Enterprise Analytics, a catalog is a named entity registered with CREATE CATALOG. Catalogs are globally unique and do not belong to an Analytics database.

Namespace

Namespaces logically group Iceberg tables within a catalog, similar to a database or schema in relational systems. A catalog can contain multiple namespaces, and namespaces can be nested.

catalog_name
├── namespace1
│   ├── table1
│   └── table2
└── namespace2
    └── table3

When creating an external collection on a catalog, you specify the namespace and table name in the WITH clause. For more information, see CREATE EXTERNAL COLLECTION on a Catalog.

Data Files

The data files managed by Iceberg are stored in external object storage. Enterprise Analytics supports the following Iceberg data file formats:

Format Support

Parquet

Supported

Supported Catalog Types

Source Description Required Link

AWS_GLUE

AWS Glue Data Catalog — the centralized metadata repository in the AWS ecosystem.

AWS link

AWS_GLUE_REST

AWS Glue accessed via the Iceberg REST endpoint, using Sigv4-signed credentials.

AWS link

S3_TABLES

Amazon S3 Tables — a managed Iceberg table bucket on Amazon S3.

AWS link

BIGLAKE_METASTORE

Google BigLake Metastore — GCP managed metadata service with an Iceberg REST catalog API.

GCS link

NESSIE

Nessie — an open source catalog with Git-like branching semantics.

HTTP link

NESSIE_REST

Nessie accessed via its REST catalog implementation.

HTTP link

REST

REST-compatible Iceberg catalogs.

HTTP link

Supported Storage Locations

Iceberg data files can reside in the following object storage locations:

  • AWS S3

  • Google Cloud Storage (GCS)

  • Azure Blob Storage

Types Mapping

The following table describes the type mapping between Iceberg types and Enterprise Analytics types:

Iceberg Type Enterprise Analytics Type Comments

BOOLEAN

BOOLEAN

INTEGER

BIGINT

LONG

BIGINT

FLOAT

FLOAT

DOUBLE

DOUBLE

STRING

STRING

UUID

UUID

FIXED

BINARY

BINARY

BINARY

DECIMAL

Not supported

Can be parsed as DOUBLE. See [1].

STRUCT

OBJECT

LIST

ARRAY

MAP

ARRAY

ARRAY of key/value OBJECT pairs. Example: [ { "key": "key1", "value": "value1" }, { "key": "key2", "value": "value2" } ]

DATE

DATE

Can be converted to INTEGER (epoch days since 1970-01-01). See [3].

TIME

TIME

Can be converted to INTEGER (milliseconds since midnight). See [4].

TIMESTAMP

DATETIME (milliseconds precision)

Can be converted to BIGINT (microseconds since epoch). See [2].

TIMESTAMP_NANO

DATETIME (milliseconds precision)

Can be converted to BIGINT (nanoseconds since epoch). See [2].

GEOMETRY

Not supported

GEOGRAPHY

Not supported

VARIANT

Not supported

UNKNOWN

Not supported

[1] DECIMAL is not natively supported in Enterprise Analytics. To parse DECIMAL values as DOUBLE, set decimal-to-double to "true" in CREATE EXTERNAL COLLECTION. If decimal-to-double is not set, Enterprise Analytics returns an error: Decimal is not supported. To parse it as DOUBLE, set decimal-to-double to true. This property is not enabled by default because it’s a temporary workaround. When Enterprise Analytics adds native DECIMAL support, this property is no longer required.

[2] Enterprise Analytics parses datetime types to milliseconds precision. To return the original long value (microseconds since epoch for TIMESTAMP, nanoseconds since epoch for TIMESTAMP_NANO), set timestamp-as-long to "true" in CREATE EXTERNAL COLLECTION.

[3] To return DATE as INTEGER (epoch days since 1970-01-01), set date-as-int to "true" in CREATE EXTERNAL COLLECTION.

[4] To return TIME as INTEGER (milliseconds since midnight), set time-as-int to "true" in CREATE EXTERNAL COLLECTION.

Query Iceberg Tables

  1. Create Authentication Links — Create one or more links to authenticate access to the Iceberg catalog and the underlying object storage. The catalog and data file locations can use the same link or different links, depending on your setup and permissions.

    The link used to authenticate the catalog and the link used to read the data files can differ. For example, a Nessie catalog may use an HTTP link for catalog authentication while the underlying data files are stored in S3 and require an AWS link.

  2. Register the Iceberg Catalog — Use CREATE CATALOG to connect Enterprise Analytics to a supported Iceberg catalog. Once registered, the catalog is available globally in Enterprise Analytics and automatically appears in the Analytics Workbench UI.

  3. Create an External Collection — Use CREATE EXTERNAL COLLECTION to expose an Iceberg table for querying. Once created, the Iceberg table can be queried using SQL++ in the same way as any external collection.

Filtration

When Enterprise Analytics reads an Iceberg table, the following filtrations are applied in order:

  1. Only the files belonging to the specified table are scanned — no other table’s files are accessed.

  2. If a WHERE clause is provided, Enterprise Analytics applies predicates to perform partition pruning and manifest-level exclusion before reading data files.

  3. Only columns referenced in the SELECT clause are projected — not all columns in the table are read.

Partition pruning, manifest-level exclusion, and column projection reduce the amount of data scanned for selective queries. See Create an Iceberg Table for details.

Use Time Travel

Every write to an Iceberg table creates a new snapshot. Enterprise Analytics lets you query any past snapshot of an Iceberg external collection using AT SNAPSHOT or AT TIMESTAMP in a SQL++ statement, without modifying the collection definition. You can also pin a collection to a specific snapshot permanently by setting snapshotId or snapshotTimestamp in CREATE EXTERNAL COLLECTION.

AT TIMESTAMP

Returns data from the most recent snapshot at or before the specified timestamp.

SELECT * FROM <collection-name> AT TIMESTAMP '<timestamp>'

The timestamp must be a string in one of the following formats:

  • Milliseconds since Unix epoch: '<ms-since-unix-epoch>'

  • Date: 'yyyy-MM-dd'

  • Datetime: 'yyyy-MM-ddTHH:mm:ss'

Examples
SELECT * FROM usersTable AT TIMESTAMP '<ms-since-unix-epoch>'

SELECT * FROM usersTable AT TIMESTAMP '2022-07-01'

SELECT * FROM usersTable AT TIMESTAMP '2022-07-01T13:12:01'

AT SNAPSHOT

Returns data from a specific snapshot by its ID.

SELECT * FROM <collection-name> AT SNAPSHOT '<snapshot-id>'
Example
SELECT * FROM usersTable AT SNAPSHOT '1339696213265401120'

Listing Snapshots

To find available snapshot IDs and timestamps, use the following data source functions or REST endpoints.

Data Source Functions

List all snapshots for an Iceberg external collection:

SELECT * FROM list_iceberg_snapshots("<database>", "<scope>", "<collection>") AS x;

List all catalogs, namespaces, and tables registered in Enterprise Analytics:

SELECT * FROM list_iceberg_catalogs() AS x;
SELECT * FROM list_iceberg_namespaces("<catalog-name>") AS x;
SELECT * FROM list_iceberg_tables("<catalog-name>", "<namespace>") AS x;

REST API

Endpoint Description

GET /api/v1/iceberg/catalog/

Returns all catalogs registered in Enterprise Analytics.

GET /api/v1/iceberg/catalog/{catalogName}/namespace

Returns all namespaces in the specified catalog.

GET /api/v1/iceberg/catalog/{catalogName}/namespace/{namespace}/table

Returns all tables in the specified namespace.

GET /api/v1/iceberg/snapshot/{databaseName}/{scopeName}/{collectionName}

Returns all snapshots for the specified Iceberg external collection.

FAQ

Can You Use Both snapshotId and snapshotTimestamp in the Same Query?

No — specify only one at a time. Providing both returns an error.

What Snapshot Does Enterprise Analytics Read if No Snapshot Is Specified?

Enterprise Analytics reads from the latest snapshot of the table.

What’s the Difference Between a Query-Level Snapshot and a Collection-Level Snapshot?

Setting snapshotId or snapshotTimestamp in CREATE EXTERNAL COLLECTION pins the collection to that snapshot permanently — all queries against that collection use it by default. Using AT SNAPSHOT or AT TIMESTAMP in a query overrides the collection-level setting for that query only.

Can You Time Travel on a Collection With No Pinned Snapshot?

Yes — AT SNAPSHOT and AT TIMESTAMP work on any Iceberg external collection regardless of whether a snapshot was set at creation time.

See Also