--- title: Iceberg Tables description: Operational Insights provides read-only query access to Apache Iceberg tables through external catalogs, enabling unified queries across data lake and operational data without moving data. pubDate: 2026-11-05T15:16:13.118Z meta: component: title: Operational Insights Capella version: "" topic_type: concept antora: editUrl: https://github.com/couchbaselabs/docs-columnar/edit/main/modules/sqlpp/pages/5_ddl_iceberg.adoc xref: xref:analytics:sqlpp:5_ddl_iceberg.adoc[] --- [Consult the llms.txt file for a full list of contents](/llms.txt) [View original HTML](/operational-insights-cloud/sqlpp/5_ddl_iceberg.html) # Iceberg Tables > Operational Insights 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. Operational Insights connects to Iceberg catalogs to query Iceberg tables stored in external object storage — such as Amazon S3 and Google Cloud Storage — using existing links for authentication. To get started, use [CREATE CATALOG](5%5Fddl%5Ficeberg%5Fcatalog.md) to register an Iceberg catalog, then use [CREATE EXTERNAL COLLECTION](5%5Fddl%5Ficeberg%5Ftable.md) to expose individual Iceberg tables for querying. ## [](#iceberg-concepts)Iceberg Concepts * [Catalog](#catalog) * [Namespace](#namespace) * [Data Files](#data-files) ### [](#catalog)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 Operational Insights, a catalog is a named entity registered with [CREATE CATALOG](5%5Fddl%5Ficeberg%5Fcatalog.md). Catalogs are globally unique and do not belong to a database. ### [](#namespace)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](5%5Fddl%5Ficeberg%5Ftable.md). ### [](#data-files)Data Files The data files managed by Iceberg are stored in external object storage. Operational Insights supports Parquet as the Iceberg data file format. ## [](#supported-catalog-types)Supported Catalog Types | Source | Description | Required Link | | ------------------ | -------------------------------------------------------------------------------------------------- | ------------- | | AWS\_GLUE | AWS Glue Data Catalog — the centralized metadata repository in the AWS ecosystem. | S3 link | | AWS\_GLUE\_REST | AWS Glue accessed through the Iceberg REST endpoint, using SigV4-signed credentials. | S3 link | | S3\_TABLES | Amazon S3 Tables — a managed Iceberg table bucket on Amazon S3. | S3 link | | BIGLAKE\_METASTORE | Google BigLake Metastore — Google Cloud-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 through its REST catalog implementation. | HTTP link | | REST | REST-compatible Iceberg catalogs. | HTTP link | ## [](#supported-storage-locations)Supported Storage Locations Iceberg data files can reside in the following object storage locations: * Amazon S3 * Google Cloud Storage (GCS) ## [](#types-mapping)Types Mapping The following table describes the type mapping between Iceberg types and Operational Insights types: | Iceberg Type | Operational Insights 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 Operational Insights. To parse `DECIMAL` values as `DOUBLE`, set `decimal-to-double` to `"true"` in [CREATE EXTERNAL COLLECTION](5%5Fddl%5Ficeberg%5Ftable.md). If `decimal-to-double` is not set, Operational Insights 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 Operational Insights adds native `DECIMAL` support, this property is no longer required. \[2\] Operational Insights 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-to-long` to `"true"` in [CREATE EXTERNAL COLLECTION](5%5Fddl%5Ficeberg%5Ftable.md). \[3\] To return `DATE` as `INTEGER` (epoch days since 1970-01-01), set `date-to-int` to `"true"` in [CREATE EXTERNAL COLLECTION](5%5Fddl%5Ficeberg%5Ftable.md). \[4\] To return `TIME` as `INTEGER` (milliseconds since midnight), set `time-to-int` to `"true"` in [CREATE EXTERNAL COLLECTION](5%5Fddl%5Ficeberg%5Ftable.md). ## [](#query-iceberg-tables)Query Iceberg Tables 1. Create Authentication Links: Create 1 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. 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 S3 link. 2. Register the Iceberg Catalog: Use [CREATE CATALOG](5%5Fddl%5Ficeberg%5Fcatalog.md) to connect Operational Insights to a supported Iceberg catalog. Once registered, the catalog is available globally in Operational Insights. 3. Create an External Collection: Use [CREATE EXTERNAL COLLECTION](5%5Fddl%5Ficeberg%5Ftable.md) to expose an Iceberg table for querying. Once created, the Iceberg table can be queried using SQL++ for Operational Insights Cloud in the same way as any external collection. ## [](#filtration)Filtration When Operational Insights 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, Operational Insights 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 [Cost-Based Optimizer](5b%5Fcbo.md) for further details on query optimization. ## [](#use-time-travel)Use Time Travel Every write to an Iceberg table creates a new snapshot. Operational Insights lets you query any past snapshot of an Iceberg external collection using `AT SNAPSHOT` or `AT TIMESTAMP` in a SQL++ for Operational Insights Cloud 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](5%5Fddl%5Ficeberg%5Ftable.md). ### [](#at-timestamp)AT TIMESTAMP Returns data from the most recent snapshot at or before the specified timestamp. ```SQL++ SELECT * FROM AT TIMESTAMP '' ``` The timestamp must be a string in one of the following formats: * Milliseconds since Unix epoch: `''` * Date: `'yyyy-MM-dd'` * Datetime: `'yyyy-MM-ddTHH:mm:ss'` Examples ```SQL++ SELECT * FROM usersTable AT TIMESTAMP '' SELECT * FROM usersTable AT TIMESTAMP '2022-07-01' SELECT * FROM usersTable AT TIMESTAMP '2022-07-01T13:12:01' ``` ### [](#at-snapshot)AT SNAPSHOT Returns data from a specific snapshot by its ID. ```SQL++ SELECT * FROM AT SNAPSHOT '' ``` Example ```SQL++ SELECT * FROM usersTable AT SNAPSHOT '1339696213265401120' ``` ### [](#list-snapshots)List Snapshots To find available snapshot IDs and timestamps, use the following data source functions or REST endpoints. #### [](#data-source-functions)Data Source Functions List all snapshots for an Iceberg external collection: ```SQL++ SELECT * FROM list_iceberg_snapshots("", "", "") AS x; ``` List all catalogs, namespaces, and tables registered in Operational Insights: ```SQL++ SELECT * FROM list_iceberg_catalogs() AS x; SELECT * FROM list_iceberg_namespaces("") AS x; SELECT * FROM list_iceberg_tables("", "") AS x; ``` #### [](#rest-api)REST API | Endpoint | Description | | ------------------------------------------------------------------------ | -------------------------------------------------------------------- | | GET /api/v1/iceberg/catalog/ | Returns all catalogs registered in Operational Insights. | | 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)FAQ #### [](#can-you-use-both-snapshotid-and-snapshottimestamp-in-the-same-query)Can You Use Both `snapshotId` and `snapshotTimestamp` in the Same Query? No — specify only 1 at a time. Providing both returns an error. #### [](#what-snapshot-does-operational-insights-read-if-no-snapshot-is-specified)What Snapshot Does Operational Insights Read if No Snapshot Is Specified? Operational Insights reads from the latest snapshot of the table. #### [](#whats-the-difference-between-a-query-level-snapshot-and-a-collection-level-snapshot)What's the Difference Between a Query-Level Snapshot and a Collection-Level Snapshot? Setting `snapshotId` or `snapshotTimestamp` in [CREATE EXTERNAL COLLECTION](5%5Fddl%5Ficeberg%5Ftable.md) 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)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)See Also * [Create a Catalog](5%5Fddl%5Ficeberg%5Fcatalog.md) * [Create an Iceberg Table](5%5Fddl%5Ficeberg%5Ftable.md) * [Set Up an External Data Source](../sources/manage-external.md)