cdk-glue-iceberg-table 0.10.2 → 0.12.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/.jsii CHANGED
@@ -9751,7 +9751,7 @@
9751
9751
  },
9752
9752
  "name": "cdk-glue-iceberg-table",
9753
9753
  "readme": {
9754
- "markdown": "# cdk-glue-iceberg-table\n\n[![CI](https://img.shields.io/github/actions/workflow/status/ksco92/arceus/ci.yml?branch=main&label=CI)](https://github.com/ksco92/arceus/actions/workflows/ci.yml)\n[![coverage](https://codecov.io/gh/ksco92/arceus/branch/main/graph/badge.svg)](https://codecov.io/gh/ksco92/arceus)\n[![npm](https://img.shields.io/npm/v/cdk-glue-iceberg-table.svg)](https://www.npmjs.com/package/cdk-glue-iceberg-table)\n[![PyPI](https://img.shields.io/pypi/v/cdk-glue-iceberg-table.svg)](https://pypi.org/project/cdk-glue-iceberg-table/)\n[![Construct Hub](https://img.shields.io/badge/Construct%20Hub-available-blueviolet)](https://constructs.dev/packages/cdk-glue-iceberg-table)\n[![downloads](https://img.shields.io/npm/dw/cdk-glue-iceberg-table.svg)](https://www.npmjs.com/package/cdk-glue-iceberg-table)\n[![license](https://img.shields.io/npm/l/cdk-glue-iceberg-table.svg)](https://github.com/ksco92/arceus/blob/main/LICENSE)\n\n**`cdk-glue-iceberg-table` is an AWS CDK L2 construct to create and\nevolve Apache Iceberg tables in the AWS Glue Data Catalog — schema and\npartition changes that survive CloudFormation updates, via cdk\ndeploy.** It supports Iceberg format version 3 (`variant`, nanosecond\ntimestamps, `geometry` / `geography`, `unknown`). It emits the exact\n`AWS::Glue::Table` / `OpenTableFormatInput` shape, so a single `cdk\ndeploy` creates, evolves, and destroys a table like any other CDK\nresource. No custom resource, no Lambda, no \"`cdk deploy` and then run\nthis SQL by hand\" two-step. Table changes (new columns, renames, drops,\nnew partition fields) land as a reviewed diff in a pull request and\napply through `cdk deploy`.\n\nStatus (October 2026): published on npm (TypeScript/JavaScript) and\nPyPI (Python), pre-1.0, with a public surface guarded by an end-to-end\nconsumer test on every PR plus real-AWS integration suites, including\nones for format version 3. The multi-language packages are generated\nfrom one TypeScript source with [jsii](https://aws.github.io/jsii/)\nand indexed on [Construct\nHub](https://constructs.dev/packages/cdk-glue-iceberg-table).\nDeveloped in the [`ksco92/arceus`](https://github.com/ksco92/arceus)\nmonorepo, which also holds a CDK demo app that dogfoods the construct\nagainst a real AWS account.\n\n### Why this exists\n\nAWS documents the CloudFormation shape for Iceberg tables ([AWS Big\nData blog, December 2025](https://aws.amazon.com/blogs/big-data/create-and-update-apache-iceberg-tables-with-partitions-in-the-aws-glue-data-catalog-using-the-aws-sdk-and-aws-cloudformation)),\nbut raw `AWS::Glue::Table` is a minefield: the CREATE succeeds and the\n*first* `Update` silently strips `table_type=ICEBERG`, after which\nevery Athena query fails with `HIVE_UNSUPPORTED_FORMAT`. The\nmotivating CDK issue is [aws/aws-cdk#29660](https://github.com/aws/aws-cdk/issues/29660);\n[`manmartgarc`'s comment](https://github.com/aws/aws-cdk/issues/29660#issuecomment-4411359248)\ndocuments the only working shape and the silent-corruption traps you\nhit by getting it slightly wrong. This construct implements that\nshape, refuses to emit the unsafe alternatives, and pins Iceberg field\nIDs so schema evolution never orphans existing data. It was the basis\nof an upstream proposal to land an `IcebergTable` in\n`@aws-cdk/aws-glue-alpha` ([aws/aws-cdk#37988](https://github.com/aws/aws-cdk/pull/37988)),\nclosed unmerged in September 2026.\n\n### How it compares\n\n| Approach | Declarative IaC (in the PR) | In-place schema + partition evolution | Prevents the silent-corruption footguns | Typed API + synth-time validation |\n| --- | --- | --- | --- | --- |\n| Raw `CfnTable` (L1) | ✅ | ⚠️ only if you hand-write the exact `OpenTableFormatInput` shape | ❌ you own both footguns | ❌ |\n| CDK custom resource (Lambda + Glue SDK) | ⚠️ via a custom resource you maintain | ⚠️ you write the diff logic | ⚠️ your code's responsibility | ❌ |\n| Spark SQL DDL, or Athena SQL DDL, at job runtime | ❌ imperative, outside the PR | ✅ but outside CloudFormation | n/a | ❌ |\n| **`cdk-glue-iceberg-table`** | ✅ | ✅ via `cdk deploy` | ✅ both prevented by construction | ✅ |\n\n## Install\n\nTypeScript / JavaScript (npm):\n\n```bash\nnpm install cdk-glue-iceberg-table\n```\n\nPython (PyPI):\n\n```bash\npip install cdk-glue-iceberg-table\n```\n\nPeer dependencies (your CDK app must already have these). This\nrelease requires `aws-cdk-lib` 2.273.0 or newer and `constructs`\n10.8.1 or newer, plus Node.js 22.14 or newer for both languages (the\nPython package runs under Node.js through jsii).\n\nFor TypeScript / JavaScript:\n\n```bash\nnpm install aws-cdk-lib@^2.273.0 constructs@^10.8.1\n```\n\nFor Python:\n\n```bash\npip install 'aws-cdk-lib>=2.273.0' 'constructs>=10.8.1'\n```\n\n## Use\n\n### TypeScript\n\n```ts\nimport { Bucket } from 'aws-cdk-lib/aws-s3';\nimport { Database } from 'aws-cdk-lib/aws-glue';\nimport {\n IcebergFormatVersion,\n IcebergTable,\n IcebergType,\n IcebergPartitionTransform,\n} from 'cdk-glue-iceberg-table';\n\nconst bucket = new Bucket(this, 'Warehouse');\nconst db = new Database(this, 'Db', { databaseName: 'analytics' });\n\nnew IcebergTable(this, 'OrdersTable', {\n database: db,\n tableName: 'orders',\n location: `s3://${bucket.bucketName}/analytics/orders/`,\n columns: [\n { name: 'order_id', type: IcebergType.LONG, required: true, id: 1 },\n { name: 'customer_id', type: IcebergType.LONG, required: true, id: 2 },\n { name: 'placed_at', type: IcebergType.TIMESTAMPTZ, required: true, id: 3 },\n ],\n partitionSpec: [\n { sourceColumn: 'placed_at', transform: IcebergPartitionTransform.DAY, fieldId: 1000 },\n { sourceColumn: 'customer_id', transform: IcebergPartitionTransform.bucket(16), fieldId: 1001 },\n ],\n identifierFieldNames: ['order_id'],\n formatVersion: IcebergFormatVersion.V2,\n});\n```\n\n### Python\n\nThe same table in Python — the API mirrors TypeScript with\n`snake_case` props and `PascalCase` types:\n\n```python\nfrom aws_cdk.aws_s3 import Bucket\nfrom aws_cdk.aws_glue import Database\nfrom cdk_glue_iceberg_table import (\n IcebergFormatVersion,\n IcebergTable,\n IcebergType,\n IcebergPartitionTransform,\n)\n\nbucket = Bucket(self, \"Warehouse\")\ndb = Database(self, \"Db\", database_name=\"analytics\")\n\nIcebergTable(self, \"OrdersTable\",\n database=db,\n table_name=\"orders\",\n location=f\"s3://{bucket.bucket_name}/analytics/orders/\",\n columns=[\n {\"name\": \"order_id\", \"type\": IcebergType.LONG, \"required\": True, \"id\": 1},\n {\"name\": \"customer_id\", \"type\": IcebergType.LONG, \"required\": True, \"id\": 2},\n {\"name\": \"placed_at\", \"type\": IcebergType.TIMESTAMPTZ, \"required\": True, \"id\": 3},\n ],\n partition_spec=[\n {\"source_column\": \"placed_at\", \"transform\": IcebergPartitionTransform.DAY, \"field_id\": 1000},\n {\"source_column\": \"customer_id\", \"transform\": IcebergPartitionTransform.bucket(16), \"field_id\": 1001},\n ],\n identifier_field_names=[\"order_id\"],\n format_version=IcebergFormatVersion.V2,\n)\n```\n\nConsumer-facing reference sections:\n\n- [How it compares](#how-it-compares) — `cdk-glue-iceberg-table` vs raw `CfnTable`, custom resources, and runtime SQL DDL.\n- [Using `IcebergTable`](#using-icebergtable) — full API reference with examples.\n- [Format version 3](#format-version-3) — the six v3 types, which engines read them, and the accepted limits.\n- [Two footguns the construct prevents](#two-footguns-the-construct-prevents) — the silent-corruption traps that motivated this construct.\n- [Known limitations](#known-limitations) — what the construct does and doesn't enforce.\n- [FAQ](#faq) — common \"how do I … in CDK / CloudFormation\" questions.\n\n## Exported surface\n\nThe package entry point re-exports the main types you import from\n`cdk-glue-iceberg-table`. In TypeScript / JavaScript the compiled\nsurface lives under `dist/lib/iceberg/` after `npm install`; in Python\nthe same surface is imported from the `cdk_glue_iceberg_table` module\nafter `pip install`:\n\n- **`IcebergTable`** — the L2 construct itself, with `grantRead` / `grantWrite` / `grantReadWrite` and the `fromIcebergTableAttributes(...)` import factory.\n- **`IcebergType`** — primitive types, the v3 constants `UNKNOWN`, `TIMESTAMP_NS`, `TIMESTAMPTZ_NS`, and `VARIANT`, and the `list` / `map` / `struct` / `decimal` / `fixed` / `geometry(crs?)` / `geography(crs?, algorithm?)` factories. Renders to the string Glue's `IcebergStructField.type` expects.\n- **`IcebergPartitionTransform`** — identity / `bucket(N)` / `truncate(W)` / year / month / day / hour / void. Each transform validates against the source column type at synth time.\n- **`IcebergDataFormat`** (parquet/orc/avro, default parquet), **`IcebergFormatVersion`** (v1/v2/v3, required — set explicitly per table; Athena cannot query v3 tables), **`IcebergSortDirection`**, **`IcebergNullOrder`**, **`IcebergEdgeAlgorithm`** (`SPHERICAL`, `VINCENTY`, `THOMAS`, `ANDOYER`, `KARNEY`; the second argument of `IcebergType.geography`), plus a `tableProperties` validator that catches misconfigured properties before they leave your machine (wrong codec for the chosen format, `merge-on-read` on a v1 table, non-positive numeric values, …).\n\n## Using `IcebergTable`\n\nA minimal table:\n\n```typescript\nimport {\n Bucket,\n} from 'aws-cdk-lib/aws-s3';\nimport {\n Database,\n} from 'aws-cdk-lib/aws-glue';\nimport {\n IcebergFormatVersion,\n IcebergTable,\n IcebergType,\n} from 'cdk-glue-iceberg-table';\n\nconst bucket = new Bucket(this, 'Warehouse');\n\nconst db = new Database(this, 'Db', {\n databaseName: 'analytics',\n});\n\nnew IcebergTable(this, 'Users', {\n database: db,\n tableName: 'users',\n columns: [\n {\n name: 'user_id',\n type: IcebergType.LONG,\n required: true,\n id: 1,\n },\n {\n name: 'email',\n type: IcebergType.STRING,\n required: true,\n id: 2,\n },\n {\n name: 'signed_up_at',\n type: IcebergType.TIMESTAMPTZ,\n required: true,\n id: 3,\n },\n ],\n location: `s3://${bucket.bucketName}/analytics/users/`,\n formatVersion: IcebergFormatVersion.V2,\n});\n```\n\nEvery top-level column must declare an `id`: a stable, unique,\npositive integer you pick once and never reuse or reassign. Because\nIceberg data files reference fields by id rather than by name, a fixed\nid is what lets you add, rename, and drop columns across deploys\nwithout corrupting old data — see\n[How do I evolve an Iceberg table schema](#how-do-i-evolve-an-iceberg-table-schema-add-rename-or-drop-a-column-in-cloudformation).\nOnce a column is dropped, leave its id retired; never hand it to a new\ncolumn. (Nested struct/list/map field ids are assigned automatically\nabove the highest top-level id — only top-level column ids are\ncaller-provided.)\n\nA table that exercises most of the surface (partitions, sort order,\nnested types, identifier fields, table properties, removal policy):\n\n```typescript\nimport {\n RemovalPolicy,\n} from 'aws-cdk-lib';\nimport {\n Database,\n} from 'aws-cdk-lib/aws-glue';\nimport {\n IcebergDataFormat,\n IcebergFormatVersion,\n IcebergNullOrder,\n IcebergPartitionTransform,\n IcebergSortDirection,\n IcebergTable,\n IcebergType,\n} from 'cdk-glue-iceberg-table';\n\nnew IcebergTable(this, 'OrdersTable', {\n database: db,\n tableName: 'orders',\n comment: 'Demo Iceberg orders table — exercises partitions, sort order, and merge-on-read.',\n columns: [\n {\n name: 'order_id',\n type: IcebergType.LONG,\n required: true,\n id: 1,\n },\n {\n name: 'customer_id',\n type: IcebergType.LONG,\n required: true,\n id: 2,\n },\n {\n name: 'order_amount',\n type: IcebergType.decimal(12, 2),\n required: true,\n id: 3,\n },\n {\n name: 'currency',\n type: IcebergType.STRING,\n required: true,\n id: 4,\n },\n {\n name: 'placed_at',\n type: IcebergType.TIMESTAMPTZ,\n required: true,\n id: 5,\n },\n {\n name: 'tags',\n type: IcebergType.list(IcebergType.STRING),\n id: 6,\n },\n {\n name: 'shipping_address',\n type: IcebergType.struct([\n {\n name: 'line1',\n type: IcebergType.STRING,\n required: true,\n },\n {\n name: 'city',\n type: IcebergType.STRING,\n required: true,\n },\n {\n name: 'country',\n type: IcebergType.STRING,\n required: true,\n },\n {\n name: 'postal_code',\n type: IcebergType.STRING,\n },\n ]),\n id: 7,\n },\n {\n name: 'metadata',\n type: IcebergType.map(IcebergType.STRING, IcebergType.STRING, false),\n id: 8,\n },\n ],\n location: `s3://${bucket.bucketName}/analytics/orders/`,\n partitionSpec: [\n {\n sourceColumn: 'placed_at',\n transform: IcebergPartitionTransform.DAY,\n fieldId: 1000,\n },\n {\n sourceColumn: 'customer_id',\n transform: IcebergPartitionTransform.bucket(16),\n fieldId: 1001,\n },\n ],\n sortOrder: [\n {\n sourceColumn: 'placed_at',\n direction: IcebergSortDirection.ASC,\n nullOrder: IcebergNullOrder.NULLS_LAST,\n },\n {\n sourceColumn: 'order_id',\n direction: IcebergSortDirection.ASC,\n },\n ],\n identifierFieldNames: [\n 'order_id',\n ],\n dataFormat: IcebergDataFormat.PARQUET,\n formatVersion: IcebergFormatVersion.V2,\n tableProperties: {\n 'write.parquet.compression-codec': 'zstd',\n 'write.delete.mode': 'merge-on-read',\n 'write.update.mode': 'merge-on-read',\n 'write.merge.mode': 'merge-on-read',\n 'write.target-file-size-bytes': '134217728',\n 'history.expire.min-snapshots-to-keep': '5',\n 'gc.enabled': 'true',\n },\n removalPolicy: RemovalPolicy.DESTROY,\n});\n```\n\nEach partition field also pins a `fieldId`: an integer of 1000 or\nabove (the Iceberg spec reserves lower ids for schema columns), unique\nacross the table's entire partition-spec history. The discipline is\nthe inverse of the column-id rule. A column keeps its id forever; a\npartition field keeps its id only while it stays untouched. Change\nanything about a field — swap `month` for `day`, point it at a\ndifferent source column — and it becomes a *new* field that needs a\nfresh, never-before-used id, while the old id retires with the old\nspec. Reusing a retired id (or reassigning an id to a different field)\nproduces a table that Athena still reads but Spark and Trino reject\nwith `ValidationException: Conflicting partition fields`.\n\nThe resulting Iceberg `metadata.json` for this table contains every\nfeature you set:\n\n```json\n{\n \"format-version\": 2,\n \"table-uuid\": \"39a948f9-...\",\n \"current-schema-id\": 0,\n \"schemas\": [\n {\n \"schema-id\": 0,\n \"identifier-field-ids\": [1],\n \"fields\": [\n { \"id\": 1, \"name\": \"order_id\", \"required\": true, \"type\": \"long\" },\n { \"id\": 2, \"name\": \"customer_id\", \"required\": true, \"type\": \"long\" },\n { \"id\": 3, \"name\": \"order_amount\", \"required\": true, \"type\": \"decimal(12, 2)\" },\n { \"id\": 4, \"name\": \"currency\", \"required\": true, \"type\": \"string\" },\n { \"id\": 5, \"name\": \"placed_at\", \"required\": true, \"type\": \"timestamptz\" },\n { \"id\": 6, \"name\": \"tags\", \"required\": false,\n \"type\": { \"type\": \"list\", \"element-id\": 9, \"element\": \"string\", \"element-required\": true } },\n { \"id\": 7, \"name\": \"shipping_address\", \"required\": false,\n \"type\": { \"type\": \"struct\", \"fields\": [\n { \"id\": 10, \"name\": \"line1\", \"required\": true, \"type\": \"string\" },\n { \"id\": 11, \"name\": \"city\", \"required\": true, \"type\": \"string\" },\n { \"id\": 12, \"name\": \"country\", \"required\": true, \"type\": \"string\" },\n { \"id\": 13, \"name\": \"postal_code\", \"required\": false, \"type\": \"string\" }\n ] } },\n { \"id\": 8, \"name\": \"metadata\", \"required\": false,\n \"type\": { \"type\": \"map\", \"key-id\": 14, \"key\": \"string\", \"value-id\": 15,\n \"value-required\": false, \"value\": \"string\" } }\n ]\n }\n ],\n \"partition-specs\": [\n { \"spec-id\": 0, \"fields\": [\n { \"name\": \"placed_at_day\", \"transform\": \"day\", \"source-id\": 5, \"field-id\": 1000 },\n { \"name\": \"customer_id_bucket\", \"transform\": \"bucket[16]\", \"source-id\": 2, \"field-id\": 1001 }\n ]}\n ],\n \"sort-orders\": [\n { \"order-id\": 1, \"fields\": [\n { \"transform\": \"identity\", \"source-id\": 5, \"direction\": \"asc\", \"null-order\": \"nulls-last\" },\n { \"transform\": \"identity\", \"source-id\": 1, \"direction\": \"asc\", \"null-order\": \"nulls-last\" }\n ]}\n ],\n \"properties\": {\n \"format-version\": \"2\",\n \"write.format.default\": \"parquet\",\n \"write.parquet.compression-codec\": \"zstd\",\n \"write.merge.mode\": \"merge-on-read\",\n \"write.update.mode\": \"merge-on-read\",\n \"write.delete.mode\": \"merge-on-read\",\n \"write.target-file-size-bytes\": \"134217728\",\n \"history.expire.min-snapshots-to-keep\": \"5\",\n \"gc.enabled\": \"true\",\n \"comment\": \"Demo Iceberg orders table — exercises partitions, sort order, and merge-on-read.\"\n }\n}\n```\n\n### Format version 3\n\nSet `formatVersion: IcebergFormatVersion.V3` to create a v3 table. The\nsix v3 types (below) are only accepted on a V3 table, at any nesting\ndepth: inside a struct, as a list element, or as a map key or value.\nSynth fails on a V1 or V2 table that uses one.\n\n```typescript\nimport {\n IcebergEdgeAlgorithm,\n IcebergFormatVersion,\n IcebergTable,\n IcebergType,\n} from 'cdk-glue-iceberg-table';\n\nnew IcebergTable(this, 'Events', {\n database: db,\n tableName: 'events',\n location: `s3://${bucket.bucketName}/analytics/events/`,\n columns: [\n { name: 'occurred_at', type: IcebergType.TIMESTAMP_NS, id: 1 },\n { name: 'payload', type: IcebergType.VARIANT, id: 2 },\n {\n name: 'origin',\n type: IcebergType.geography('OGC:CRS84', IcebergEdgeAlgorithm.SPHERICAL),\n id: 3,\n },\n ],\n formatVersion: IcebergFormatVersion.V3,\n});\n```\n\nThe same table in Python:\n\n```python\nfrom cdk_glue_iceberg_table import (\n IcebergEdgeAlgorithm,\n IcebergFormatVersion,\n IcebergTable,\n IcebergType,\n)\n\nIcebergTable(self, \"Events\",\n database=db,\n table_name=\"events\",\n location=f\"s3://{bucket.bucket_name}/analytics/events/\",\n columns=[\n {\"name\": \"occurred_at\", \"type\": IcebergType.TIMESTAMP_NS, \"id\": 1},\n {\"name\": \"payload\", \"type\": IcebergType.VARIANT, \"id\": 2},\n {\n \"name\": \"origin\",\n \"type\": IcebergType.geography(\"OGC:CRS84\", IcebergEdgeAlgorithm.SPHERICAL),\n \"id\": 3,\n },\n ],\n format_version=IcebergFormatVersion.V3,\n)\n```\n\nThis table has a `timestamp_ns` column; see [Known limitations](#known-limitations)\nbefore reading it from upstream Spark.\n\nThe v3 types, with the rules `cdk synth` enforces:\n\n| Type | Factory | Rendered string | Partition and identifier rules |\n| --- | --- | --- | --- |\n| unknown | `IcebergType.UNKNOWN` | `unknown` | Must be optional, as a column, list element, or map value; never a map key. Partition source only with `void`. Not an identifier field. |\n| timestamp with nanoseconds | `IcebergType.TIMESTAMP_NS` | `timestamp_ns` | `identity`, `year`, `month`, `day`, `hour`, `bucket(N)`, `void`; not `truncate(W)`. Allowed as an identifier field. |\n| timestamptz with nanoseconds | `IcebergType.TIMESTAMPTZ_NS` | `timestamptz_ns` | Same as `timestamp_ns`. |\n| variant | `IcebergType.VARIANT` | `variant` | Never a partition or sort source, `void` included. Not an identifier field. |\n| geometry | `IcebergType.geometry(crs?)` | `geometry`, or `geometry(<crs>)` when a CRS is given | Partition source only with `void`. Not an identifier field. |\n| geography | `IcebergType.geography(crs?, algorithm?)` | `geography`, `geography(<crs>)`, or `geography(<crs>, <algorithm>)` when an algorithm is given, such as `geography(OGC:CRS84, spherical)` | Same as `geometry`. |\n\nA geometry or geography `crs` is an identifier such as `OGC:CRS84` or\n`EPSG:3857`; whitespace, parentheses, braces, and commas are rejected.\nWhen `algorithm` is set without a `crs`, the rendered string spells out\n`OGC:CRS84`.\n\nWhich engines read a v3 table created by the construct:\n\n| Engine | v3 tables | Notes |\n| --- | --- | --- |\n| Spark 4.1 + Iceberg 1.12 (the integration-test runner) | Yes | Reads and writes tables the construct creates, including deletion vectors, row lineage, `variant`, `unknown`, and `geometry` / `geography`, except tables with nanosecond-timestamp columns or a geometry CRS other than `OGC:CRS84` (checked by `scripts/spark/verify_v3_dml.py`; details in [Known limitations](#known-limitations)). |\n| AWS Glue 6.0 | Documented | The [AWS Glue versions](https://docs.aws.amazon.com/glue/latest/dg/release-notes.html) page lists \"Iceberg format version 3 with VARIANT data type, deletion vectors, row lineage tracking, nanosecond timestamps, and geo types\". The integration suites do not run on Glue 6.0. |\n| Amazon EMR Spark 8.1.0 (Spark 4.1.1, Iceberg 1.11.0-amzn-0) | Documented | The [emr-spark-8.1.0 release notes](https://docs.aws.amazon.com/emr/latest/ReleaseGuide/emr-spark810-release.html) state \"Amazon EMR Spark 8.1.0 extends Iceberg v3 spec support for Spark workloads\". The integration suites do not run on EMR 8.1. |\n| Athena SQL | No | The [Athena Iceberg page](https://docs.aws.amazon.com/athena/latest/ug/querying-iceberg.html) states \"Athena only creates and operates on Iceberg v2 tables.\" |\n\n### Granting access\n\n```typescript\ntable.grantRead(role); // Glue read + S3 read on the table's prefix\ntable.grantWrite(role); // Glue write + S3 write\ntable.grantReadWrite(role);\n```\n\nThe `grant*` helpers issue **IAM grants only**. Under Lake Formation\nyou still add the matching `SELECT` / `INSERT` / `DELETE` LF grants on\ntop of the construct's IAM grants for Athena queries to succeed.\n\n### Importing an existing table\n\n```typescript\nconst existing = IcebergTable.fromIcebergTableAttributes(this, 'Orders', {\n database: db,\n tableName: 'orders',\n location: 's3://my-bucket/analytics/orders/',\n});\nexisting.grantRead(role);\n```\n\n### Evolving schema and partitions\n\nChange the `columns` array (or `partitionSpec`) and run `cdk deploy`\nagain. The construct passes the new schema to Glue's `UpdateTable`,\nwhich writes a new `metadata.json` with a new `schema-id`; existing\ndata files stay readable because each column's `id` is pinned and\nnever reused. Adds, renames (same `id`, new `name`), and drops all\nflow through `cdk deploy` alone — no out-of-band SQL DDL.\n\nPartition evolution flows the same way, with one extra rule on\n`fieldId`: a changed partition field is a new partition field. To move\na table from `month(placed_at)` to `day(placed_at)`, drop the month\nentry and add a day entry under a fresh `fieldId` — never recycle the\nmonth field's id:\n\n```typescript\npartitionSpec: [\n // was: { sourceColumn: 'placed_at', transform: IcebergPartitionTransform.MONTH, fieldId: 1000 },\n {\n sourceColumn: 'placed_at',\n transform: IcebergPartitionTransform.DAY,\n fieldId: 1001,\n },\n],\n```\n\nOld data files written under the month spec stay readable; new writes\npartition by day. Reusing `1000` for the day field instead corrupts\nthe spec history for strict engines (Spark, Trino) while Athena keeps\nworking — the failure only surfaces at Spark runtime.\n\n### Inserting and querying\n\n```sql\n-- INSERT into the orders table\nINSERT INTO sample_database.orders VALUES\n (1001, 5001, DECIMAL '149.99', 'USD',\n TIMESTAMP '2026-05-20 09:15:00 UTC',\n ARRAY['holiday-promo','first-order'],\n CAST(ROW('1 Infinite Loop','Cupertino','US','95014')\n AS ROW(line1 VARCHAR,city VARCHAR,country VARCHAR,postal_code VARCHAR)),\n MAP(ARRAY['channel','utm'], ARRAY['web','google'])),\n -- ... more rows\n;\n\n-- merge-on-read DELETE (only legal because we chose v2 + merge-on-read mode)\nDELETE FROM sample_database.orders WHERE order_id = 1003;\n\n-- merge-on-read UPDATE\nUPDATE sample_database.orders SET currency = 'GBP' WHERE customer_id = 5002;\n\n-- SELECT\nSELECT customer_id, SUM(order_amount) AS total\n FROM sample_database.orders\n GROUP BY 1\n ORDER BY 2 DESC;\n```\n\n## Two footguns the construct prevents\n\n### Footgun #1 — schema under `storageDescriptor.columns`\n\nThe CREATE succeeds but the first UPDATE silently strips\n`table_type=ICEBERG` from the table's Glue parameters, and Athena\nqueries after that fail with `HIVE_UNSUPPORTED_FORMAT`.\n\n```typescript\n// DON'T DO THIS — what most StackOverflow / re:Post examples show\nnew CfnTable(this, 'OrdersBad', {\n catalogId: this.account,\n databaseName: 'analytics',\n tableInput: {\n name: 'orders',\n tableType: 'EXTERNAL_TABLE',\n parameters: {\n table_type: 'ICEBERG',\n },\n storageDescriptor: {\n location: 's3://.../orders/',\n columns: [\n /* ... */\n ],\n },\n },\n openTableFormatInput: {\n icebergInput: {\n metadataOperation: 'CREATE',\n version: '2',\n },\n },\n});\n```\n\n`IcebergTable` instead always emits schema/partitions/sort/properties\nunder `openTableFormatInput.icebergInput.icebergTableInput`, never\nunder `storageDescriptor`.\n\n### Footgun #2 — `tableInput` co-present with `openTableFormatInput`\n\nEven setting just `tableInput: { name: 'foo' }` next to\n`openTableFormatInput` returns\n`\"Table metadata is expected only via TableInput or via IcebergTableInputProperties inside OpenTableFormatInput\"`.\nThe construct never emits `tableInput`; the table-level comment goes\ninto `tableProperties['comment']`, which lives inside\n`icebergTableInput.properties`.\n\n(There is a third footgun, field-id reuse after a column drop, that\nthe construct does **not** prevent. See the next section.)\n\n## Known limitations\n\n- **Field-id reuse is not detected across deploys.** If you drop a column with `id = 5` and then add a different column with `id = 5` in a later deploy, Glue accepts the UPDATE and Iceberg's metadata silently violates the \"never reuse a retired id\" invariant. Readers projecting old snapshots will surface deleted data under the new field's name. The construct enforces uniqueness **within one deploy** (`duplicate column id N` validator), but it doesn't compare against the live table state. The safe workflow is to always pin `id` explicitly and treat dropped ids as retired forever; never let CDK reassign an id that has ever been used.\n- **Partition field-id reuse is not detected across deploys either.** The same live-state blindness applies to partition `fieldId`s: the construct validates them within one deploy (integer >= 1000, unique in the spec), but it cannot tell that the id you pinned already appeared in an earlier spec of the deployed table. The invariant partition ids must uphold is stricter than the column one — unique across the table's **entire spec history**, so a changed field (different transform or source column) must take a fresh id rather than keep its old one. Violate it and strict engines (Spark, Trino) reject the table with `Conflicting partition fields` while Athena keeps answering, masking the break until Spark runtime. The safe workflow: treat every id that has ever appeared in any spec as retired, and allocate new fields the next never-used id.\n- **`last-partition-id` is written by Glue, not by the construct.** The construct supplies the spec's field ids; Glue's `UpdateTable` computes the table's `last-partition-id` counter when it writes the new metadata. The repo's integration test asserts the counter keeps up with the highest supplied field id after a partition evolution, but engines that later evolve the spec themselves (e.g. Spark `ALTER TABLE … ADD PARTITION FIELD`) allocate from that counter — if you mix CDK-managed and engine-managed partition evolution, verify the counter in `metadata.json` before trusting engine-side changes.\n- **CREATE-only metadata operation.** The CFN `IcebergInput.metadataOperation` only accepts `CREATE`; the construct always emits that. Subsequent deploys use Glue's normal `UpdateTable` path, which writes new Iceberg metadata in-place.\n- **Format version is immutable after CREATE.** CloudFormation does not change an existing table's format version, so changing `formatVersion` on a table no engine has upgraded means destroy + recreate. An engine can upgrade a v2 table to v3 in place with `ALTER TABLE ... SET TBLPROPERTIES ('format-version' = '3')`; after that, set `formatVersion` to `V3` so the next deploy declares the version the table already has.\n- **`merge-on-read` requires v2 or later.** The construct rejects `write.{delete,update,merge}.mode = merge-on-read` on a v1 table at synth time.\n- **Column defaults are not available.** Iceberg v3 `initial-default` and `write-default` cannot be declared through CloudFormation: the `AWS::Glue::Table` resource schema has no `InitialDefault` or `WriteDefault` property. Revisit when that schema gains the two properties.\n- **Nanosecond timestamps are catalog-only for upstream Spark 4.1.** A table with any `timestamp_ns` or `timestamptz_ns` column fails to open in upstream Spark 4.1 with Iceberg 1.12. The integration suite for these columns asserts from `metadata.json` only. The [engine matrix](#format-version-3) lists the engines that document support.\n- **Geometry CRS other than `OGC:CRS84` is catalog-only for upstream Spark 4.1.** Spark 4.1 accepts `OGC:CRS84`, or bare `geometry`, as the geometry CRS; a table declaring another CRS, such as `EPSG:3857`, cannot be read there.\n- **Athena DDL features that don't surface through CFN** (e.g. `ALTER TABLE WRITE ORDERED BY`, `ALTER TABLE … SET LOCATION`, `bucketed_by` / `bucket_count` Hive clauses) are not exposed. Use `IcebergPartitionTransform.bucket(N)` instead of Hive bucketing.\n- **Dropping a partition column requires a `void` intermediate per the Iceberg spec**, and the CFN `OpenTableFormatInput` cannot express that. The construct accepts the change, but Athena queries against the result will fail with `Type cannot be null`. The safe pattern is to drop partitions that source from a column while keeping that column in the schema, and only drop a column once it is no longer partitioning anything.\n\n## FAQ\n\n### How do I create an Apache Iceberg table in AWS CDK?\n\nInstall `cdk-glue-iceberg-table`, then declare an `IcebergTable` with a\ndatabase, a column list, and an S3 `location` — see [Use](#use).\n`cdk deploy` creates the Glue Data Catalog table and writes the\nIceberg `metadata.json` under your S3 prefix. No custom resource or\nLambda is involved; it is a plain `AWS::Glue::Table` in your\nCloudFormation template.\n\n### How do I evolve an Iceberg table schema (add, rename, or drop a column) in CloudFormation?\n\nChange the `columns` array and run `cdk deploy` again. The construct\npasses the new schema to Glue's `UpdateTable`, which writes a new\n`metadata.json` with a new `schema-id`; existing data files stay\nreadable because each column's `id` is pinned and never reused.\nPartition changes work the same way, except a changed partition field\ntakes a fresh `fieldId` instead of keeping its old one. See [Evolving\nschema and partitions](#evolving-schema-and-partitions).\n\n### Does CloudFormation support Iceberg tables natively?\n\nYes, through `AWS::Glue::Table` with `OpenTableFormatInput.IcebergInput`,\ndocumented by AWS in [December 2025](https://aws.amazon.com/blogs/big-data/create-and-update-apache-iceberg-tables-with-partitions-in-the-aws-glue-data-catalog-using-the-aws-sdk-and-aws-cloudformation).\nThe catch is that the raw shape corrupts the table on the first\n`Update` if you place schema under `storageDescriptor.columns` or set\n`tableInput` alongside `openTableFormatInput`. This construct only ever\nemits the safe shape and gives you no way to express the unsafe ones.\nSee [Two footguns the construct prevents](#two-footguns-the-construct-prevents).\n\n### What is the difference between cdk-glue-iceberg-table and a raw CfnTable?\n\nA raw `CfnTable` makes you hand-write the `OpenTableFormatInput` JSON\nand own both silent-corruption footguns. `cdk-glue-iceberg-table` gives\nyou a typed `IcebergType` / `IcebergPartitionTransform` API,\nsynth-time validation (partition transforms checked against column\ntypes, format/version mismatches caught before deploy), pinned field\nIDs for safe evolution, and `grantRead` / `grantWrite` helpers. See\n[How it compares](#how-it-compares).\n\n### How do I create a partitioned Iceberg table in CDK?\n\nPass a `partitionSpec` of `IcebergPartitionTransform` entries —\n`identity`, `bucket(N)`, `truncate(W)`, `year`, `month`, `day`, `hour`,\nor `void` — each pinned to a `fieldId` of 1000 or above. Transforms are\nvalidated against their source column's type at synth time. See\n[Using `IcebergTable`](#using-icebergtable).\n\n### Does it work with Athena and Lake Formation?\n\nYes for v2 tables, no for v3 (see the engine matrix in [Format\nversion 3](#format-version-3)). On v2, Athena reads and writes,\nincluding merge-on-read `INSERT` / `UPDATE` / `DELETE` / `MERGE`, time\ntravel, `OPTIMIZE`, and `VACUUM`. The demo app in the\n[`arceus`](https://github.com/ksco92/arceus) repo registers its tables\nwith Lake Formation and exercises the same operations through Spark in\nits integration suite. The construct's `grant*` helpers issue IAM\ngrants; under Lake Formation you still add the matching `SELECT` /\n`INSERT` LF grants. See [Granting access](#granting-access).\n\n### Can I use Iceberg v2 merge-on-read (row-level UPDATE and DELETE)?\n\nYes — set `formatVersion: IcebergFormatVersion.V2` and the\n`write.{delete,update,merge}.mode = merge-on-read` table properties.\nThe construct rejects merge-on-read on a v1 table at synth time.\n\n### Can I create an Iceberg v3 table?\n\nYes. Set `formatVersion: IcebergFormatVersion.V3`; see [Format\nversion 3](#format-version-3) for the types, the engine matrix and the\nlimits.\n\n## Contributing\n\nDevelopment, the monorepo layout, and the demo app live in [CONTRIBUTING.md](https://github.com/ksco92/arceus/blob/main/CONTRIBUTING.md).\n\n## License\n\n[MIT](https://github.com/ksco92/arceus/blob/main/LICENSE).\n"
9754
+ "markdown": "# cdk-glue-iceberg-table\n\n[![CI](https://img.shields.io/github/actions/workflow/status/ksco92/arceus/ci.yml?branch=main&label=CI)](https://github.com/ksco92/arceus/actions/workflows/ci.yml)\n[![coverage](https://codecov.io/gh/ksco92/arceus/branch/main/graph/badge.svg)](https://codecov.io/gh/ksco92/arceus)\n[![npm](https://img.shields.io/npm/v/cdk-glue-iceberg-table.svg)](https://www.npmjs.com/package/cdk-glue-iceberg-table)\n[![PyPI](https://img.shields.io/pypi/v/cdk-glue-iceberg-table.svg)](https://pypi.org/project/cdk-glue-iceberg-table/)\n[![Construct Hub](https://img.shields.io/badge/Construct%20Hub-available-blueviolet)](https://constructs.dev/packages/cdk-glue-iceberg-table)\n[![downloads](https://img.shields.io/npm/dw/cdk-glue-iceberg-table.svg)](https://www.npmjs.com/package/cdk-glue-iceberg-table)\n[![license](https://img.shields.io/npm/l/cdk-glue-iceberg-table.svg)](https://github.com/ksco92/arceus/blob/main/LICENSE)\n\n**`cdk-glue-iceberg-table` is an AWS CDK L2 construct to create and\nevolve Apache Iceberg tables in the AWS Glue Data Catalog — schema and\npartition changes that survive CloudFormation updates, via cdk\ndeploy.** It supports Iceberg format version 3 (`variant`, nanosecond\ntimestamps, `geometry` / `geography`, `unknown`). It emits the exact\n`AWS::Glue::Table` / `OpenTableFormatInput` shape, so a single `cdk\ndeploy` creates, evolves, and destroys a table like any other CDK\nresource. No custom resource, no Lambda, no \"`cdk deploy` and then run\nthis SQL by hand\" two-step. Table changes (new columns, renames, drops,\nnew partition fields) land as a reviewed diff in a pull request and\napply through `cdk deploy`.\n\nStatus (October 2026): published on npm (TypeScript/JavaScript) and\nPyPI (Python), pre-1.0, with a public surface guarded by an end-to-end\nconsumer test on every PR plus real-AWS integration suites, including\nones for format version 3. The multi-language packages are generated\nfrom one TypeScript source with [jsii](https://aws.github.io/jsii/)\nand indexed on [Construct\nHub](https://constructs.dev/packages/cdk-glue-iceberg-table).\nDeveloped in the [`ksco92/arceus`](https://github.com/ksco92/arceus)\nmonorepo, which also holds a CDK demo app that dogfoods the construct\nagainst a real AWS account.\n\n### Why this exists\n\nAWS documents the CloudFormation shape for Iceberg tables ([AWS Big\nData blog, December 2025](https://aws.amazon.com/blogs/big-data/create-and-update-apache-iceberg-tables-with-partitions-in-the-aws-glue-data-catalog-using-the-aws-sdk-and-aws-cloudformation)),\nbut raw `AWS::Glue::Table` is a minefield: the CREATE succeeds and the\n*first* `Update` silently strips `table_type=ICEBERG`, after which\nevery Athena query fails with `HIVE_UNSUPPORTED_FORMAT`. The\nmotivating CDK issue is [aws/aws-cdk#29660](https://github.com/aws/aws-cdk/issues/29660);\n[`manmartgarc`'s comment](https://github.com/aws/aws-cdk/issues/29660#issuecomment-4411359248)\ndocuments the only working shape and the silent-corruption traps you\nhit by getting it slightly wrong. This construct implements that\nshape, refuses to emit the unsafe alternatives, and pins Iceberg field\nIDs so schema evolution never orphans existing data. It was the basis\nof an upstream proposal to land an `IcebergTable` in\n`@aws-cdk/aws-glue-alpha` ([aws/aws-cdk#37988](https://github.com/aws/aws-cdk/pull/37988)),\nclosed unmerged in September 2026.\n\n### How it compares\n\n| Approach | Declarative IaC (in the PR) | In-place schema + partition evolution | Prevents the silent-corruption footguns | Typed API + synth-time validation |\n| --- | --- | --- | --- | --- |\n| Raw `CfnTable` (L1) | ✅ | ⚠️ only if you hand-write the exact `OpenTableFormatInput` shape | ❌ you own both footguns | ❌ |\n| CDK custom resource (Lambda + Glue SDK) | ⚠️ via a custom resource you maintain | ⚠️ you write the diff logic | ⚠️ your code's responsibility | ❌ |\n| Spark SQL DDL, or Athena SQL DDL, at job runtime | ❌ imperative, outside the PR | ✅ but outside CloudFormation | n/a | ❌ |\n| **`cdk-glue-iceberg-table`** | ✅ | ✅ via `cdk deploy` | ✅ both prevented by construction | ✅ |\n\n## Install\n\nTypeScript / JavaScript (npm):\n\n```bash\nnpm install cdk-glue-iceberg-table\n```\n\nPython (PyPI):\n\n```bash\npip install cdk-glue-iceberg-table\n```\n\nPeer dependencies (your CDK app must already have these). This\nrelease requires `aws-cdk-lib` 2.273.0 or newer and `constructs`\n10.8.1 or newer, plus Node.js 22.14 or newer for both languages (the\nPython package runs under Node.js through jsii).\n\nFor TypeScript / JavaScript:\n\n```bash\nnpm install aws-cdk-lib@^2.273.0 constructs@^10.8.1\n```\n\nFor Python:\n\n```bash\npip install 'aws-cdk-lib>=2.273.0' 'constructs>=10.8.1'\n```\n\n## Use\n\n### TypeScript\n\n```ts\nimport { Bucket } from 'aws-cdk-lib/aws-s3';\nimport { Database } from 'aws-cdk-lib/aws-glue';\nimport {\n IcebergFormatVersion,\n IcebergTable,\n IcebergType,\n IcebergPartitionTransform,\n} from 'cdk-glue-iceberg-table';\n\nconst bucket = new Bucket(this, 'Warehouse');\nconst db = new Database(this, 'Db', { databaseName: 'analytics' });\n\nnew IcebergTable(this, 'OrdersTable', {\n database: db,\n tableName: 'orders',\n location: `s3://${bucket.bucketName}/analytics/orders/`,\n columns: [\n { name: 'order_id', type: IcebergType.LONG, required: true, id: 1 },\n { name: 'customer_id', type: IcebergType.LONG, required: true, id: 2 },\n { name: 'placed_at', type: IcebergType.TIMESTAMPTZ, required: true, id: 3 },\n ],\n partitionSpec: [\n { sourceColumn: 'placed_at', transform: IcebergPartitionTransform.DAY, fieldId: 1000 },\n { sourceColumn: 'customer_id', transform: IcebergPartitionTransform.bucket(16), fieldId: 1001 },\n ],\n identifierFieldNames: ['order_id'],\n formatVersion: IcebergFormatVersion.V2,\n});\n```\n\n### Python\n\nThe same table in Python — the API mirrors TypeScript with\n`snake_case` props and `PascalCase` types:\n\n```python\nfrom aws_cdk.aws_s3 import Bucket\nfrom aws_cdk.aws_glue import Database\nfrom cdk_glue_iceberg_table import (\n IcebergFormatVersion,\n IcebergTable,\n IcebergType,\n IcebergPartitionTransform,\n)\n\nbucket = Bucket(self, \"Warehouse\")\ndb = Database(self, \"Db\", database_name=\"analytics\")\n\nIcebergTable(self, \"OrdersTable\",\n database=db,\n table_name=\"orders\",\n location=f\"s3://{bucket.bucket_name}/analytics/orders/\",\n columns=[\n {\"name\": \"order_id\", \"type\": IcebergType.LONG, \"required\": True, \"id\": 1},\n {\"name\": \"customer_id\", \"type\": IcebergType.LONG, \"required\": True, \"id\": 2},\n {\"name\": \"placed_at\", \"type\": IcebergType.TIMESTAMPTZ, \"required\": True, \"id\": 3},\n ],\n partition_spec=[\n {\"source_column\": \"placed_at\", \"transform\": IcebergPartitionTransform.DAY, \"field_id\": 1000},\n {\"source_column\": \"customer_id\", \"transform\": IcebergPartitionTransform.bucket(16), \"field_id\": 1001},\n ],\n identifier_field_names=[\"order_id\"],\n format_version=IcebergFormatVersion.V2,\n)\n```\n\nConsumer-facing reference sections:\n\n- [How it compares](#how-it-compares) — `cdk-glue-iceberg-table` vs raw `CfnTable`, custom resources, and runtime SQL DDL.\n- [Using `IcebergTable`](#using-icebergtable) — full API reference with examples.\n- [Format version 3](#format-version-3) — the six v3 types, which engines read them, and the accepted limits.\n- [Two footguns the construct prevents](#two-footguns-the-construct-prevents) — the silent-corruption traps that motivated this construct.\n- [Known limitations](#known-limitations) — what the construct does and doesn't enforce.\n- [FAQ](#faq) — common \"how do I … in CDK / CloudFormation\" questions.\n\n## Exported surface\n\nThe package entry point re-exports the main types you import from\n`cdk-glue-iceberg-table`. In TypeScript / JavaScript the compiled\nsurface lives under `dist/lib/iceberg/` after `npm install`; in Python\nthe same surface is imported from the `cdk_glue_iceberg_table` module\nafter `pip install`:\n\n- **`IcebergTable`** — the L2 construct itself, with `grantRead` / `grantWrite` / `grantReadWrite` and the `fromIcebergTableAttributes(...)` import factory.\n- **`IcebergType`** — primitive types, the v3 constants `UNKNOWN`, `TIMESTAMP_NS`, `TIMESTAMPTZ_NS`, and `VARIANT`, and the `list` / `map` / `struct` / `decimal` / `fixed` / `geometry(crs?)` / `geography(crs?, algorithm?)` factories. `list` takes an `IcebergListDefinition`, `map` an `IcebergMapDefinition`, and `struct` a list of `IcebergStructFieldDefinition`, each carrying the nested field ids. Renders to the string Glue's `IcebergStructField.type` expects.\n- **`IcebergPartitionTransform`** — identity / `bucket(N)` / `truncate(W)` / year / month / day / hour / void. Each transform validates against the source column type at synth time.\n- **`IcebergDataFormat`** (parquet/orc/avro, default parquet), **`IcebergFormatVersion`** (v1/v2/v3, required — set explicitly per table; Athena cannot query v3 tables), **`IcebergSortDirection`**, **`IcebergNullOrder`**, **`IcebergEdgeAlgorithm`** (`SPHERICAL`, `VINCENTY`, `THOMAS`, `ANDOYER`, `KARNEY`; the second argument of `IcebergType.geography`), plus a `tableProperties` validator that catches misconfigured properties before they leave your machine (wrong codec for the chosen format, `merge-on-read` on a v1 table, non-positive numeric values, …).\n\n## Using `IcebergTable`\n\nA minimal table:\n\n```typescript\nimport {\n Bucket,\n} from 'aws-cdk-lib/aws-s3';\nimport {\n Database,\n} from 'aws-cdk-lib/aws-glue';\nimport {\n IcebergFormatVersion,\n IcebergTable,\n IcebergType,\n} from 'cdk-glue-iceberg-table';\n\nconst bucket = new Bucket(this, 'Warehouse');\n\nconst db = new Database(this, 'Db', {\n databaseName: 'analytics',\n});\n\nnew IcebergTable(this, 'Users', {\n database: db,\n tableName: 'users',\n columns: [\n {\n name: 'user_id',\n type: IcebergType.LONG,\n required: true,\n id: 1,\n },\n {\n name: 'email',\n type: IcebergType.STRING,\n required: true,\n id: 2,\n },\n {\n name: 'signed_up_at',\n type: IcebergType.TIMESTAMPTZ,\n required: true,\n id: 3,\n },\n ],\n location: `s3://${bucket.bucketName}/analytics/users/`,\n formatVersion: IcebergFormatVersion.V2,\n});\n```\n\nEvery top-level column must declare an `id`: a stable, unique,\npositive integer you pick once and never reuse or reassign. Because\nIceberg data files reference fields by id rather than by name, a fixed\nid is what lets you add, rename, and drop columns across deploys\nwithout corrupting old data — see\n[How do I evolve an Iceberg table schema](#how-do-i-evolve-an-iceberg-table-schema-add-rename-or-drop-a-column-in-cloudformation).\nOnce a column is dropped, leave its id retired; never hand it to a new\ncolumn. Nested fields follow the same rule: every struct field takes\nan `id`, every list an `elementId`, and every map a `keyId` and a\n`valueId`. All ids in a schema, top-level and nested, must be distinct\nintegers from 1 to 2147483447.\n\nA table that exercises most of the surface (partitions, sort order,\nnested types, identifier fields, table properties, removal policy):\n\n```typescript\nimport {\n RemovalPolicy,\n} from 'aws-cdk-lib';\nimport {\n Database,\n} from 'aws-cdk-lib/aws-glue';\nimport {\n IcebergDataFormat,\n IcebergFormatVersion,\n IcebergNullOrder,\n IcebergPartitionTransform,\n IcebergSortDirection,\n IcebergTable,\n IcebergType,\n} from 'cdk-glue-iceberg-table';\n\nnew IcebergTable(this, 'OrdersTable', {\n database: db,\n tableName: 'orders',\n comment: 'Demo Iceberg orders table — exercises partitions, sort order, and merge-on-read.',\n columns: [\n {\n name: 'order_id',\n type: IcebergType.LONG,\n required: true,\n id: 1,\n },\n {\n name: 'customer_id',\n type: IcebergType.LONG,\n required: true,\n id: 2,\n },\n {\n name: 'order_amount',\n type: IcebergType.decimal(12, 2),\n required: true,\n id: 3,\n },\n {\n name: 'currency',\n type: IcebergType.STRING,\n required: true,\n id: 4,\n },\n {\n name: 'placed_at',\n type: IcebergType.TIMESTAMPTZ,\n required: true,\n id: 5,\n },\n {\n name: 'tags',\n type: IcebergType.list({\n element: IcebergType.STRING,\n elementId: 9,\n }),\n id: 6,\n },\n {\n name: 'shipping_address',\n type: IcebergType.struct([\n {\n id: 10,\n name: 'line1',\n type: IcebergType.STRING,\n required: true,\n },\n {\n id: 11,\n name: 'city',\n type: IcebergType.STRING,\n required: true,\n },\n {\n id: 12,\n name: 'country',\n type: IcebergType.STRING,\n required: true,\n },\n {\n id: 13,\n name: 'postal_code',\n type: IcebergType.STRING,\n },\n ]),\n id: 7,\n },\n {\n name: 'metadata',\n type: IcebergType.map({\n key: IcebergType.STRING,\n keyId: 14,\n value: IcebergType.STRING,\n valueId: 15,\n }),\n id: 8,\n },\n ],\n location: `s3://${bucket.bucketName}/analytics/orders/`,\n partitionSpec: [\n {\n sourceColumn: 'placed_at',\n transform: IcebergPartitionTransform.DAY,\n fieldId: 1000,\n },\n {\n sourceColumn: 'customer_id',\n transform: IcebergPartitionTransform.bucket(16),\n fieldId: 1001,\n },\n ],\n sortOrder: [\n {\n sourceColumn: 'placed_at',\n direction: IcebergSortDirection.ASC,\n nullOrder: IcebergNullOrder.NULLS_LAST,\n },\n {\n sourceColumn: 'order_id',\n direction: IcebergSortDirection.ASC,\n },\n ],\n identifierFieldNames: [\n 'order_id',\n ],\n dataFormat: IcebergDataFormat.PARQUET,\n formatVersion: IcebergFormatVersion.V2,\n tableProperties: {\n 'write.parquet.compression-codec': 'zstd',\n 'write.delete.mode': 'merge-on-read',\n 'write.update.mode': 'merge-on-read',\n 'write.merge.mode': 'merge-on-read',\n 'write.target-file-size-bytes': '134217728',\n 'history.expire.min-snapshots-to-keep': '5',\n 'gc.enabled': 'true',\n },\n removalPolicy: RemovalPolicy.DESTROY,\n});\n```\n\nEach partition field also pins a `fieldId`: an integer of 1000 or\nabove (the Iceberg spec reserves lower ids for schema columns), unique\nacross the table's entire partition-spec history. The discipline is\nthe inverse of the column-id rule. A column keeps its id forever; a\npartition field keeps its id only while it stays untouched. Change\nanything about a field — swap `month` for `day`, point it at a\ndifferent source column — and it becomes a *new* field that needs a\nfresh, never-before-used id, while the old id retires with the old\nspec. Reusing a retired id (or reassigning an id to a different field)\nproduces a table that Athena still reads but Spark and Trino reject\nwith `ValidationException: Conflicting partition fields`.\n\n`identifierFieldNames` lists the columns that together identify a row\nand renders as the schema's `identifier-field-ids`. Each one must be a\n`required: true` column (Glue rejects an optional one). The construct\nprefixes each identifier column's `doc` with `(PK) `, so a `doc` you\nwrite must not start with `(PK) `; see [Evolving schema and\npartitions](#evolving-schema-and-partitions).\n\nThe resulting Iceberg `metadata.json` for this table contains every\nfeature you set:\n\n```json\n{\n \"format-version\": 2,\n \"table-uuid\": \"39a948f9-...\",\n \"current-schema-id\": 0,\n \"schemas\": [\n {\n \"schema-id\": 0,\n \"identifier-field-ids\": [1],\n \"fields\": [\n { \"id\": 1, \"name\": \"order_id\", \"required\": true, \"type\": \"long\", \"doc\": \"(PK) \" },\n { \"id\": 2, \"name\": \"customer_id\", \"required\": true, \"type\": \"long\" },\n { \"id\": 3, \"name\": \"order_amount\", \"required\": true, \"type\": \"decimal(12, 2)\" },\n { \"id\": 4, \"name\": \"currency\", \"required\": true, \"type\": \"string\" },\n { \"id\": 5, \"name\": \"placed_at\", \"required\": true, \"type\": \"timestamptz\" },\n { \"id\": 6, \"name\": \"tags\", \"required\": false,\n \"type\": { \"type\": \"list\", \"element-id\": 9, \"element\": \"string\", \"element-required\": false } },\n { \"id\": 7, \"name\": \"shipping_address\", \"required\": false,\n \"type\": { \"type\": \"struct\", \"fields\": [\n { \"id\": 10, \"name\": \"line1\", \"required\": true, \"type\": \"string\" },\n { \"id\": 11, \"name\": \"city\", \"required\": true, \"type\": \"string\" },\n { \"id\": 12, \"name\": \"country\", \"required\": true, \"type\": \"string\" },\n { \"id\": 13, \"name\": \"postal_code\", \"required\": false, \"type\": \"string\" }\n ] } },\n { \"id\": 8, \"name\": \"metadata\", \"required\": false,\n \"type\": { \"type\": \"map\", \"key-id\": 14, \"key\": \"string\", \"value-id\": 15,\n \"value-required\": false, \"value\": \"string\" } }\n ]\n }\n ],\n \"partition-specs\": [\n { \"spec-id\": 0, \"fields\": [\n { \"name\": \"placed_at_day\", \"transform\": \"day\", \"source-id\": 5, \"field-id\": 1000 },\n { \"name\": \"customer_id_bucket\", \"transform\": \"bucket[16]\", \"source-id\": 2, \"field-id\": 1001 }\n ]}\n ],\n \"sort-orders\": [\n { \"order-id\": 1, \"fields\": [\n { \"transform\": \"identity\", \"source-id\": 5, \"direction\": \"asc\", \"null-order\": \"nulls-last\" },\n { \"transform\": \"identity\", \"source-id\": 1, \"direction\": \"asc\", \"null-order\": \"nulls-last\" }\n ]}\n ],\n \"properties\": {\n \"format-version\": \"2\",\n \"write.format.default\": \"parquet\",\n \"write.parquet.compression-codec\": \"zstd\",\n \"write.merge.mode\": \"merge-on-read\",\n \"write.update.mode\": \"merge-on-read\",\n \"write.delete.mode\": \"merge-on-read\",\n \"write.target-file-size-bytes\": \"134217728\",\n \"history.expire.min-snapshots-to-keep\": \"5\",\n \"gc.enabled\": \"true\",\n \"comment\": \"Demo Iceberg orders table — exercises partitions, sort order, and merge-on-read.\"\n }\n}\n```\n\n### Format version 3\n\nSet `formatVersion: IcebergFormatVersion.V3` to create a v3 table. The\nsix v3 types (below) are only accepted on a V3 table, at any nesting\ndepth: inside a struct, as a list element, or as a map key or value.\nSynth fails on a V1 or V2 table that uses one.\n\n```typescript\nimport {\n IcebergEdgeAlgorithm,\n IcebergFormatVersion,\n IcebergTable,\n IcebergType,\n} from 'cdk-glue-iceberg-table';\n\nnew IcebergTable(this, 'Events', {\n database: db,\n tableName: 'events',\n location: `s3://${bucket.bucketName}/analytics/events/`,\n columns: [\n { name: 'occurred_at', type: IcebergType.TIMESTAMP_NS, id: 1 },\n { name: 'payload', type: IcebergType.VARIANT, id: 2 },\n {\n name: 'origin',\n type: IcebergType.geography('OGC:CRS84', IcebergEdgeAlgorithm.SPHERICAL),\n id: 3,\n },\n ],\n formatVersion: IcebergFormatVersion.V3,\n});\n```\n\nThe same table in Python:\n\n```python\nfrom cdk_glue_iceberg_table import (\n IcebergEdgeAlgorithm,\n IcebergFormatVersion,\n IcebergTable,\n IcebergType,\n)\n\nIcebergTable(self, \"Events\",\n database=db,\n table_name=\"events\",\n location=f\"s3://{bucket.bucket_name}/analytics/events/\",\n columns=[\n {\"name\": \"occurred_at\", \"type\": IcebergType.TIMESTAMP_NS, \"id\": 1},\n {\"name\": \"payload\", \"type\": IcebergType.VARIANT, \"id\": 2},\n {\n \"name\": \"origin\",\n \"type\": IcebergType.geography(\"OGC:CRS84\", IcebergEdgeAlgorithm.SPHERICAL),\n \"id\": 3,\n },\n ],\n format_version=IcebergFormatVersion.V3,\n)\n```\n\nThis table has a `timestamp_ns` column; see [Known limitations](#known-limitations)\nbefore reading it from upstream Spark.\n\nThe v3 types, with the rules `cdk synth` enforces:\n\n| Type | Factory | Rendered string | Partition and identifier rules |\n| --- | --- | --- | --- |\n| unknown | `IcebergType.UNKNOWN` | `unknown` | Must be optional, as a column, list element, or map value; never a map key. Partition source only with `void`. Not an identifier field. |\n| timestamp with nanoseconds | `IcebergType.TIMESTAMP_NS` | `timestamp_ns` | `identity`, `year`, `month`, `day`, `hour`, `bucket(N)`, `void`; not `truncate(W)`. Allowed as an identifier field. |\n| timestamptz with nanoseconds | `IcebergType.TIMESTAMPTZ_NS` | `timestamptz_ns` | Same as `timestamp_ns`. |\n| variant | `IcebergType.VARIANT` | `variant` | Never a partition or sort source, `void` included. Not an identifier field. |\n| geometry | `IcebergType.geometry(crs?)` | `geometry`, or `geometry(<crs>)` when a CRS is given | Partition source only with `void`. Not an identifier field. |\n| geography | `IcebergType.geography(crs?, algorithm?)` | `geography`, `geography(<crs>)`, or `geography(<crs>, <algorithm>)` when an algorithm is given, such as `geography(OGC:CRS84, spherical)` | Same as `geometry`. |\n\nA geometry or geography `crs` is an identifier such as `OGC:CRS84` or\n`EPSG:3857`; whitespace, parentheses, braces, and commas are rejected.\nWhen `algorithm` is set without a `crs`, the rendered string spells out\n`OGC:CRS84`.\n\nWhich engines read a v3 table created by the construct:\n\n| Engine | v3 tables | Notes |\n| --- | --- | --- |\n| Spark 4.1 + Iceberg 1.12 (the integration-test runner) | Yes | Reads and writes tables the construct creates, including deletion vectors, row lineage, `variant`, `unknown`, and `geometry` / `geography`, except tables with nanosecond-timestamp columns or a geometry CRS other than `OGC:CRS84` (checked by `scripts/spark/verify_v3_dml.py`; details in [Known limitations](#known-limitations)). |\n| AWS Glue 6.0 | Documented | The [AWS Glue versions](https://docs.aws.amazon.com/glue/latest/dg/release-notes.html) page lists \"Iceberg format version 3 with VARIANT data type, deletion vectors, row lineage tracking, nanosecond timestamps, and geo types\". The integration suites do not run on Glue 6.0. |\n| Amazon EMR Spark 8.1.0 (Spark 4.1.1, Iceberg 1.11.0-amzn-0) | Documented | The [emr-spark-8.1.0 release notes](https://docs.aws.amazon.com/emr/latest/ReleaseGuide/emr-spark810-release.html) state \"Amazon EMR Spark 8.1.0 extends Iceberg v3 spec support for Spark workloads\". The integration suites do not run on EMR 8.1. |\n| Athena SQL | No | The [Athena Iceberg page](https://docs.aws.amazon.com/athena/latest/ug/querying-iceberg.html) states \"Athena only creates and operates on Iceberg v2 tables.\" |\n\n### Granting access\n\n```typescript\ntable.grantRead(role); // Glue read + S3 read on the table's prefix\ntable.grantWrite(role); // Glue write + S3 write\ntable.grantReadWrite(role);\n```\n\nThe `grant*` helpers issue **IAM grants only**. Under Lake Formation\nyou still add the matching `SELECT` / `INSERT` / `DELETE` LF grants on\ntop of the construct's IAM grants for Athena queries to succeed.\n\n### Importing an existing table\n\n```typescript\nconst existing = IcebergTable.fromIcebergTableAttributes(this, 'Orders', {\n database: db,\n tableName: 'orders',\n location: 's3://my-bucket/analytics/orders/',\n});\nexisting.grantRead(role);\n```\n\n### Evolving schema and partitions\n\nChange the `columns` array (or `partitionSpec`) and run `cdk deploy`\nagain. The construct passes the new schema to Glue's `UpdateTable`,\nwhich writes a new `metadata.json` with a new `schema-id`; existing\ndata files stay readable because each column's `id` is pinned and\nnever reused. Adds, renames (same `id`, new `name`), and drops all\nflow through `cdk deploy` alone — no out-of-band SQL DDL.\n\nNested fields evolve the same way. Each struct field, list element,\nmap key, and map value keeps the id you gave it (the rule is under\n[Using `IcebergTable`](#using-icebergtable)), so adding a column or a\nstruct field anywhere in the schema leaves every other id unchanged. A\nnew nested field takes an id no field of the table has ever used:\n\n```typescript\ntype: IcebergType.struct([\n { id: 10, name: 'line1', type: IcebergType.STRING },\n { id: 16, name: 'line2', type: IcebergType.STRING }, // new field, never-used id\n { id: 11, name: 'city', type: IcebergType.STRING },\n]),\n```\n\nUpgrading from a version before 0.12.0, which numbered nested fields\nitself: pin each nested field to the id the deployed table already\nhas, or the first deploy renumbers it and existing data files read\nunder the wrong field. Read the ids from the `element-id`, `key-id`,\n`value-id`, and struct field `id` values in the previous version's\nsynthesized template (`cdk.out/<Stack>.template.json`) or in the\ntable's current `metadata.json`. A nested type object shared by two\ncolumns now fails synth with a duplicate id; give each column its own\nnested type with its own ids. The list element and map value\nnullability default also changed: `elementRequired` and\n`valueRequired` now default to `false`. Earlier versions made list\nelements required by default and map values required unless the third\nargument of `map` was `false`; set `elementRequired: true` or\n`valueRequired: true` wherever the deployed schema has\n`\"element-required\": true` or `\"value-required\": true`.\n\nGlue's `UpdateTable` reuses an earlier schema whose fields (name,\ntype, `required`, `doc`) match the request, together with that\nschema's `identifier-field-ids`. The construct therefore prefixes the\n`doc` of every identifier column with `(PK) ` (just `(PK) ` when the\ncolumn has no `doc`), shown as the column comment, so every\nidentifier change is a field change. On a table whose schema history\nwas written with the marker, identifier changes flow through `cdk\ndeploy` like column changes.\n\nPartition evolution flows the same way, with one extra rule on\n`fieldId`: a changed partition field is a new partition field. To move\na table from `month(placed_at)` to `day(placed_at)`, drop the month\nentry and add a day entry under a fresh `fieldId` — never recycle the\nmonth field's id:\n\n```typescript\npartitionSpec: [\n // was: { sourceColumn: 'placed_at', transform: IcebergPartitionTransform.MONTH, fieldId: 1000 },\n {\n sourceColumn: 'placed_at',\n transform: IcebergPartitionTransform.DAY,\n fieldId: 1001,\n },\n],\n```\n\nOld data files written under the month spec stay readable; new writes\npartition by day. Reusing `1000` for the day field instead corrupts\nthe spec history for strict engines (Spark, Trino) while Athena keeps\nworking — the failure only surfaces at Spark runtime.\n\n### Inserting and querying\n\n```sql\n-- INSERT into the orders table\nINSERT INTO sample_database.orders VALUES\n (1001, 5001, DECIMAL '149.99', 'USD',\n TIMESTAMP '2026-05-20 09:15:00 UTC',\n ARRAY['holiday-promo','first-order'],\n CAST(ROW('1 Infinite Loop','Cupertino','US','95014')\n AS ROW(line1 VARCHAR,city VARCHAR,country VARCHAR,postal_code VARCHAR)),\n MAP(ARRAY['channel','utm'], ARRAY['web','google'])),\n -- ... more rows\n;\n\n-- merge-on-read DELETE (only legal because we chose v2 + merge-on-read mode)\nDELETE FROM sample_database.orders WHERE order_id = 1003;\n\n-- merge-on-read UPDATE\nUPDATE sample_database.orders SET currency = 'GBP' WHERE customer_id = 5002;\n\n-- SELECT\nSELECT customer_id, SUM(order_amount) AS total\n FROM sample_database.orders\n GROUP BY 1\n ORDER BY 2 DESC;\n```\n\n## Two footguns the construct prevents\n\n### Footgun #1 — schema under `storageDescriptor.columns`\n\nThe CREATE succeeds but the first UPDATE silently strips\n`table_type=ICEBERG` from the table's Glue parameters, and Athena\nqueries after that fail with `HIVE_UNSUPPORTED_FORMAT`.\n\n```typescript\n// DON'T DO THIS — what most StackOverflow / re:Post examples show\nnew CfnTable(this, 'OrdersBad', {\n catalogId: this.account,\n databaseName: 'analytics',\n tableInput: {\n name: 'orders',\n tableType: 'EXTERNAL_TABLE',\n parameters: {\n table_type: 'ICEBERG',\n },\n storageDescriptor: {\n location: 's3://.../orders/',\n columns: [\n /* ... */\n ],\n },\n },\n openTableFormatInput: {\n icebergInput: {\n metadataOperation: 'CREATE',\n version: '2',\n },\n },\n});\n```\n\n`IcebergTable` instead always emits schema/partitions/sort/properties\nunder `openTableFormatInput.icebergInput.icebergTableInput`, never\nunder `storageDescriptor`.\n\n### Footgun #2 — `tableInput` co-present with `openTableFormatInput`\n\nEven setting just `tableInput: { name: 'foo' }` next to\n`openTableFormatInput` returns\n`\"Table metadata is expected only via TableInput or via IcebergTableInputProperties inside OpenTableFormatInput\"`.\nThe construct never emits `tableInput`; the table-level comment goes\ninto `tableProperties['comment']`, which lives inside\n`icebergTableInput.properties`.\n\n(There is a third footgun, field-id reuse after a column drop, that\nthe construct does **not** prevent. See the next section.)\n\n## Known limitations\n\n- **Field-id reuse is not detected across deploys.** This applies to nested ids (struct field, list element, map key and value) as well as column ids. If you drop a column with `id = 5` and then add a different column with `id = 5` in a later deploy, Glue accepts the UPDATE and Iceberg's metadata silently violates the \"never reuse a retired id\" invariant. Readers projecting old snapshots will surface deleted data under the new field's name. The construct enforces uniqueness **within one deploy** (`duplicate field id N` validator), but it doesn't compare against the live table state. The safe workflow is to treat dropped ids as retired forever.\n- **Partition field-id reuse is not detected across deploys either.** The same live-state blindness applies to partition `fieldId`s: the construct validates them within one deploy (integer >= 1000, unique in the spec), but it cannot tell that the id you pinned already appeared in an earlier spec of the deployed table. The invariant partition ids must uphold is stricter than the column one — unique across the table's **entire spec history**, so a changed field (different transform or source column) must take a fresh id rather than keep its old one. Violate it and strict engines (Spark, Trino) reject the table with `Conflicting partition fields` while Athena keeps answering, masking the break until Spark runtime. The safe workflow: treat every id that has ever appeared in any spec as retired, and allocate new fields the next never-used id. A partition change needs a new source column or transform; Glue ignores a `fieldId`-only change.\n- **`last-partition-id` is written by Glue, not by the construct.** The construct supplies the spec's field ids; Glue's `UpdateTable` computes the table's `last-partition-id` counter when it writes the new metadata. The repo's integration test asserts the counter keeps up with the highest supplied field id after a partition evolution, but engines that later evolve the spec themselves (e.g. Spark `ALTER TABLE … ADD PARTITION FIELD`) allocate from that counter — if you mix CDK-managed and engine-managed partition evolution, verify the counter in `metadata.json` before trusting engine-side changes.\n- **Removing the last identifier from a table created with identifiers before 0.11.0 can bring the old ids back.** That table's history holds an unmarked schema with ids, and Glue reuses it when the rendered fields match it again. Change a column `doc` in the same deploy that removes the last identifier.\n- **CREATE-only metadata operation.** The CFN `IcebergInput.metadataOperation` only accepts `CREATE`; the construct always emits that. Subsequent deploys use Glue's normal `UpdateTable` path, which writes new Iceberg metadata in-place.\n- **Format version is immutable after CREATE.** Glue ignores a V2 to V3 `formatVersion` change, though `properties.format-version` then reads `3`. Keep `formatVersion` at the table's real version, or destroy + recreate the table to change it. An engine can upgrade a v2 table to v3 in place with `ALTER TABLE ... SET TBLPROPERTIES ('format-version' = '3')`; after that, set `formatVersion` to `V3` so the next deploy declares the version the table already has.\n- **`merge-on-read` requires v2 or later.** The construct rejects `write.{delete,update,merge}.mode = merge-on-read` on a v1 table at synth time.\n- **Column defaults are not available.** Iceberg v3 `initial-default` and `write-default` cannot be declared through CloudFormation: the `AWS::Glue::Table` resource schema has no `InitialDefault` or `WriteDefault` property. Revisit when that schema gains the two properties.\n- **Nanosecond timestamps are catalog-only for upstream Spark 4.1.** A table with any `timestamp_ns` or `timestamptz_ns` column fails to open in upstream Spark 4.1 with Iceberg 1.12. The integration suite for these columns asserts from `metadata.json` only. The [engine matrix](#format-version-3) lists the engines that document support.\n- **Geometry CRS other than `OGC:CRS84` is catalog-only for upstream Spark 4.1.** Spark 4.1 accepts `OGC:CRS84`, or bare `geometry`, as the geometry CRS; a table declaring another CRS, such as `EPSG:3857`, cannot be read there.\n- **Athena DDL features that don't surface through CFN** (e.g. `ALTER TABLE WRITE ORDERED BY`, `ALTER TABLE … SET LOCATION`, `bucketed_by` / `bucket_count` Hive clauses) are not exposed. Use `IcebergPartitionTransform.bucket(N)` instead of Hive bucketing.\n- **Dropping a partition column requires a `void` intermediate per the Iceberg spec**, and the CFN `OpenTableFormatInput` cannot express that. The construct accepts the change, but Athena queries against the result will fail with `Type cannot be null`. The safe pattern is to drop partitions that source from a column while keeping that column in the schema, and only drop a column once it is no longer partitioning anything.\n\n## FAQ\n\n### How do I create an Apache Iceberg table in AWS CDK?\n\nInstall `cdk-glue-iceberg-table`, then declare an `IcebergTable` with a\ndatabase, a column list, and an S3 `location` — see [Use](#use).\n`cdk deploy` creates the Glue Data Catalog table and writes the\nIceberg `metadata.json` under your S3 prefix. No custom resource or\nLambda is involved; it is a plain `AWS::Glue::Table` in your\nCloudFormation template.\n\n### How do I evolve an Iceberg table schema (add, rename, or drop a column) in CloudFormation?\n\nChange the `columns` array and run `cdk deploy` again. The construct\npasses the new schema to Glue's `UpdateTable`, which writes a new\n`metadata.json` with a new `schema-id`; existing data files stay\nreadable because each column's `id` is pinned and never reused.\nPartition changes work the same way, except a changed partition field\ntakes a fresh `fieldId` instead of keeping its old one. See [Evolving\nschema and partitions](#evolving-schema-and-partitions).\n\n### Does CloudFormation support Iceberg tables natively?\n\nYes, through `AWS::Glue::Table` with `OpenTableFormatInput.IcebergInput`,\ndocumented by AWS in [December 2025](https://aws.amazon.com/blogs/big-data/create-and-update-apache-iceberg-tables-with-partitions-in-the-aws-glue-data-catalog-using-the-aws-sdk-and-aws-cloudformation).\nThe catch is that the raw shape corrupts the table on the first\n`Update` if you place schema under `storageDescriptor.columns` or set\n`tableInput` alongside `openTableFormatInput`. This construct only ever\nemits the safe shape and gives you no way to express the unsafe ones.\nSee [Two footguns the construct prevents](#two-footguns-the-construct-prevents).\n\n### What is the difference between cdk-glue-iceberg-table and a raw CfnTable?\n\nA raw `CfnTable` makes you hand-write the `OpenTableFormatInput` JSON\nand own both silent-corruption footguns. `cdk-glue-iceberg-table` gives\nyou a typed `IcebergType` / `IcebergPartitionTransform` API,\nsynth-time validation (partition transforms checked against column\ntypes, format/version mismatches caught before deploy), pinned field\nIDs for safe evolution, and `grantRead` / `grantWrite` helpers. See\n[How it compares](#how-it-compares).\n\n### How do I create a partitioned Iceberg table in CDK?\n\nPass a `partitionSpec` of `IcebergPartitionTransform` entries —\n`identity`, `bucket(N)`, `truncate(W)`, `year`, `month`, `day`, `hour`,\nor `void` — each pinned to a `fieldId` of 1000 or above. Transforms are\nvalidated against their source column's type at synth time. See\n[Using `IcebergTable`](#using-icebergtable).\n\n### Does it work with Athena and Lake Formation?\n\nYes for v2 tables, no for v3 (see the engine matrix in [Format\nversion 3](#format-version-3)). On v2, Athena reads and writes,\nincluding merge-on-read `INSERT` / `UPDATE` / `DELETE` / `MERGE`, time\ntravel, `OPTIMIZE`, and `VACUUM`. The demo app in the\n[`arceus`](https://github.com/ksco92/arceus) repo registers its tables\nwith Lake Formation and exercises the same operations through Spark in\nits integration suite. The construct's `grant*` helpers issue IAM\ngrants; under Lake Formation you still add the matching `SELECT` /\n`INSERT` LF grants. See [Granting access](#granting-access).\n\n### Can I use Iceberg v2 merge-on-read (row-level UPDATE and DELETE)?\n\nYes — set `formatVersion: IcebergFormatVersion.V2` and the\n`write.{delete,update,merge}.mode = merge-on-read` table properties.\nThe construct rejects merge-on-read on a v1 table at synth time.\n\n### Can I create an Iceberg v3 table?\n\nYes. Set `formatVersion: IcebergFormatVersion.V3`; see [Format\nversion 3](#format-version-3) for the types, the engine matrix and the\nlimits.\n\n## Contributing\n\nDevelopment, the monorepo layout, and the demo app live in [CONTRIBUTING.md](https://github.com/ksco92/arceus/blob/main/CONTRIBUTING.md).\n\n## License\n\n[MIT](https://github.com/ksco92/arceus/blob/main/LICENSE).\n"
9755
9755
  },
9756
9756
  "repository": {
9757
9757
  "directory": "packages/cdk-glue-iceberg-table",
@@ -9779,7 +9779,7 @@
9779
9779
  "kind": "interface",
9780
9780
  "locationInModule": {
9781
9781
  "filename": "lib/iceberg/iceberg-table.ts",
9782
- "line": 220
9782
+ "line": 217
9783
9783
  },
9784
9784
  "methods": [
9785
9785
  {
@@ -9790,7 +9790,7 @@
9790
9790
  },
9791
9791
  "locationInModule": {
9792
9792
  "filename": "lib/iceberg/iceberg-table.ts",
9793
- "line": 234
9793
+ "line": 231
9794
9794
  },
9795
9795
  "name": "grantRead",
9796
9796
  "parameters": [
@@ -9815,7 +9815,7 @@
9815
9815
  },
9816
9816
  "locationInModule": {
9817
9817
  "filename": "lib/iceberg/iceberg-table.ts",
9818
- "line": 240
9818
+ "line": 237
9819
9819
  },
9820
9820
  "name": "grantReadWrite",
9821
9821
  "parameters": [
@@ -9840,7 +9840,7 @@
9840
9840
  },
9841
9841
  "locationInModule": {
9842
9842
  "filename": "lib/iceberg/iceberg-table.ts",
9843
- "line": 237
9843
+ "line": 234
9844
9844
  },
9845
9845
  "name": "grantWrite",
9846
9846
  "parameters": [
@@ -9869,7 +9869,7 @@
9869
9869
  "immutable": true,
9870
9870
  "locationInModule": {
9871
9871
  "filename": "lib/iceberg/iceberg-table.ts",
9872
- "line": 228
9872
+ "line": 225
9873
9873
  },
9874
9874
  "name": "database",
9875
9875
  "type": {
@@ -9885,7 +9885,7 @@
9885
9885
  "immutable": true,
9886
9886
  "locationInModule": {
9887
9887
  "filename": "lib/iceberg/iceberg-table.ts",
9888
- "line": 231
9888
+ "line": 228
9889
9889
  },
9890
9890
  "name": "location",
9891
9891
  "type": {
@@ -9901,7 +9901,7 @@
9901
9901
  "immutable": true,
9902
9902
  "locationInModule": {
9903
9903
  "filename": "lib/iceberg/iceberg-table.ts",
9904
- "line": 222
9904
+ "line": 219
9905
9905
  },
9906
9906
  "name": "tableArn",
9907
9907
  "type": {
@@ -9917,7 +9917,7 @@
9917
9917
  "immutable": true,
9918
9918
  "locationInModule": {
9919
9919
  "filename": "lib/iceberg/iceberg-table.ts",
9920
- "line": 225
9920
+ "line": 222
9921
9921
  },
9922
9922
  "name": "tableName",
9923
9923
  "type": {
@@ -9945,14 +9945,14 @@
9945
9945
  {
9946
9946
  "abstract": true,
9947
9947
  "docs": {
9948
- "remarks": "Required: every top-level\ncolumn must be pinned to a stable, unique positive integer that\nyou never reuse or reassign across deploys. That stability is the\nwhole point — because data files reference fields by id, a fixed\nid lets you add, remove, and reorder columns safely without\ntriggering Iceberg's silent-corruption-on-id-reuse trap. Pick the\nid once when you add the column and never change it; once a column\nis dropped, leave its id retired rather than giving it to a new\ncolumn.",
9948
+ "remarks": "Keep it for the life of the column and never\ngive a dropped column's id to another field.",
9949
9949
  "stability": "experimental",
9950
- "summary": "Iceberg field id for this column."
9950
+ "summary": "Iceberg field id for this column: unique across the table schema, from 1 to 2147483447."
9951
9951
  },
9952
9952
  "immutable": true,
9953
9953
  "locationInModule": {
9954
9954
  "filename": "lib/iceberg/iceberg-table.ts",
9955
- "line": 105
9955
+ "line": 99
9956
9956
  },
9957
9957
  "name": "id",
9958
9958
  "type": {
@@ -9994,8 +9994,9 @@
9994
9994
  {
9995
9995
  "abstract": true,
9996
9996
  "docs": {
9997
+ "remarks": "must not start with `(PK) `.",
9997
9998
  "stability": "experimental",
9998
- "summary": "Optional documentation string."
9999
+ "summary": "Optional documentation string;"
9999
10000
  },
10000
10001
  "immutable": true,
10001
10002
  "locationInModule": {
@@ -10077,7 +10078,7 @@
10077
10078
  "kind": "enum",
10078
10079
  "locationInModule": {
10079
10080
  "filename": "lib/iceberg/iceberg-type.ts",
10080
- "line": 58
10081
+ "line": 40
10081
10082
  },
10082
10083
  "members": [
10083
10084
  {
@@ -10153,6 +10154,175 @@
10153
10154
  "name": "IcebergFormatVersion",
10154
10155
  "symbolId": "lib/iceberg/iceberg-table-properties:IcebergFormatVersion"
10155
10156
  },
10157
+ "cdk-glue-iceberg-table.IcebergListDefinition": {
10158
+ "assembly": "cdk-glue-iceberg-table",
10159
+ "datatype": true,
10160
+ "docs": {
10161
+ "stability": "experimental",
10162
+ "summary": "Definition of a list type."
10163
+ },
10164
+ "fqn": "cdk-glue-iceberg-table.IcebergListDefinition",
10165
+ "kind": "interface",
10166
+ "locationInModule": {
10167
+ "filename": "lib/iceberg/iceberg-type.ts",
10168
+ "line": 70
10169
+ },
10170
+ "name": "IcebergListDefinition",
10171
+ "properties": [
10172
+ {
10173
+ "abstract": true,
10174
+ "docs": {
10175
+ "stability": "experimental",
10176
+ "summary": "Element type."
10177
+ },
10178
+ "immutable": true,
10179
+ "locationInModule": {
10180
+ "filename": "lib/iceberg/iceberg-type.ts",
10181
+ "line": 72
10182
+ },
10183
+ "name": "element",
10184
+ "type": {
10185
+ "fqn": "cdk-glue-iceberg-table.IcebergType"
10186
+ }
10187
+ },
10188
+ {
10189
+ "abstract": true,
10190
+ "docs": {
10191
+ "stability": "experimental",
10192
+ "summary": "Iceberg field id of the element: unique across the table schema, from 1 to 2147483447."
10193
+ },
10194
+ "immutable": true,
10195
+ "locationInModule": {
10196
+ "filename": "lib/iceberg/iceberg-type.ts",
10197
+ "line": 75
10198
+ },
10199
+ "name": "elementId",
10200
+ "type": {
10201
+ "primitive": "number"
10202
+ }
10203
+ },
10204
+ {
10205
+ "abstract": true,
10206
+ "docs": {
10207
+ "remarks": "Defaults to `false`.",
10208
+ "stability": "experimental",
10209
+ "summary": "Whether elements are non-nullable."
10210
+ },
10211
+ "immutable": true,
10212
+ "locationInModule": {
10213
+ "filename": "lib/iceberg/iceberg-type.ts",
10214
+ "line": 78
10215
+ },
10216
+ "name": "elementRequired",
10217
+ "optional": true,
10218
+ "type": {
10219
+ "primitive": "boolean"
10220
+ }
10221
+ }
10222
+ ],
10223
+ "symbolId": "lib/iceberg/iceberg-type:IcebergListDefinition"
10224
+ },
10225
+ "cdk-glue-iceberg-table.IcebergMapDefinition": {
10226
+ "assembly": "cdk-glue-iceberg-table",
10227
+ "datatype": true,
10228
+ "docs": {
10229
+ "remarks": "Keys are always required per the Iceberg spec.",
10230
+ "stability": "experimental",
10231
+ "summary": "Definition of a map type."
10232
+ },
10233
+ "fqn": "cdk-glue-iceberg-table.IcebergMapDefinition",
10234
+ "kind": "interface",
10235
+ "locationInModule": {
10236
+ "filename": "lib/iceberg/iceberg-type.ts",
10237
+ "line": 82
10238
+ },
10239
+ "name": "IcebergMapDefinition",
10240
+ "properties": [
10241
+ {
10242
+ "abstract": true,
10243
+ "docs": {
10244
+ "stability": "experimental",
10245
+ "summary": "Key type."
10246
+ },
10247
+ "immutable": true,
10248
+ "locationInModule": {
10249
+ "filename": "lib/iceberg/iceberg-type.ts",
10250
+ "line": 84
10251
+ },
10252
+ "name": "key",
10253
+ "type": {
10254
+ "fqn": "cdk-glue-iceberg-table.IcebergType"
10255
+ }
10256
+ },
10257
+ {
10258
+ "abstract": true,
10259
+ "docs": {
10260
+ "stability": "experimental",
10261
+ "summary": "Iceberg field id of the key: unique across the table schema, from 1 to 2147483447."
10262
+ },
10263
+ "immutable": true,
10264
+ "locationInModule": {
10265
+ "filename": "lib/iceberg/iceberg-type.ts",
10266
+ "line": 87
10267
+ },
10268
+ "name": "keyId",
10269
+ "type": {
10270
+ "primitive": "number"
10271
+ }
10272
+ },
10273
+ {
10274
+ "abstract": true,
10275
+ "docs": {
10276
+ "stability": "experimental",
10277
+ "summary": "Value type."
10278
+ },
10279
+ "immutable": true,
10280
+ "locationInModule": {
10281
+ "filename": "lib/iceberg/iceberg-type.ts",
10282
+ "line": 90
10283
+ },
10284
+ "name": "value",
10285
+ "type": {
10286
+ "fqn": "cdk-glue-iceberg-table.IcebergType"
10287
+ }
10288
+ },
10289
+ {
10290
+ "abstract": true,
10291
+ "docs": {
10292
+ "stability": "experimental",
10293
+ "summary": "Iceberg field id of the value: unique across the table schema, from 1 to 2147483447."
10294
+ },
10295
+ "immutable": true,
10296
+ "locationInModule": {
10297
+ "filename": "lib/iceberg/iceberg-type.ts",
10298
+ "line": 93
10299
+ },
10300
+ "name": "valueId",
10301
+ "type": {
10302
+ "primitive": "number"
10303
+ }
10304
+ },
10305
+ {
10306
+ "abstract": true,
10307
+ "docs": {
10308
+ "remarks": "Defaults to `false`.",
10309
+ "stability": "experimental",
10310
+ "summary": "Whether values are non-nullable."
10311
+ },
10312
+ "immutable": true,
10313
+ "locationInModule": {
10314
+ "filename": "lib/iceberg/iceberg-type.ts",
10315
+ "line": 96
10316
+ },
10317
+ "name": "valueRequired",
10318
+ "optional": true,
10319
+ "type": {
10320
+ "primitive": "boolean"
10321
+ }
10322
+ }
10323
+ ],
10324
+ "symbolId": "lib/iceberg/iceberg-type:IcebergMapDefinition"
10325
+ },
10156
10326
  "cdk-glue-iceberg-table.IcebergNullOrder": {
10157
10327
  "assembly": "cdk-glue-iceberg-table",
10158
10328
  "docs": {
@@ -10195,7 +10365,7 @@
10195
10365
  "kind": "interface",
10196
10366
  "locationInModule": {
10197
10367
  "filename": "lib/iceberg/iceberg-table.ts",
10198
- "line": 109
10368
+ "line": 103
10199
10369
  },
10200
10370
  "name": "IcebergPartitionField",
10201
10371
  "properties": [
@@ -10209,7 +10379,7 @@
10209
10379
  "immutable": true,
10210
10380
  "locationInModule": {
10211
10381
  "filename": "lib/iceberg/iceberg-table.ts",
10212
- "line": 140
10382
+ "line": 134
10213
10383
  },
10214
10384
  "name": "fieldId",
10215
10385
  "type": {
@@ -10225,7 +10395,7 @@
10225
10395
  "immutable": true,
10226
10396
  "locationInModule": {
10227
10397
  "filename": "lib/iceberg/iceberg-table.ts",
10228
- "line": 111
10398
+ "line": 105
10229
10399
  },
10230
10400
  "name": "sourceColumn",
10231
10401
  "type": {
@@ -10241,7 +10411,7 @@
10241
10411
  "immutable": true,
10242
10412
  "locationInModule": {
10243
10413
  "filename": "lib/iceberg/iceberg-table.ts",
10244
- "line": 114
10414
+ "line": 108
10245
10415
  },
10246
10416
  "name": "transform",
10247
10417
  "type": {
@@ -10258,7 +10428,7 @@
10258
10428
  "immutable": true,
10259
10429
  "locationInModule": {
10260
10430
  "filename": "lib/iceberg/iceberg-table.ts",
10261
- "line": 121
10431
+ "line": 115
10262
10432
  },
10263
10433
  "name": "name",
10264
10434
  "optional": true,
@@ -10967,7 +11137,7 @@
10967
11137
  "kind": "interface",
10968
11138
  "locationInModule": {
10969
11139
  "filename": "lib/iceberg/iceberg-table.ts",
10970
- "line": 144
11140
+ "line": 138
10971
11141
  },
10972
11142
  "name": "IcebergSortField",
10973
11143
  "properties": [
@@ -10980,7 +11150,7 @@
10980
11150
  "immutable": true,
10981
11151
  "locationInModule": {
10982
11152
  "filename": "lib/iceberg/iceberg-table.ts",
10983
- "line": 146
11153
+ "line": 140
10984
11154
  },
10985
11155
  "name": "sourceColumn",
10986
11156
  "type": {
@@ -10997,7 +11167,7 @@
10997
11167
  "immutable": true,
10998
11168
  "locationInModule": {
10999
11169
  "filename": "lib/iceberg/iceberg-table.ts",
11000
- "line": 152
11170
+ "line": 146
11001
11171
  },
11002
11172
  "name": "direction",
11003
11173
  "optional": true,
@@ -11015,7 +11185,7 @@
11015
11185
  "immutable": true,
11016
11186
  "locationInModule": {
11017
11187
  "filename": "lib/iceberg/iceberg-table.ts",
11018
- "line": 155
11188
+ "line": 149
11019
11189
  },
11020
11190
  "name": "nullOrder",
11021
11191
  "optional": true,
@@ -11033,7 +11203,7 @@
11033
11203
  "immutable": true,
11034
11204
  "locationInModule": {
11035
11205
  "filename": "lib/iceberg/iceberg-table.ts",
11036
- "line": 149
11206
+ "line": 143
11037
11207
  },
11038
11208
  "name": "transform",
11039
11209
  "optional": true,
@@ -11055,10 +11225,26 @@
11055
11225
  "kind": "interface",
11056
11226
  "locationInModule": {
11057
11227
  "filename": "lib/iceberg/iceberg-type.ts",
11058
- "line": 70
11228
+ "line": 52
11059
11229
  },
11060
11230
  "name": "IcebergStructFieldDefinition",
11061
11231
  "properties": [
11232
+ {
11233
+ "abstract": true,
11234
+ "docs": {
11235
+ "stability": "experimental",
11236
+ "summary": "Iceberg field id of the field: unique across the table schema, from 1 to 2147483447."
11237
+ },
11238
+ "immutable": true,
11239
+ "locationInModule": {
11240
+ "filename": "lib/iceberg/iceberg-type.ts",
11241
+ "line": 54
11242
+ },
11243
+ "name": "id",
11244
+ "type": {
11245
+ "primitive": "number"
11246
+ }
11247
+ },
11062
11248
  {
11063
11249
  "abstract": true,
11064
11250
  "docs": {
@@ -11068,7 +11254,7 @@
11068
11254
  "immutable": true,
11069
11255
  "locationInModule": {
11070
11256
  "filename": "lib/iceberg/iceberg-type.ts",
11071
- "line": 72
11257
+ "line": 57
11072
11258
  },
11073
11259
  "name": "name",
11074
11260
  "type": {
@@ -11084,7 +11270,7 @@
11084
11270
  "immutable": true,
11085
11271
  "locationInModule": {
11086
11272
  "filename": "lib/iceberg/iceberg-type.ts",
11087
- "line": 75
11273
+ "line": 60
11088
11274
  },
11089
11275
  "name": "type",
11090
11276
  "type": {
@@ -11100,7 +11286,7 @@
11100
11286
  "immutable": true,
11101
11287
  "locationInModule": {
11102
11288
  "filename": "lib/iceberg/iceberg-type.ts",
11103
- "line": 81
11289
+ "line": 66
11104
11290
  },
11105
11291
  "name": "doc",
11106
11292
  "optional": true,
@@ -11118,7 +11304,7 @@
11118
11304
  "immutable": true,
11119
11305
  "locationInModule": {
11120
11306
  "filename": "lib/iceberg/iceberg-type.ts",
11121
- "line": 78
11307
+ "line": 63
11122
11308
  },
11123
11309
  "name": "required",
11124
11310
  "optional": true,
@@ -11144,7 +11330,7 @@
11144
11330
  },
11145
11331
  "locationInModule": {
11146
11332
  "filename": "lib/iceberg/iceberg-table.ts",
11147
- "line": 283
11333
+ "line": 280
11148
11334
  },
11149
11335
  "parameters": [
11150
11336
  {
@@ -11173,7 +11359,7 @@
11173
11359
  "kind": "class",
11174
11360
  "locationInModule": {
11175
11361
  "filename": "lib/iceberg/iceberg-table.ts",
11176
- "line": 257
11362
+ "line": 254
11177
11363
  },
11178
11364
  "methods": [
11179
11365
  {
@@ -11184,7 +11370,7 @@
11184
11370
  },
11185
11371
  "locationInModule": {
11186
11372
  "filename": "lib/iceberg/iceberg-table.ts",
11187
- "line": 356
11373
+ "line": 353
11188
11374
  },
11189
11375
  "name": "fromIcebergTableAttributes",
11190
11376
  "parameters": [
@@ -11221,7 +11407,7 @@
11221
11407
  },
11222
11408
  "locationInModule": {
11223
11409
  "filename": "lib/iceberg/iceberg-table.ts",
11224
- "line": 435
11410
+ "line": 432
11225
11411
  },
11226
11412
  "name": "grantRead",
11227
11413
  "overrides": "cdk-glue-iceberg-table.IIcebergTable",
@@ -11246,7 +11432,7 @@
11246
11432
  },
11247
11433
  "locationInModule": {
11248
11434
  "filename": "lib/iceberg/iceberg-table.ts",
11249
- "line": 463
11435
+ "line": 460
11250
11436
  },
11251
11437
  "name": "grantReadWrite",
11252
11438
  "overrides": "cdk-glue-iceberg-table.IIcebergTable",
@@ -11271,7 +11457,7 @@
11271
11457
  },
11272
11458
  "locationInModule": {
11273
11459
  "filename": "lib/iceberg/iceberg-table.ts",
11274
- "line": 449
11460
+ "line": 446
11275
11461
  },
11276
11462
  "name": "grantWrite",
11277
11463
  "overrides": "cdk-glue-iceberg-table.IIcebergTable",
@@ -11300,7 +11486,7 @@
11300
11486
  "immutable": true,
11301
11487
  "locationInModule": {
11302
11488
  "filename": "lib/iceberg/iceberg-table.ts",
11303
- "line": 265
11489
+ "line": 262
11304
11490
  },
11305
11491
  "name": "database",
11306
11492
  "overrides": "cdk-glue-iceberg-table.IIcebergTable",
@@ -11316,7 +11502,7 @@
11316
11502
  "immutable": true,
11317
11503
  "locationInModule": {
11318
11504
  "filename": "lib/iceberg/iceberg-table.ts",
11319
- "line": 271
11505
+ "line": 268
11320
11506
  },
11321
11507
  "name": "dataFormat",
11322
11508
  "type": {
@@ -11331,7 +11517,7 @@
11331
11517
  "immutable": true,
11332
11518
  "locationInModule": {
11333
11519
  "filename": "lib/iceberg/iceberg-table.ts",
11334
- "line": 274
11520
+ "line": 271
11335
11521
  },
11336
11522
  "name": "formatVersion",
11337
11523
  "type": {
@@ -11346,7 +11532,7 @@
11346
11532
  "immutable": true,
11347
11533
  "locationInModule": {
11348
11534
  "filename": "lib/iceberg/iceberg-table.ts",
11349
- "line": 268
11535
+ "line": 265
11350
11536
  },
11351
11537
  "name": "location",
11352
11538
  "overrides": "cdk-glue-iceberg-table.IIcebergTable",
@@ -11362,7 +11548,7 @@
11362
11548
  "immutable": true,
11363
11549
  "locationInModule": {
11364
11550
  "filename": "lib/iceberg/iceberg-table.ts",
11365
- "line": 277
11551
+ "line": 274
11366
11552
  },
11367
11553
  "name": "resource",
11368
11554
  "type": {
@@ -11377,7 +11563,7 @@
11377
11563
  "immutable": true,
11378
11564
  "locationInModule": {
11379
11565
  "filename": "lib/iceberg/iceberg-table.ts",
11380
- "line": 259
11566
+ "line": 256
11381
11567
  },
11382
11568
  "name": "tableArn",
11383
11569
  "overrides": "cdk-glue-iceberg-table.IIcebergTable",
@@ -11393,7 +11579,7 @@
11393
11579
  "immutable": true,
11394
11580
  "locationInModule": {
11395
11581
  "filename": "lib/iceberg/iceberg-table.ts",
11396
- "line": 262
11582
+ "line": 259
11397
11583
  },
11398
11584
  "name": "tableName",
11399
11585
  "overrides": "cdk-glue-iceberg-table.IIcebergTable",
@@ -11415,7 +11601,7 @@
11415
11601
  "kind": "interface",
11416
11602
  "locationInModule": {
11417
11603
  "filename": "lib/iceberg/iceberg-table.ts",
11418
- "line": 487
11604
+ "line": 484
11419
11605
  },
11420
11606
  "name": "IcebergTableAttributes",
11421
11607
  "properties": [
@@ -11428,7 +11614,7 @@
11428
11614
  "immutable": true,
11429
11615
  "locationInModule": {
11430
11616
  "filename": "lib/iceberg/iceberg-table.ts",
11431
- "line": 489
11617
+ "line": 486
11432
11618
  },
11433
11619
  "name": "database",
11434
11620
  "type": {
@@ -11444,7 +11630,7 @@
11444
11630
  "immutable": true,
11445
11631
  "locationInModule": {
11446
11632
  "filename": "lib/iceberg/iceberg-table.ts",
11447
- "line": 495
11633
+ "line": 492
11448
11634
  },
11449
11635
  "name": "location",
11450
11636
  "type": {
@@ -11460,7 +11646,7 @@
11460
11646
  "immutable": true,
11461
11647
  "locationInModule": {
11462
11648
  "filename": "lib/iceberg/iceberg-table.ts",
11463
- "line": 492
11649
+ "line": 489
11464
11650
  },
11465
11651
  "name": "tableName",
11466
11652
  "type": {
@@ -11481,7 +11667,7 @@
11481
11667
  "kind": "interface",
11482
11668
  "locationInModule": {
11483
11669
  "filename": "lib/iceberg/iceberg-table.ts",
11484
- "line": 159
11670
+ "line": 153
11485
11671
  },
11486
11672
  "name": "IcebergTableProps",
11487
11673
  "properties": [
@@ -11495,7 +11681,7 @@
11495
11681
  "immutable": true,
11496
11682
  "locationInModule": {
11497
11683
  "filename": "lib/iceberg/iceberg-table.ts",
11498
- "line": 167
11684
+ "line": 161
11499
11685
  },
11500
11686
  "name": "columns",
11501
11687
  "type": {
@@ -11516,7 +11702,7 @@
11516
11702
  "immutable": true,
11517
11703
  "locationInModule": {
11518
11704
  "filename": "lib/iceberg/iceberg-table.ts",
11519
- "line": 161
11705
+ "line": 155
11520
11706
  },
11521
11707
  "name": "database",
11522
11708
  "type": {
@@ -11533,7 +11719,7 @@
11533
11719
  "immutable": true,
11534
11720
  "locationInModule": {
11535
11721
  "filename": "lib/iceberg/iceberg-table.ts",
11536
- "line": 189
11722
+ "line": 186
11537
11723
  },
11538
11724
  "name": "formatVersion",
11539
11725
  "type": {
@@ -11550,7 +11736,7 @@
11550
11736
  "immutable": true,
11551
11737
  "locationInModule": {
11552
11738
  "filename": "lib/iceberg/iceberg-table.ts",
11553
- "line": 170
11739
+ "line": 164
11554
11740
  },
11555
11741
  "name": "location",
11556
11742
  "type": {
@@ -11566,7 +11752,7 @@
11566
11752
  "immutable": true,
11567
11753
  "locationInModule": {
11568
11754
  "filename": "lib/iceberg/iceberg-table.ts",
11569
- "line": 164
11755
+ "line": 158
11570
11756
  },
11571
11757
  "name": "tableName",
11572
11758
  "type": {
@@ -11583,7 +11769,7 @@
11583
11769
  "immutable": true,
11584
11770
  "locationInModule": {
11585
11771
  "filename": "lib/iceberg/iceberg-table.ts",
11586
- "line": 209
11772
+ "line": 206
11587
11773
  },
11588
11774
  "name": "comment",
11589
11775
  "optional": true,
@@ -11601,7 +11787,7 @@
11601
11787
  "immutable": true,
11602
11788
  "locationInModule": {
11603
11789
  "filename": "lib/iceberg/iceberg-table.ts",
11604
- "line": 186
11790
+ "line": 183
11605
11791
  },
11606
11792
  "name": "dataFormat",
11607
11793
  "optional": true,
@@ -11612,14 +11798,14 @@
11612
11798
  {
11613
11799
  "abstract": true,
11614
11800
  "docs": {
11615
- "remarks": "Maps to\n`IcebergSchema.identifierFieldIds`. Per the Iceberg spec these\nmust be primitive, non-nullable, non-floating-point fields.",
11801
+ "remarks": "Maps to\n`IcebergSchema.identifierFieldIds`. Per the Iceberg spec these\nmust be primitive, non-nullable, non-floating-point fields; an\noptional column is rejected at synth. The construct prefixes each\nidentifier column's `doc` with `(PK) `, so no column's own `doc`\nmay start with that prefix.",
11616
11802
  "stability": "experimental",
11617
11803
  "summary": "Names of columns that together identify a row."
11618
11804
  },
11619
11805
  "immutable": true,
11620
11806
  "locationInModule": {
11621
11807
  "filename": "lib/iceberg/iceberg-table.ts",
11622
- "line": 183
11808
+ "line": 180
11623
11809
  },
11624
11810
  "name": "identifierFieldNames",
11625
11811
  "optional": true,
@@ -11642,7 +11828,7 @@
11642
11828
  "immutable": true,
11643
11829
  "locationInModule": {
11644
11830
  "filename": "lib/iceberg/iceberg-table.ts",
11645
- "line": 173
11831
+ "line": 167
11646
11832
  },
11647
11833
  "name": "partitionSpec",
11648
11834
  "optional": true,
@@ -11665,7 +11851,7 @@
11665
11851
  "immutable": true,
11666
11852
  "locationInModule": {
11667
11853
  "filename": "lib/iceberg/iceberg-table.ts",
11668
- "line": 216
11854
+ "line": 213
11669
11855
  },
11670
11856
  "name": "removalPolicy",
11671
11857
  "optional": true,
@@ -11683,7 +11869,7 @@
11683
11869
  "immutable": true,
11684
11870
  "locationInModule": {
11685
11871
  "filename": "lib/iceberg/iceberg-table.ts",
11686
- "line": 176
11872
+ "line": 170
11687
11873
  },
11688
11874
  "name": "sortOrder",
11689
11875
  "optional": true,
@@ -11706,7 +11892,7 @@
11706
11892
  "immutable": true,
11707
11893
  "locationInModule": {
11708
11894
  "filename": "lib/iceberg/iceberg-table.ts",
11709
- "line": 198
11895
+ "line": 195
11710
11896
  },
11711
11897
  "name": "tableProperties",
11712
11898
  "optional": true,
@@ -11736,7 +11922,7 @@
11736
11922
  },
11737
11923
  "locationInModule": {
11738
11924
  "filename": "lib/iceberg/iceberg-type.ts",
11739
- "line": 340
11925
+ "line": 373
11740
11926
  },
11741
11927
  "parameters": [
11742
11928
  {
@@ -11750,7 +11936,7 @@
11750
11936
  "kind": "class",
11751
11937
  "locationInModule": {
11752
11938
  "filename": "lib/iceberg/iceberg-type.ts",
11753
- "line": 134
11939
+ "line": 158
11754
11940
  },
11755
11941
  "methods": [
11756
11942
  {
@@ -11760,7 +11946,7 @@
11760
11946
  },
11761
11947
  "locationInModule": {
11762
11948
  "filename": "lib/iceberg/iceberg-type.ts",
11763
- "line": 222
11949
+ "line": 246
11764
11950
  },
11765
11951
  "name": "decimal",
11766
11952
  "parameters": [
@@ -11797,7 +11983,7 @@
11797
11983
  },
11798
11984
  "locationInModule": {
11799
11985
  "filename": "lib/iceberg/iceberg-type.ts",
11800
- "line": 234
11986
+ "line": 258
11801
11987
  },
11802
11988
  "name": "fixed",
11803
11989
  "parameters": [
@@ -11826,7 +12012,7 @@
11826
12012
  },
11827
12013
  "locationInModule": {
11828
12014
  "filename": "lib/iceberg/iceberg-type.ts",
11829
- "line": 296
12015
+ "line": 320
11830
12016
  },
11831
12017
  "name": "geography",
11832
12018
  "parameters": [
@@ -11868,7 +12054,7 @@
11868
12054
  },
11869
12055
  "locationInModule": {
11870
12056
  "filename": "lib/iceberg/iceberg-type.ts",
11871
- "line": 284
12057
+ "line": 308
11872
12058
  },
11873
12059
  "name": "geometry",
11874
12060
  "parameters": [
@@ -11898,28 +12084,17 @@
11898
12084
  },
11899
12085
  "locationInModule": {
11900
12086
  "filename": "lib/iceberg/iceberg-type.ts",
11901
- "line": 246
12087
+ "line": 269
11902
12088
  },
11903
12089
  "name": "list",
11904
12090
  "parameters": [
11905
12091
  {
11906
12092
  "docs": {
11907
- "summary": "Element type."
11908
- },
11909
- "name": "element",
11910
- "type": {
11911
- "fqn": "cdk-glue-iceberg-table.IcebergType"
11912
- }
11913
- },
11914
- {
11915
- "docs": {
11916
- "remarks": "Defaults to `true` (non-null).",
11917
- "summary": "Whether elements are non-nullable."
12093
+ "summary": "Element type, element id, and element nullability."
11918
12094
  },
11919
- "name": "elementRequired",
11920
- "optional": true,
12095
+ "name": "definition",
11921
12096
  "type": {
11922
- "primitive": "boolean"
12097
+ "fqn": "cdk-glue-iceberg-table.IcebergListDefinition"
11923
12098
  }
11924
12099
  }
11925
12100
  ],
@@ -11932,43 +12107,22 @@
11932
12107
  },
11933
12108
  {
11934
12109
  "docs": {
11935
- "remarks": "Keys are always required per the Iceberg spec.",
11936
12110
  "stability": "experimental",
11937
12111
  "summary": "Key/value map."
11938
12112
  },
11939
12113
  "locationInModule": {
11940
12114
  "filename": "lib/iceberg/iceberg-type.ts",
11941
- "line": 260
12115
+ "line": 282
11942
12116
  },
11943
12117
  "name": "map",
11944
12118
  "parameters": [
11945
12119
  {
11946
12120
  "docs": {
11947
- "summary": "Key type."
11948
- },
11949
- "name": "key",
11950
- "type": {
11951
- "fqn": "cdk-glue-iceberg-table.IcebergType"
11952
- }
11953
- },
11954
- {
11955
- "docs": {
11956
- "summary": "Value type."
12121
+ "summary": "Key and value types, their ids, and value nullability."
11957
12122
  },
11958
- "name": "value",
12123
+ "name": "definition",
11959
12124
  "type": {
11960
- "fqn": "cdk-glue-iceberg-table.IcebergType"
11961
- }
11962
- },
11963
- {
11964
- "docs": {
11965
- "remarks": "Defaults to `true` (non-null).",
11966
- "summary": "Whether values are non-nullable."
11967
- },
11968
- "name": "valueRequired",
11969
- "optional": true,
11970
- "type": {
11971
- "primitive": "boolean"
12125
+ "fqn": "cdk-glue-iceberg-table.IcebergMapDefinition"
11972
12126
  }
11973
12127
  }
11974
12128
  ],
@@ -11986,13 +12140,13 @@
11986
12140
  },
11987
12141
  "locationInModule": {
11988
12142
  "filename": "lib/iceberg/iceberg-type.ts",
11989
- "line": 273
12143
+ "line": 297
11990
12144
  },
11991
12145
  "name": "struct",
11992
12146
  "parameters": [
11993
12147
  {
11994
12148
  "docs": {
11995
- "summary": "Struct fields (each carries a name, type, required flag, optional doc)."
12149
+ "summary": "Struct fields (each carries an id, name, type, required flag, optional doc)."
11996
12150
  },
11997
12151
  "name": "fields",
11998
12152
  "type": {
@@ -12019,7 +12173,7 @@
12019
12173
  },
12020
12174
  "locationInModule": {
12021
12175
  "filename": "lib/iceberg/iceberg-type.ts",
12022
- "line": 547
12176
+ "line": 575
12023
12177
  },
12024
12178
  "name": "isDecimal",
12025
12179
  "returns": {
@@ -12035,7 +12189,7 @@
12035
12189
  },
12036
12190
  "locationInModule": {
12037
12191
  "filename": "lib/iceberg/iceberg-type.ts",
12038
- "line": 552
12192
+ "line": 580
12039
12193
  },
12040
12194
  "name": "isFixed",
12041
12195
  "returns": {
@@ -12051,7 +12205,7 @@
12051
12205
  },
12052
12206
  "locationInModule": {
12053
12207
  "filename": "lib/iceberg/iceberg-type.ts",
12054
- "line": 542
12208
+ "line": 570
12055
12209
  },
12056
12210
  "name": "isPrimitive",
12057
12211
  "parameters": [
@@ -12080,7 +12234,7 @@
12080
12234
  "immutable": true,
12081
12235
  "locationInModule": {
12082
12236
  "filename": "lib/iceberg/iceberg-type.ts",
12083
- "line": 193
12237
+ "line": 217
12084
12238
  },
12085
12239
  "name": "BINARY",
12086
12240
  "static": true,
@@ -12097,7 +12251,7 @@
12097
12251
  "immutable": true,
12098
12252
  "locationInModule": {
12099
12253
  "filename": "lib/iceberg/iceberg-type.ts",
12100
- "line": 138
12254
+ "line": 162
12101
12255
  },
12102
12256
  "name": "BOOLEAN",
12103
12257
  "static": true,
@@ -12114,7 +12268,7 @@
12114
12268
  "immutable": true,
12115
12269
  "locationInModule": {
12116
12270
  "filename": "lib/iceberg/iceberg-type.ts",
12117
- "line": 163
12271
+ "line": 187
12118
12272
  },
12119
12273
  "name": "DATE",
12120
12274
  "static": true,
@@ -12131,7 +12285,7 @@
12131
12285
  "immutable": true,
12132
12286
  "locationInModule": {
12133
12287
  "filename": "lib/iceberg/iceberg-type.ts",
12134
- "line": 158
12288
+ "line": 182
12135
12289
  },
12136
12290
  "name": "DOUBLE",
12137
12291
  "static": true,
@@ -12148,7 +12302,7 @@
12148
12302
  "immutable": true,
12149
12303
  "locationInModule": {
12150
12304
  "filename": "lib/iceberg/iceberg-type.ts",
12151
- "line": 153
12305
+ "line": 177
12152
12306
  },
12153
12307
  "name": "FLOAT",
12154
12308
  "static": true,
@@ -12165,7 +12319,7 @@
12165
12319
  "immutable": true,
12166
12320
  "locationInModule": {
12167
12321
  "filename": "lib/iceberg/iceberg-type.ts",
12168
- "line": 143
12322
+ "line": 167
12169
12323
  },
12170
12324
  "name": "INT",
12171
12325
  "static": true,
@@ -12182,7 +12336,7 @@
12182
12336
  "immutable": true,
12183
12337
  "locationInModule": {
12184
12338
  "filename": "lib/iceberg/iceberg-type.ts",
12185
- "line": 148
12339
+ "line": 172
12186
12340
  },
12187
12341
  "name": "LONG",
12188
12342
  "static": true,
@@ -12199,7 +12353,7 @@
12199
12353
  "immutable": true,
12200
12354
  "locationInModule": {
12201
12355
  "filename": "lib/iceberg/iceberg-type.ts",
12202
- "line": 183
12356
+ "line": 207
12203
12357
  },
12204
12358
  "name": "STRING",
12205
12359
  "static": true,
@@ -12216,7 +12370,7 @@
12216
12370
  "immutable": true,
12217
12371
  "locationInModule": {
12218
12372
  "filename": "lib/iceberg/iceberg-type.ts",
12219
- "line": 168
12373
+ "line": 192
12220
12374
  },
12221
12375
  "name": "TIME",
12222
12376
  "static": true,
@@ -12233,7 +12387,7 @@
12233
12387
  "immutable": true,
12234
12388
  "locationInModule": {
12235
12389
  "filename": "lib/iceberg/iceberg-type.ts",
12236
- "line": 173
12390
+ "line": 197
12237
12391
  },
12238
12392
  "name": "TIMESTAMP",
12239
12393
  "static": true,
@@ -12251,7 +12405,7 @@
12251
12405
  "immutable": true,
12252
12406
  "locationInModule": {
12253
12407
  "filename": "lib/iceberg/iceberg-type.ts",
12254
- "line": 203
12408
+ "line": 227
12255
12409
  },
12256
12410
  "name": "TIMESTAMP_NS",
12257
12411
  "static": true,
@@ -12268,7 +12422,7 @@
12268
12422
  "immutable": true,
12269
12423
  "locationInModule": {
12270
12424
  "filename": "lib/iceberg/iceberg-type.ts",
12271
- "line": 178
12425
+ "line": 202
12272
12426
  },
12273
12427
  "name": "TIMESTAMPTZ",
12274
12428
  "static": true,
@@ -12286,7 +12440,7 @@
12286
12440
  "immutable": true,
12287
12441
  "locationInModule": {
12288
12442
  "filename": "lib/iceberg/iceberg-type.ts",
12289
- "line": 208
12443
+ "line": 232
12290
12444
  },
12291
12445
  "name": "TIMESTAMPTZ_NS",
12292
12446
  "static": true,
@@ -12304,7 +12458,7 @@
12304
12458
  "immutable": true,
12305
12459
  "locationInModule": {
12306
12460
  "filename": "lib/iceberg/iceberg-type.ts",
12307
- "line": 198
12461
+ "line": 222
12308
12462
  },
12309
12463
  "name": "UNKNOWN",
12310
12464
  "static": true,
@@ -12321,7 +12475,7 @@
12321
12475
  "immutable": true,
12322
12476
  "locationInModule": {
12323
12477
  "filename": "lib/iceberg/iceberg-type.ts",
12324
- "line": 188
12478
+ "line": 212
12325
12479
  },
12326
12480
  "name": "UUID",
12327
12481
  "static": true,
@@ -12339,7 +12493,7 @@
12339
12493
  "immutable": true,
12340
12494
  "locationInModule": {
12341
12495
  "filename": "lib/iceberg/iceberg-type.ts",
12342
- "line": 213
12496
+ "line": 237
12343
12497
  },
12344
12498
  "name": "VARIANT",
12345
12499
  "static": true,
@@ -12355,7 +12509,7 @@
12355
12509
  "immutable": true,
12356
12510
  "locationInModule": {
12357
12511
  "filename": "lib/iceberg/iceberg-type.ts",
12358
- "line": 305
12512
+ "line": 329
12359
12513
  },
12360
12514
  "name": "kind",
12361
12515
  "type": {
@@ -12370,7 +12524,7 @@
12370
12524
  "immutable": true,
12371
12525
  "locationInModule": {
12372
12526
  "filename": "lib/iceberg/iceberg-type.ts",
12373
- "line": 308
12527
+ "line": 332
12374
12528
  },
12375
12529
  "name": "decimalPrecision",
12376
12530
  "optional": true,
@@ -12386,7 +12540,7 @@
12386
12540
  "immutable": true,
12387
12541
  "locationInModule": {
12388
12542
  "filename": "lib/iceberg/iceberg-type.ts",
12389
- "line": 311
12543
+ "line": 335
12390
12544
  },
12391
12545
  "name": "decimalScale",
12392
12546
  "optional": true,
@@ -12402,7 +12556,7 @@
12402
12556
  "immutable": true,
12403
12557
  "locationInModule": {
12404
12558
  "filename": "lib/iceberg/iceberg-type.ts",
12405
- "line": 314
12559
+ "line": 338
12406
12560
  },
12407
12561
  "name": "fixedLength",
12408
12562
  "optional": true,
@@ -12418,7 +12572,7 @@
12418
12572
  "immutable": true,
12419
12573
  "locationInModule": {
12420
12574
  "filename": "lib/iceberg/iceberg-type.ts",
12421
- "line": 335
12575
+ "line": 368
12422
12576
  },
12423
12577
  "name": "geoCrs",
12424
12578
  "optional": true,
@@ -12434,7 +12588,7 @@
12434
12588
  "immutable": true,
12435
12589
  "locationInModule": {
12436
12590
  "filename": "lib/iceberg/iceberg-type.ts",
12437
- "line": 338
12591
+ "line": 371
12438
12592
  },
12439
12593
  "name": "geographyAlgorithm",
12440
12594
  "optional": true,
@@ -12450,7 +12604,7 @@
12450
12604
  "immutable": true,
12451
12605
  "locationInModule": {
12452
12606
  "filename": "lib/iceberg/iceberg-type.ts",
12453
- "line": 317
12607
+ "line": 341
12454
12608
  },
12455
12609
  "name": "listElement",
12456
12610
  "optional": true,
@@ -12458,6 +12612,22 @@
12458
12612
  "fqn": "cdk-glue-iceberg-table.IcebergType"
12459
12613
  }
12460
12614
  },
12615
+ {
12616
+ "docs": {
12617
+ "stability": "experimental",
12618
+ "summary": "List element field id (set when `kind === LIST`)."
12619
+ },
12620
+ "immutable": true,
12621
+ "locationInModule": {
12622
+ "filename": "lib/iceberg/iceberg-type.ts",
12623
+ "line": 344
12624
+ },
12625
+ "name": "listElementId",
12626
+ "optional": true,
12627
+ "type": {
12628
+ "primitive": "number"
12629
+ }
12630
+ },
12461
12631
  {
12462
12632
  "docs": {
12463
12633
  "stability": "experimental",
@@ -12466,7 +12636,7 @@
12466
12636
  "immutable": true,
12467
12637
  "locationInModule": {
12468
12638
  "filename": "lib/iceberg/iceberg-type.ts",
12469
- "line": 320
12639
+ "line": 347
12470
12640
  },
12471
12641
  "name": "listElementRequired",
12472
12642
  "optional": true,
@@ -12482,7 +12652,7 @@
12482
12652
  "immutable": true,
12483
12653
  "locationInModule": {
12484
12654
  "filename": "lib/iceberg/iceberg-type.ts",
12485
- "line": 323
12655
+ "line": 350
12486
12656
  },
12487
12657
  "name": "mapKey",
12488
12658
  "optional": true,
@@ -12490,6 +12660,22 @@
12490
12660
  "fqn": "cdk-glue-iceberg-table.IcebergType"
12491
12661
  }
12492
12662
  },
12663
+ {
12664
+ "docs": {
12665
+ "stability": "experimental",
12666
+ "summary": "Map key field id (set when `kind === MAP`)."
12667
+ },
12668
+ "immutable": true,
12669
+ "locationInModule": {
12670
+ "filename": "lib/iceberg/iceberg-type.ts",
12671
+ "line": 353
12672
+ },
12673
+ "name": "mapKeyId",
12674
+ "optional": true,
12675
+ "type": {
12676
+ "primitive": "number"
12677
+ }
12678
+ },
12493
12679
  {
12494
12680
  "docs": {
12495
12681
  "stability": "experimental",
@@ -12498,7 +12684,7 @@
12498
12684
  "immutable": true,
12499
12685
  "locationInModule": {
12500
12686
  "filename": "lib/iceberg/iceberg-type.ts",
12501
- "line": 326
12687
+ "line": 356
12502
12688
  },
12503
12689
  "name": "mapValue",
12504
12690
  "optional": true,
@@ -12506,6 +12692,22 @@
12506
12692
  "fqn": "cdk-glue-iceberg-table.IcebergType"
12507
12693
  }
12508
12694
  },
12695
+ {
12696
+ "docs": {
12697
+ "stability": "experimental",
12698
+ "summary": "Map value field id (set when `kind === MAP`)."
12699
+ },
12700
+ "immutable": true,
12701
+ "locationInModule": {
12702
+ "filename": "lib/iceberg/iceberg-type.ts",
12703
+ "line": 359
12704
+ },
12705
+ "name": "mapValueId",
12706
+ "optional": true,
12707
+ "type": {
12708
+ "primitive": "number"
12709
+ }
12710
+ },
12509
12711
  {
12510
12712
  "docs": {
12511
12713
  "stability": "experimental",
@@ -12514,7 +12716,7 @@
12514
12716
  "immutable": true,
12515
12717
  "locationInModule": {
12516
12718
  "filename": "lib/iceberg/iceberg-type.ts",
12517
- "line": 329
12719
+ "line": 362
12518
12720
  },
12519
12721
  "name": "mapValueRequired",
12520
12722
  "optional": true,
@@ -12530,7 +12732,7 @@
12530
12732
  "immutable": true,
12531
12733
  "locationInModule": {
12532
12734
  "filename": "lib/iceberg/iceberg-type.ts",
12533
- "line": 332
12735
+ "line": 365
12534
12736
  },
12535
12737
  "name": "structFields",
12536
12738
  "optional": true,
@@ -12556,7 +12758,7 @@
12556
12758
  "kind": "enum",
12557
12759
  "locationInModule": {
12558
12760
  "filename": "lib/iceberg/iceberg-type.ts",
12559
- "line": 31
12761
+ "line": 13
12560
12762
  },
12561
12763
  "members": [
12562
12764
  {
@@ -12713,7 +12915,7 @@
12713
12915
  "kind": "interface",
12714
12916
  "locationInModule": {
12715
12917
  "filename": "lib/iceberg/iceberg-type.ts",
12716
- "line": 92
12918
+ "line": 107
12717
12919
  },
12718
12920
  "name": "IcebergTypeOptions",
12719
12921
  "properties": [
@@ -12726,7 +12928,7 @@
12726
12928
  "immutable": true,
12727
12929
  "locationInModule": {
12728
12930
  "filename": "lib/iceberg/iceberg-type.ts",
12729
- "line": 94
12931
+ "line": 109
12730
12932
  },
12731
12933
  "name": "kind",
12732
12934
  "type": {
@@ -12742,7 +12944,7 @@
12742
12944
  "immutable": true,
12743
12945
  "locationInModule": {
12744
12946
  "filename": "lib/iceberg/iceberg-type.ts",
12745
- "line": 97
12947
+ "line": 112
12746
12948
  },
12747
12949
  "name": "decimalPrecision",
12748
12950
  "optional": true,
@@ -12759,7 +12961,7 @@
12759
12961
  "immutable": true,
12760
12962
  "locationInModule": {
12761
12963
  "filename": "lib/iceberg/iceberg-type.ts",
12762
- "line": 100
12964
+ "line": 115
12763
12965
  },
12764
12966
  "name": "decimalScale",
12765
12967
  "optional": true,
@@ -12777,7 +12979,7 @@
12777
12979
  "immutable": true,
12778
12980
  "locationInModule": {
12779
12981
  "filename": "lib/iceberg/iceberg-type.ts",
12780
- "line": 103
12982
+ "line": 118
12781
12983
  },
12782
12984
  "name": "fixedLength",
12783
12985
  "optional": true,
@@ -12795,7 +12997,7 @@
12795
12997
  "immutable": true,
12796
12998
  "locationInModule": {
12797
12999
  "filename": "lib/iceberg/iceberg-type.ts",
12798
- "line": 124
13000
+ "line": 148
12799
13001
  },
12800
13002
  "name": "geoCrs",
12801
13003
  "optional": true,
@@ -12813,7 +13015,7 @@
12813
13015
  "immutable": true,
12814
13016
  "locationInModule": {
12815
13017
  "filename": "lib/iceberg/iceberg-type.ts",
12816
- "line": 127
13018
+ "line": 151
12817
13019
  },
12818
13020
  "name": "geographyAlgorithm",
12819
13021
  "optional": true,
@@ -12831,7 +13033,7 @@
12831
13033
  "immutable": true,
12832
13034
  "locationInModule": {
12833
13035
  "filename": "lib/iceberg/iceberg-type.ts",
12834
- "line": 106
13036
+ "line": 121
12835
13037
  },
12836
13038
  "name": "listElement",
12837
13039
  "optional": true,
@@ -12842,14 +13044,32 @@
12842
13044
  {
12843
13045
  "abstract": true,
12844
13046
  "docs": {
12845
- "remarks": "Defaults to `true`.",
13047
+ "remarks": "Checked by `IcebergTable`.",
13048
+ "stability": "experimental",
13049
+ "summary": "Element field id."
13050
+ },
13051
+ "immutable": true,
13052
+ "locationInModule": {
13053
+ "filename": "lib/iceberg/iceberg-type.ts",
13054
+ "line": 124
13055
+ },
13056
+ "name": "listElementId",
13057
+ "optional": true,
13058
+ "type": {
13059
+ "primitive": "number"
13060
+ }
13061
+ },
13062
+ {
13063
+ "abstract": true,
13064
+ "docs": {
13065
+ "remarks": "Defaults to `false`.",
12846
13066
  "stability": "experimental",
12847
13067
  "summary": "Whether list elements are non-nullable."
12848
13068
  },
12849
13069
  "immutable": true,
12850
13070
  "locationInModule": {
12851
13071
  "filename": "lib/iceberg/iceberg-type.ts",
12852
- "line": 109
13072
+ "line": 127
12853
13073
  },
12854
13074
  "name": "listElementRequired",
12855
13075
  "optional": true,
@@ -12867,7 +13087,7 @@
12867
13087
  "immutable": true,
12868
13088
  "locationInModule": {
12869
13089
  "filename": "lib/iceberg/iceberg-type.ts",
12870
- "line": 112
13090
+ "line": 130
12871
13091
  },
12872
13092
  "name": "mapKey",
12873
13093
  "optional": true,
@@ -12875,6 +13095,24 @@
12875
13095
  "fqn": "cdk-glue-iceberg-table.IcebergType"
12876
13096
  }
12877
13097
  },
13098
+ {
13099
+ "abstract": true,
13100
+ "docs": {
13101
+ "remarks": "Checked by `IcebergTable`.",
13102
+ "stability": "experimental",
13103
+ "summary": "Map key field id."
13104
+ },
13105
+ "immutable": true,
13106
+ "locationInModule": {
13107
+ "filename": "lib/iceberg/iceberg-type.ts",
13108
+ "line": 133
13109
+ },
13110
+ "name": "mapKeyId",
13111
+ "optional": true,
13112
+ "type": {
13113
+ "primitive": "number"
13114
+ }
13115
+ },
12878
13116
  {
12879
13117
  "abstract": true,
12880
13118
  "docs": {
@@ -12885,7 +13123,7 @@
12885
13123
  "immutable": true,
12886
13124
  "locationInModule": {
12887
13125
  "filename": "lib/iceberg/iceberg-type.ts",
12888
- "line": 115
13126
+ "line": 136
12889
13127
  },
12890
13128
  "name": "mapValue",
12891
13129
  "optional": true,
@@ -12896,14 +13134,32 @@
12896
13134
  {
12897
13135
  "abstract": true,
12898
13136
  "docs": {
12899
- "remarks": "Defaults to `true`.",
13137
+ "remarks": "Checked by `IcebergTable`.",
13138
+ "stability": "experimental",
13139
+ "summary": "Map value field id."
13140
+ },
13141
+ "immutable": true,
13142
+ "locationInModule": {
13143
+ "filename": "lib/iceberg/iceberg-type.ts",
13144
+ "line": 139
13145
+ },
13146
+ "name": "mapValueId",
13147
+ "optional": true,
13148
+ "type": {
13149
+ "primitive": "number"
13150
+ }
13151
+ },
13152
+ {
13153
+ "abstract": true,
13154
+ "docs": {
13155
+ "remarks": "Defaults to `false`.",
12900
13156
  "stability": "experimental",
12901
13157
  "summary": "Whether map values are non-nullable."
12902
13158
  },
12903
13159
  "immutable": true,
12904
13160
  "locationInModule": {
12905
13161
  "filename": "lib/iceberg/iceberg-type.ts",
12906
- "line": 118
13162
+ "line": 142
12907
13163
  },
12908
13164
  "name": "mapValueRequired",
12909
13165
  "optional": true,
@@ -12921,7 +13177,7 @@
12921
13177
  "immutable": true,
12922
13178
  "locationInModule": {
12923
13179
  "filename": "lib/iceberg/iceberg-type.ts",
12924
- "line": 121
13180
+ "line": 145
12925
13181
  },
12926
13182
  "name": "structFields",
12927
13183
  "optional": true,
@@ -12938,6 +13194,6 @@
12938
13194
  "symbolId": "lib/iceberg/iceberg-type:IcebergTypeOptions"
12939
13195
  }
12940
13196
  },
12941
- "version": "0.10.2",
12942
- "fingerprint": "Ar/EvDNczhisSfJXjzifZh3n7A9a9Ucef30oNZRhlWU="
13197
+ "version": "0.12.0",
13198
+ "fingerprint": "BVPUg5AHM6eqgtl5oOA6VFaXYLPm9MrB2eqV/wxx41Q="
12943
13199
  }