cdk-glue-iceberg-table 0.7.4 → 0.9.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[![types](https://img.shields.io/npm/types/cdk-glue-iceberg-table.svg)](https://www.npmjs.com/package/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[![last commit](https://img.shields.io/github/last-commit/ksco92/arceus.svg)](https://github.com/ksco92/arceus/commits/main)\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 the AWS CDK L2 construct for creating\nand evolving Apache Iceberg tables in the AWS Glue Data Catalog.** It\nemits the exact `AWS::Glue::Table` / `OpenTableFormatInput` shape that\nsurvives a CloudFormation `Update`, so a single `cdk deploy` creates a\ntable, evolves its schema and partitions, and destroys it, the same\nlifecycle CDK gives any other resource. No custom resource, no Lambda,\nno \"`cdk deploy` and then run this SQL by hand\" two-step. Table\nchanges (new columns, renames, drops, new partition fields) land as\na reviewed diff in a pull request and apply through `cdk deploy`.\n\nStatus (October 2026): published on npm (TypeScript/JavaScript) and PyPI\n(Python), pre-1.0, with a public surface guarded by an end-to-end\nconsumer test on every PR plus three real-AWS integration suites. The\nmulti-language packages are generated from one TypeScript source with\n[jsii](https://aws.github.io/jsii/) and indexed on\n[Construct Hub](https://constructs.dev/packages/cdk-glue-iceberg-table).\nDeveloped in the\n[`ksco92/arceus`](https://github.com/ksco92/arceus) monorepo, which\nalso holds a CDK demo app that dogfoods the construct against a real\nAWS 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 / 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- [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 everything 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 plus `list` / `map` / `struct` / `decimal` / `fixed` factories. Renders to the JSON shape 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, required — set explicitly per table), **`IcebergSortDirection`**, **`IcebergNullOrder`**, 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### 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.** The `formatVersion` prop is read once at table creation; changing it later requires a destroy + recreate.\n- **`merge-on-read` requires v2.** The construct rejects `write.{delete,update,merge}.mode = merge-on-read` on a v1 table at synth time.\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. The demo app in the [`arceus`](https://github.com/ksco92/arceus)\nrepo registers the tables with Lake Formation and queries them from\nAthena, including v2 merge-on-read `INSERT` / `UPDATE` / `DELETE` /\n`MERGE`, time travel, `OPTIMIZE`, and `VACUUM`. The construct's\n`grant*` helpers issue IAM grants; under Lake Formation you still add\nthe matching `SELECT` / `INSERT` LF grants. See [Granting\naccess](#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## 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[![types](https://img.shields.io/npm/types/cdk-glue-iceberg-table.svg)](https://www.npmjs.com/package/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[![last commit](https://img.shields.io/github/last-commit/ksco92/arceus.svg)](https://github.com/ksco92/arceus/commits/main)\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 the AWS CDK L2 construct for creating\nand evolving Apache Iceberg tables in the AWS Glue Data Catalog.** It\nemits the exact `AWS::Glue::Table` / `OpenTableFormatInput` shape that\nsurvives a CloudFormation `Update`, so a single `cdk deploy` creates a\ntable, evolves its schema and partitions, and destroys it, the same\nlifecycle CDK gives any other resource. No custom resource, no Lambda,\nno \"`cdk deploy` and then run this SQL by hand\" two-step. Table\nchanges (new columns, renames, drops, new partition fields) land as\na reviewed diff in a pull request and apply through `cdk deploy`.\n\nStatus (October 2026): published on npm (TypeScript/JavaScript) and PyPI\n(Python), pre-1.0, with a public surface guarded by an end-to-end\nconsumer test on every PR plus three real-AWS integration suites. The\nmulti-language packages are generated from one TypeScript source with\n[jsii](https://aws.github.io/jsii/) and indexed on\n[Construct Hub](https://constructs.dev/packages/cdk-glue-iceberg-table).\nDeveloped in the\n[`ksco92/arceus`](https://github.com/ksco92/arceus) monorepo, which\nalso holds a CDK demo app that dogfoods the construct against a real\nAWS 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 / 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- [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 everything 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 (including the v3 `UNKNOWN`, `TIMESTAMP_NS`, `TIMESTAMPTZ_NS`, and `VARIANT`) plus `list` / `map` / `struct` / `decimal` / `fixed` / `geometry` / `geography` factories. Renders to the JSON shape 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`** (for `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### 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.** The `formatVersion` prop is read once at table creation; changing it later requires a destroy + recreate.\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- **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. The demo app in the [`arceus`](https://github.com/ksco92/arceus)\nrepo registers the tables with Lake Formation and queries them from\nAthena, including v2 merge-on-read `INSERT` / `UPDATE` / `DELETE` /\n`MERGE`, time travel, `OPTIMIZE`, and `VACUUM`. The construct's\n`grant*` helpers issue IAM grants; under Lake Formation you still add\nthe matching `SELECT` / `INSERT` LF grants. See [Granting\naccess](#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## 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",
@@ -10039,7 +10039,7 @@
10039
10039
  "kind": "enum",
10040
10040
  "locationInModule": {
10041
10041
  "filename": "lib/iceberg/iceberg-table-properties.ts",
10042
- "line": 23
10042
+ "line": 26
10043
10043
  },
10044
10044
  "members": [
10045
10045
  {
@@ -10067,6 +10067,53 @@
10067
10067
  "name": "IcebergDataFormat",
10068
10068
  "symbolId": "lib/iceberg/iceberg-table-properties:IcebergDataFormat"
10069
10069
  },
10070
+ "cdk-glue-iceberg-table.IcebergEdgeAlgorithm": {
10071
+ "assembly": "cdk-glue-iceberg-table",
10072
+ "docs": {
10073
+ "stability": "experimental",
10074
+ "summary": "Edge-interpolation algorithm of a `geography` type."
10075
+ },
10076
+ "fqn": "cdk-glue-iceberg-table.IcebergEdgeAlgorithm",
10077
+ "kind": "enum",
10078
+ "locationInModule": {
10079
+ "filename": "lib/iceberg/iceberg-type.ts",
10080
+ "line": 58
10081
+ },
10082
+ "members": [
10083
+ {
10084
+ "docs": {
10085
+ "stability": "experimental"
10086
+ },
10087
+ "name": "SPHERICAL"
10088
+ },
10089
+ {
10090
+ "docs": {
10091
+ "stability": "experimental"
10092
+ },
10093
+ "name": "VINCENTY"
10094
+ },
10095
+ {
10096
+ "docs": {
10097
+ "stability": "experimental"
10098
+ },
10099
+ "name": "THOMAS"
10100
+ },
10101
+ {
10102
+ "docs": {
10103
+ "stability": "experimental"
10104
+ },
10105
+ "name": "ANDOYER"
10106
+ },
10107
+ {
10108
+ "docs": {
10109
+ "stability": "experimental"
10110
+ },
10111
+ "name": "KARNEY"
10112
+ }
10113
+ ],
10114
+ "name": "IcebergEdgeAlgorithm",
10115
+ "symbolId": "lib/iceberg/iceberg-type:IcebergEdgeAlgorithm"
10116
+ },
10070
10117
  "cdk-glue-iceberg-table.IcebergFormatVersion": {
10071
10118
  "assembly": "cdk-glue-iceberg-table",
10072
10119
  "docs": {
@@ -10094,6 +10141,13 @@
10094
10141
  "summary": "v2 — adds row-level deletes."
10095
10142
  },
10096
10143
  "name": "V2"
10144
+ },
10145
+ {
10146
+ "docs": {
10147
+ "stability": "experimental",
10148
+ "summary": "v3 — adds deletion vectors and row lineage."
10149
+ },
10150
+ "name": "V3"
10097
10151
  }
10098
10152
  ],
10099
10153
  "name": "IcebergFormatVersion",
@@ -10626,7 +10680,7 @@
10626
10680
  "kind": "class",
10627
10681
  "locationInModule": {
10628
10682
  "filename": "lib/iceberg/iceberg-table-properties.ts",
10629
- "line": 35
10683
+ "line": 38
10630
10684
  },
10631
10685
  "name": "IcebergPropertyKeys",
10632
10686
  "properties": [
@@ -10639,7 +10693,7 @@
10639
10693
  "immutable": true,
10640
10694
  "locationInModule": {
10641
10695
  "filename": "lib/iceberg/iceberg-table-properties.ts",
10642
- "line": 76
10696
+ "line": 79
10643
10697
  },
10644
10698
  "name": "COMMIT_RETRY_NUM_RETRIES",
10645
10699
  "static": true,
@@ -10656,7 +10710,7 @@
10656
10710
  "immutable": true,
10657
10711
  "locationInModule": {
10658
10712
  "filename": "lib/iceberg/iceberg-table-properties.ts",
10659
- "line": 37
10713
+ "line": 40
10660
10714
  },
10661
10715
  "name": "FORMAT_VERSION",
10662
10716
  "static": true,
@@ -10673,7 +10727,7 @@
10673
10727
  "immutable": true,
10674
10728
  "locationInModule": {
10675
10729
  "filename": "lib/iceberg/iceberg-table-properties.ts",
10676
- "line": 67
10730
+ "line": 70
10677
10731
  },
10678
10732
  "name": "GC_ENABLED",
10679
10733
  "static": true,
@@ -10690,7 +10744,7 @@
10690
10744
  "immutable": true,
10691
10745
  "locationInModule": {
10692
10746
  "filename": "lib/iceberg/iceberg-table-properties.ts",
10693
- "line": 70
10747
+ "line": 73
10694
10748
  },
10695
10749
  "name": "HISTORY_EXPIRE_MAX_SNAPSHOT_AGE_MS",
10696
10750
  "static": true,
@@ -10707,7 +10761,7 @@
10707
10761
  "immutable": true,
10708
10762
  "locationInModule": {
10709
10763
  "filename": "lib/iceberg/iceberg-table-properties.ts",
10710
- "line": 73
10764
+ "line": 76
10711
10765
  },
10712
10766
  "name": "HISTORY_EXPIRE_MIN_SNAPSHOTS_TO_KEEP",
10713
10767
  "static": true,
@@ -10724,7 +10778,7 @@
10724
10778
  "immutable": true,
10725
10779
  "locationInModule": {
10726
10780
  "filename": "lib/iceberg/iceberg-table-properties.ts",
10727
- "line": 49
10781
+ "line": 52
10728
10782
  },
10729
10783
  "name": "WRITE_AVRO_COMPRESSION_CODEC",
10730
10784
  "static": true,
@@ -10741,7 +10795,7 @@
10741
10795
  "immutable": true,
10742
10796
  "locationInModule": {
10743
10797
  "filename": "lib/iceberg/iceberg-table-properties.ts",
10744
- "line": 55
10798
+ "line": 58
10745
10799
  },
10746
10800
  "name": "WRITE_DELETE_MODE",
10747
10801
  "static": true,
@@ -10758,7 +10812,7 @@
10758
10812
  "immutable": true,
10759
10813
  "locationInModule": {
10760
10814
  "filename": "lib/iceberg/iceberg-table-properties.ts",
10761
- "line": 64
10815
+ "line": 67
10762
10816
  },
10763
10817
  "name": "WRITE_DISTRIBUTION_MODE",
10764
10818
  "static": true,
@@ -10775,7 +10829,7 @@
10775
10829
  "immutable": true,
10776
10830
  "locationInModule": {
10777
10831
  "filename": "lib/iceberg/iceberg-table-properties.ts",
10778
- "line": 40
10832
+ "line": 43
10779
10833
  },
10780
10834
  "name": "WRITE_FORMAT_DEFAULT",
10781
10835
  "static": true,
@@ -10792,7 +10846,7 @@
10792
10846
  "immutable": true,
10793
10847
  "locationInModule": {
10794
10848
  "filename": "lib/iceberg/iceberg-table-properties.ts",
10795
- "line": 61
10849
+ "line": 64
10796
10850
  },
10797
10851
  "name": "WRITE_MERGE_MODE",
10798
10852
  "static": true,
@@ -10809,7 +10863,7 @@
10809
10863
  "immutable": true,
10810
10864
  "locationInModule": {
10811
10865
  "filename": "lib/iceberg/iceberg-table-properties.ts",
10812
- "line": 46
10866
+ "line": 49
10813
10867
  },
10814
10868
  "name": "WRITE_ORC_COMPRESSION_CODEC",
10815
10869
  "static": true,
@@ -10826,7 +10880,7 @@
10826
10880
  "immutable": true,
10827
10881
  "locationInModule": {
10828
10882
  "filename": "lib/iceberg/iceberg-table-properties.ts",
10829
- "line": 43
10883
+ "line": 46
10830
10884
  },
10831
10885
  "name": "WRITE_PARQUET_COMPRESSION_CODEC",
10832
10886
  "static": true,
@@ -10843,7 +10897,7 @@
10843
10897
  "immutable": true,
10844
10898
  "locationInModule": {
10845
10899
  "filename": "lib/iceberg/iceberg-table-properties.ts",
10846
- "line": 52
10900
+ "line": 55
10847
10901
  },
10848
10902
  "name": "WRITE_TARGET_FILE_SIZE_BYTES",
10849
10903
  "static": true,
@@ -10860,7 +10914,7 @@
10860
10914
  "immutable": true,
10861
10915
  "locationInModule": {
10862
10916
  "filename": "lib/iceberg/iceberg-table-properties.ts",
10863
- "line": 58
10917
+ "line": 61
10864
10918
  },
10865
10919
  "name": "WRITE_UPDATE_MODE",
10866
10920
  "static": true,
@@ -11001,7 +11055,7 @@
11001
11055
  "kind": "interface",
11002
11056
  "locationInModule": {
11003
11057
  "filename": "lib/iceberg/iceberg-type.ts",
11004
- "line": 52
11058
+ "line": 70
11005
11059
  },
11006
11060
  "name": "IcebergStructFieldDefinition",
11007
11061
  "properties": [
@@ -11014,7 +11068,7 @@
11014
11068
  "immutable": true,
11015
11069
  "locationInModule": {
11016
11070
  "filename": "lib/iceberg/iceberg-type.ts",
11017
- "line": 54
11071
+ "line": 72
11018
11072
  },
11019
11073
  "name": "name",
11020
11074
  "type": {
@@ -11030,7 +11084,7 @@
11030
11084
  "immutable": true,
11031
11085
  "locationInModule": {
11032
11086
  "filename": "lib/iceberg/iceberg-type.ts",
11033
- "line": 57
11087
+ "line": 75
11034
11088
  },
11035
11089
  "name": "type",
11036
11090
  "type": {
@@ -11046,7 +11100,7 @@
11046
11100
  "immutable": true,
11047
11101
  "locationInModule": {
11048
11102
  "filename": "lib/iceberg/iceberg-type.ts",
11049
- "line": 63
11103
+ "line": 81
11050
11104
  },
11051
11105
  "name": "doc",
11052
11106
  "optional": true,
@@ -11064,7 +11118,7 @@
11064
11118
  "immutable": true,
11065
11119
  "locationInModule": {
11066
11120
  "filename": "lib/iceberg/iceberg-type.ts",
11067
- "line": 60
11121
+ "line": 78
11068
11122
  },
11069
11123
  "name": "required",
11070
11124
  "optional": true,
@@ -11671,7 +11725,7 @@
11671
11725
  "cdk-glue-iceberg-table.IcebergType": {
11672
11726
  "assembly": "cdk-glue-iceberg-table",
11673
11727
  "docs": {
11674
- "remarks": "Use the static factories on this class to construct\nprimitives, decimals, fixed, lists, maps, and structs.",
11728
+ "remarks": "Use the static factories on this class to construct\nprimitives, decimals, fixed, geospatial types, lists, maps, and structs.",
11675
11729
  "stability": "experimental",
11676
11730
  "summary": "Iceberg type."
11677
11731
  },
@@ -11682,7 +11736,7 @@
11682
11736
  },
11683
11737
  "locationInModule": {
11684
11738
  "filename": "lib/iceberg/iceberg-type.ts",
11685
- "line": 266
11739
+ "line": 340
11686
11740
  },
11687
11741
  "parameters": [
11688
11742
  {
@@ -11696,7 +11750,7 @@
11696
11750
  "kind": "class",
11697
11751
  "locationInModule": {
11698
11752
  "filename": "lib/iceberg/iceberg-type.ts",
11699
- "line": 110
11753
+ "line": 134
11700
11754
  },
11701
11755
  "methods": [
11702
11756
  {
@@ -11706,7 +11760,7 @@
11706
11760
  },
11707
11761
  "locationInModule": {
11708
11762
  "filename": "lib/iceberg/iceberg-type.ts",
11709
- "line": 178
11763
+ "line": 222
11710
11764
  },
11711
11765
  "name": "decimal",
11712
11766
  "parameters": [
@@ -11743,7 +11797,7 @@
11743
11797
  },
11744
11798
  "locationInModule": {
11745
11799
  "filename": "lib/iceberg/iceberg-type.ts",
11746
- "line": 190
11800
+ "line": 234
11747
11801
  },
11748
11802
  "name": "fixed",
11749
11803
  "parameters": [
@@ -11764,6 +11818,79 @@
11764
11818
  },
11765
11819
  "static": true
11766
11820
  },
11821
+ {
11822
+ "docs": {
11823
+ "remarks": "Format v3.",
11824
+ "stability": "experimental",
11825
+ "summary": "Geospatial features with edges interpolated by an algorithm."
11826
+ },
11827
+ "locationInModule": {
11828
+ "filename": "lib/iceberg/iceberg-type.ts",
11829
+ "line": 296
11830
+ },
11831
+ "name": "geography",
11832
+ "parameters": [
11833
+ {
11834
+ "docs": {
11835
+ "remarks": "Defaults to `OGC:CRS84`.",
11836
+ "summary": "Coordinate reference system identifier."
11837
+ },
11838
+ "name": "crs",
11839
+ "optional": true,
11840
+ "type": {
11841
+ "primitive": "string"
11842
+ }
11843
+ },
11844
+ {
11845
+ "docs": {
11846
+ "remarks": "Defaults to `SPHERICAL`.",
11847
+ "summary": "Edge-interpolation algorithm."
11848
+ },
11849
+ "name": "algorithm",
11850
+ "optional": true,
11851
+ "type": {
11852
+ "fqn": "cdk-glue-iceberg-table.IcebergEdgeAlgorithm"
11853
+ }
11854
+ }
11855
+ ],
11856
+ "returns": {
11857
+ "type": {
11858
+ "fqn": "cdk-glue-iceberg-table.IcebergType"
11859
+ }
11860
+ },
11861
+ "static": true
11862
+ },
11863
+ {
11864
+ "docs": {
11865
+ "remarks": "Format v3.",
11866
+ "stability": "experimental",
11867
+ "summary": "Geospatial features with linear edges."
11868
+ },
11869
+ "locationInModule": {
11870
+ "filename": "lib/iceberg/iceberg-type.ts",
11871
+ "line": 284
11872
+ },
11873
+ "name": "geometry",
11874
+ "parameters": [
11875
+ {
11876
+ "docs": {
11877
+ "remarks": "Defaults to `OGC:CRS84`.",
11878
+ "summary": "Coordinate reference system identifier, such as `EPSG:3857`."
11879
+ },
11880
+ "name": "crs",
11881
+ "optional": true,
11882
+ "type": {
11883
+ "primitive": "string"
11884
+ }
11885
+ }
11886
+ ],
11887
+ "returns": {
11888
+ "type": {
11889
+ "fqn": "cdk-glue-iceberg-table.IcebergType"
11890
+ }
11891
+ },
11892
+ "static": true
11893
+ },
11767
11894
  {
11768
11895
  "docs": {
11769
11896
  "stability": "experimental",
@@ -11771,7 +11898,7 @@
11771
11898
  },
11772
11899
  "locationInModule": {
11773
11900
  "filename": "lib/iceberg/iceberg-type.ts",
11774
- "line": 202
11901
+ "line": 246
11775
11902
  },
11776
11903
  "name": "list",
11777
11904
  "parameters": [
@@ -11811,7 +11938,7 @@
11811
11938
  },
11812
11939
  "locationInModule": {
11813
11940
  "filename": "lib/iceberg/iceberg-type.ts",
11814
- "line": 216
11941
+ "line": 260
11815
11942
  },
11816
11943
  "name": "map",
11817
11944
  "parameters": [
@@ -11859,7 +11986,7 @@
11859
11986
  },
11860
11987
  "locationInModule": {
11861
11988
  "filename": "lib/iceberg/iceberg-type.ts",
11862
- "line": 229
11989
+ "line": 273
11863
11990
  },
11864
11991
  "name": "struct",
11865
11992
  "parameters": [
@@ -11892,7 +12019,7 @@
11892
12019
  },
11893
12020
  "locationInModule": {
11894
12021
  "filename": "lib/iceberg/iceberg-type.ts",
11895
- "line": 447
12022
+ "line": 547
11896
12023
  },
11897
12024
  "name": "isDecimal",
11898
12025
  "returns": {
@@ -11908,7 +12035,7 @@
11908
12035
  },
11909
12036
  "locationInModule": {
11910
12037
  "filename": "lib/iceberg/iceberg-type.ts",
11911
- "line": 452
12038
+ "line": 552
11912
12039
  },
11913
12040
  "name": "isFixed",
11914
12041
  "returns": {
@@ -11924,7 +12051,7 @@
11924
12051
  },
11925
12052
  "locationInModule": {
11926
12053
  "filename": "lib/iceberg/iceberg-type.ts",
11927
- "line": 442
12054
+ "line": 542
11928
12055
  },
11929
12056
  "name": "isPrimitive",
11930
12057
  "parameters": [
@@ -11953,7 +12080,7 @@
11953
12080
  "immutable": true,
11954
12081
  "locationInModule": {
11955
12082
  "filename": "lib/iceberg/iceberg-type.ts",
11956
- "line": 169
12083
+ "line": 193
11957
12084
  },
11958
12085
  "name": "BINARY",
11959
12086
  "static": true,
@@ -11970,7 +12097,7 @@
11970
12097
  "immutable": true,
11971
12098
  "locationInModule": {
11972
12099
  "filename": "lib/iceberg/iceberg-type.ts",
11973
- "line": 114
12100
+ "line": 138
11974
12101
  },
11975
12102
  "name": "BOOLEAN",
11976
12103
  "static": true,
@@ -11987,7 +12114,7 @@
11987
12114
  "immutable": true,
11988
12115
  "locationInModule": {
11989
12116
  "filename": "lib/iceberg/iceberg-type.ts",
11990
- "line": 139
12117
+ "line": 163
11991
12118
  },
11992
12119
  "name": "DATE",
11993
12120
  "static": true,
@@ -12004,7 +12131,7 @@
12004
12131
  "immutable": true,
12005
12132
  "locationInModule": {
12006
12133
  "filename": "lib/iceberg/iceberg-type.ts",
12007
- "line": 134
12134
+ "line": 158
12008
12135
  },
12009
12136
  "name": "DOUBLE",
12010
12137
  "static": true,
@@ -12021,7 +12148,7 @@
12021
12148
  "immutable": true,
12022
12149
  "locationInModule": {
12023
12150
  "filename": "lib/iceberg/iceberg-type.ts",
12024
- "line": 129
12151
+ "line": 153
12025
12152
  },
12026
12153
  "name": "FLOAT",
12027
12154
  "static": true,
@@ -12038,7 +12165,7 @@
12038
12165
  "immutable": true,
12039
12166
  "locationInModule": {
12040
12167
  "filename": "lib/iceberg/iceberg-type.ts",
12041
- "line": 119
12168
+ "line": 143
12042
12169
  },
12043
12170
  "name": "INT",
12044
12171
  "static": true,
@@ -12055,7 +12182,7 @@
12055
12182
  "immutable": true,
12056
12183
  "locationInModule": {
12057
12184
  "filename": "lib/iceberg/iceberg-type.ts",
12058
- "line": 124
12185
+ "line": 148
12059
12186
  },
12060
12187
  "name": "LONG",
12061
12188
  "static": true,
@@ -12072,7 +12199,7 @@
12072
12199
  "immutable": true,
12073
12200
  "locationInModule": {
12074
12201
  "filename": "lib/iceberg/iceberg-type.ts",
12075
- "line": 159
12202
+ "line": 183
12076
12203
  },
12077
12204
  "name": "STRING",
12078
12205
  "static": true,
@@ -12089,7 +12216,7 @@
12089
12216
  "immutable": true,
12090
12217
  "locationInModule": {
12091
12218
  "filename": "lib/iceberg/iceberg-type.ts",
12092
- "line": 144
12219
+ "line": 168
12093
12220
  },
12094
12221
  "name": "TIME",
12095
12222
  "static": true,
@@ -12106,7 +12233,7 @@
12106
12233
  "immutable": true,
12107
12234
  "locationInModule": {
12108
12235
  "filename": "lib/iceberg/iceberg-type.ts",
12109
- "line": 149
12236
+ "line": 173
12110
12237
  },
12111
12238
  "name": "TIMESTAMP",
12112
12239
  "static": true,
@@ -12114,6 +12241,24 @@
12114
12241
  "fqn": "cdk-glue-iceberg-table.IcebergType"
12115
12242
  }
12116
12243
  },
12244
+ {
12245
+ "const": true,
12246
+ "docs": {
12247
+ "remarks": "Format v3.",
12248
+ "stability": "experimental",
12249
+ "summary": "Nanosecond-precision timestamp without zone."
12250
+ },
12251
+ "immutable": true,
12252
+ "locationInModule": {
12253
+ "filename": "lib/iceberg/iceberg-type.ts",
12254
+ "line": 203
12255
+ },
12256
+ "name": "TIMESTAMP_NS",
12257
+ "static": true,
12258
+ "type": {
12259
+ "fqn": "cdk-glue-iceberg-table.IcebergType"
12260
+ }
12261
+ },
12117
12262
  {
12118
12263
  "const": true,
12119
12264
  "docs": {
@@ -12123,7 +12268,7 @@
12123
12268
  "immutable": true,
12124
12269
  "locationInModule": {
12125
12270
  "filename": "lib/iceberg/iceberg-type.ts",
12126
- "line": 154
12271
+ "line": 178
12127
12272
  },
12128
12273
  "name": "TIMESTAMPTZ",
12129
12274
  "static": true,
@@ -12131,6 +12276,42 @@
12131
12276
  "fqn": "cdk-glue-iceberg-table.IcebergType"
12132
12277
  }
12133
12278
  },
12279
+ {
12280
+ "const": true,
12281
+ "docs": {
12282
+ "remarks": "Format v3.",
12283
+ "stability": "experimental",
12284
+ "summary": "Nanosecond-precision timestamp stored as UTC."
12285
+ },
12286
+ "immutable": true,
12287
+ "locationInModule": {
12288
+ "filename": "lib/iceberg/iceberg-type.ts",
12289
+ "line": 208
12290
+ },
12291
+ "name": "TIMESTAMPTZ_NS",
12292
+ "static": true,
12293
+ "type": {
12294
+ "fqn": "cdk-glue-iceberg-table.IcebergType"
12295
+ }
12296
+ },
12297
+ {
12298
+ "const": true,
12299
+ "docs": {
12300
+ "remarks": "Format v3; never required.",
12301
+ "stability": "experimental",
12302
+ "summary": "Type of a column whose values are always null."
12303
+ },
12304
+ "immutable": true,
12305
+ "locationInModule": {
12306
+ "filename": "lib/iceberg/iceberg-type.ts",
12307
+ "line": 198
12308
+ },
12309
+ "name": "UNKNOWN",
12310
+ "static": true,
12311
+ "type": {
12312
+ "fqn": "cdk-glue-iceberg-table.IcebergType"
12313
+ }
12314
+ },
12134
12315
  {
12135
12316
  "const": true,
12136
12317
  "docs": {
@@ -12140,7 +12321,7 @@
12140
12321
  "immutable": true,
12141
12322
  "locationInModule": {
12142
12323
  "filename": "lib/iceberg/iceberg-type.ts",
12143
- "line": 164
12324
+ "line": 188
12144
12325
  },
12145
12326
  "name": "UUID",
12146
12327
  "static": true,
@@ -12148,6 +12329,24 @@
12148
12329
  "fqn": "cdk-glue-iceberg-table.IcebergType"
12149
12330
  }
12150
12331
  },
12332
+ {
12333
+ "const": true,
12334
+ "docs": {
12335
+ "remarks": "Format v3.",
12336
+ "stability": "experimental",
12337
+ "summary": "Semi-structured value: an object, an array, or a primitive."
12338
+ },
12339
+ "immutable": true,
12340
+ "locationInModule": {
12341
+ "filename": "lib/iceberg/iceberg-type.ts",
12342
+ "line": 213
12343
+ },
12344
+ "name": "VARIANT",
12345
+ "static": true,
12346
+ "type": {
12347
+ "fqn": "cdk-glue-iceberg-table.IcebergType"
12348
+ }
12349
+ },
12151
12350
  {
12152
12351
  "docs": {
12153
12352
  "stability": "experimental",
@@ -12156,7 +12355,7 @@
12156
12355
  "immutable": true,
12157
12356
  "locationInModule": {
12158
12357
  "filename": "lib/iceberg/iceberg-type.ts",
12159
- "line": 237
12358
+ "line": 305
12160
12359
  },
12161
12360
  "name": "kind",
12162
12361
  "type": {
@@ -12171,7 +12370,7 @@
12171
12370
  "immutable": true,
12172
12371
  "locationInModule": {
12173
12372
  "filename": "lib/iceberg/iceberg-type.ts",
12174
- "line": 240
12373
+ "line": 308
12175
12374
  },
12176
12375
  "name": "decimalPrecision",
12177
12376
  "optional": true,
@@ -12187,7 +12386,7 @@
12187
12386
  "immutable": true,
12188
12387
  "locationInModule": {
12189
12388
  "filename": "lib/iceberg/iceberg-type.ts",
12190
- "line": 243
12389
+ "line": 311
12191
12390
  },
12192
12391
  "name": "decimalScale",
12193
12392
  "optional": true,
@@ -12203,7 +12402,7 @@
12203
12402
  "immutable": true,
12204
12403
  "locationInModule": {
12205
12404
  "filename": "lib/iceberg/iceberg-type.ts",
12206
- "line": 246
12405
+ "line": 314
12207
12406
  },
12208
12407
  "name": "fixedLength",
12209
12408
  "optional": true,
@@ -12211,6 +12410,38 @@
12211
12410
  "primitive": "number"
12212
12411
  }
12213
12412
  },
12413
+ {
12414
+ "docs": {
12415
+ "stability": "experimental",
12416
+ "summary": "Coordinate reference system (set when `kind` is `GEOMETRY` or `GEOGRAPHY` and one was given)."
12417
+ },
12418
+ "immutable": true,
12419
+ "locationInModule": {
12420
+ "filename": "lib/iceberg/iceberg-type.ts",
12421
+ "line": 335
12422
+ },
12423
+ "name": "geoCrs",
12424
+ "optional": true,
12425
+ "type": {
12426
+ "primitive": "string"
12427
+ }
12428
+ },
12429
+ {
12430
+ "docs": {
12431
+ "stability": "experimental",
12432
+ "summary": "Edge-interpolation algorithm (set when one was given)."
12433
+ },
12434
+ "immutable": true,
12435
+ "locationInModule": {
12436
+ "filename": "lib/iceberg/iceberg-type.ts",
12437
+ "line": 338
12438
+ },
12439
+ "name": "geographyAlgorithm",
12440
+ "optional": true,
12441
+ "type": {
12442
+ "fqn": "cdk-glue-iceberg-table.IcebergEdgeAlgorithm"
12443
+ }
12444
+ },
12214
12445
  {
12215
12446
  "docs": {
12216
12447
  "stability": "experimental",
@@ -12219,7 +12450,7 @@
12219
12450
  "immutable": true,
12220
12451
  "locationInModule": {
12221
12452
  "filename": "lib/iceberg/iceberg-type.ts",
12222
- "line": 249
12453
+ "line": 317
12223
12454
  },
12224
12455
  "name": "listElement",
12225
12456
  "optional": true,
@@ -12235,7 +12466,7 @@
12235
12466
  "immutable": true,
12236
12467
  "locationInModule": {
12237
12468
  "filename": "lib/iceberg/iceberg-type.ts",
12238
- "line": 252
12469
+ "line": 320
12239
12470
  },
12240
12471
  "name": "listElementRequired",
12241
12472
  "optional": true,
@@ -12251,7 +12482,7 @@
12251
12482
  "immutable": true,
12252
12483
  "locationInModule": {
12253
12484
  "filename": "lib/iceberg/iceberg-type.ts",
12254
- "line": 255
12485
+ "line": 323
12255
12486
  },
12256
12487
  "name": "mapKey",
12257
12488
  "optional": true,
@@ -12267,7 +12498,7 @@
12267
12498
  "immutable": true,
12268
12499
  "locationInModule": {
12269
12500
  "filename": "lib/iceberg/iceberg-type.ts",
12270
- "line": 258
12501
+ "line": 326
12271
12502
  },
12272
12503
  "name": "mapValue",
12273
12504
  "optional": true,
@@ -12283,7 +12514,7 @@
12283
12514
  "immutable": true,
12284
12515
  "locationInModule": {
12285
12516
  "filename": "lib/iceberg/iceberg-type.ts",
12286
- "line": 261
12517
+ "line": 329
12287
12518
  },
12288
12519
  "name": "mapValueRequired",
12289
12520
  "optional": true,
@@ -12299,7 +12530,7 @@
12299
12530
  "immutable": true,
12300
12531
  "locationInModule": {
12301
12532
  "filename": "lib/iceberg/iceberg-type.ts",
12302
- "line": 264
12533
+ "line": 332
12303
12534
  },
12304
12535
  "name": "structFields",
12305
12536
  "optional": true,
@@ -12429,6 +12660,42 @@
12429
12660
  "stability": "experimental"
12430
12661
  },
12431
12662
  "name": "STRUCT"
12663
+ },
12664
+ {
12665
+ "docs": {
12666
+ "stability": "experimental"
12667
+ },
12668
+ "name": "UNKNOWN"
12669
+ },
12670
+ {
12671
+ "docs": {
12672
+ "stability": "experimental"
12673
+ },
12674
+ "name": "TIMESTAMP_NS"
12675
+ },
12676
+ {
12677
+ "docs": {
12678
+ "stability": "experimental"
12679
+ },
12680
+ "name": "TIMESTAMPTZ_NS"
12681
+ },
12682
+ {
12683
+ "docs": {
12684
+ "stability": "experimental"
12685
+ },
12686
+ "name": "VARIANT"
12687
+ },
12688
+ {
12689
+ "docs": {
12690
+ "stability": "experimental"
12691
+ },
12692
+ "name": "GEOMETRY"
12693
+ },
12694
+ {
12695
+ "docs": {
12696
+ "stability": "experimental"
12697
+ },
12698
+ "name": "GEOGRAPHY"
12432
12699
  }
12433
12700
  ],
12434
12701
  "name": "IcebergTypeKind",
@@ -12446,7 +12713,7 @@
12446
12713
  "kind": "interface",
12447
12714
  "locationInModule": {
12448
12715
  "filename": "lib/iceberg/iceberg-type.ts",
12449
- "line": 74
12716
+ "line": 92
12450
12717
  },
12451
12718
  "name": "IcebergTypeOptions",
12452
12719
  "properties": [
@@ -12459,7 +12726,7 @@
12459
12726
  "immutable": true,
12460
12727
  "locationInModule": {
12461
12728
  "filename": "lib/iceberg/iceberg-type.ts",
12462
- "line": 76
12729
+ "line": 94
12463
12730
  },
12464
12731
  "name": "kind",
12465
12732
  "type": {
@@ -12475,7 +12742,7 @@
12475
12742
  "immutable": true,
12476
12743
  "locationInModule": {
12477
12744
  "filename": "lib/iceberg/iceberg-type.ts",
12478
- "line": 79
12745
+ "line": 97
12479
12746
  },
12480
12747
  "name": "decimalPrecision",
12481
12748
  "optional": true,
@@ -12492,7 +12759,7 @@
12492
12759
  "immutable": true,
12493
12760
  "locationInModule": {
12494
12761
  "filename": "lib/iceberg/iceberg-type.ts",
12495
- "line": 82
12762
+ "line": 100
12496
12763
  },
12497
12764
  "name": "decimalScale",
12498
12765
  "optional": true,
@@ -12510,7 +12777,7 @@
12510
12777
  "immutable": true,
12511
12778
  "locationInModule": {
12512
12779
  "filename": "lib/iceberg/iceberg-type.ts",
12513
- "line": 85
12780
+ "line": 103
12514
12781
  },
12515
12782
  "name": "fixedLength",
12516
12783
  "optional": true,
@@ -12518,6 +12785,42 @@
12518
12785
  "primitive": "number"
12519
12786
  }
12520
12787
  },
12788
+ {
12789
+ "abstract": true,
12790
+ "docs": {
12791
+ "remarks": "Optional when `kind` is `GEOMETRY` or `GEOGRAPHY`.",
12792
+ "stability": "experimental",
12793
+ "summary": "Coordinate reference system identifier."
12794
+ },
12795
+ "immutable": true,
12796
+ "locationInModule": {
12797
+ "filename": "lib/iceberg/iceberg-type.ts",
12798
+ "line": 124
12799
+ },
12800
+ "name": "geoCrs",
12801
+ "optional": true,
12802
+ "type": {
12803
+ "primitive": "string"
12804
+ }
12805
+ },
12806
+ {
12807
+ "abstract": true,
12808
+ "docs": {
12809
+ "remarks": "Optional when `kind === GEOGRAPHY`.",
12810
+ "stability": "experimental",
12811
+ "summary": "Edge-interpolation algorithm."
12812
+ },
12813
+ "immutable": true,
12814
+ "locationInModule": {
12815
+ "filename": "lib/iceberg/iceberg-type.ts",
12816
+ "line": 127
12817
+ },
12818
+ "name": "geographyAlgorithm",
12819
+ "optional": true,
12820
+ "type": {
12821
+ "fqn": "cdk-glue-iceberg-table.IcebergEdgeAlgorithm"
12822
+ }
12823
+ },
12521
12824
  {
12522
12825
  "abstract": true,
12523
12826
  "docs": {
@@ -12528,7 +12831,7 @@
12528
12831
  "immutable": true,
12529
12832
  "locationInModule": {
12530
12833
  "filename": "lib/iceberg/iceberg-type.ts",
12531
- "line": 88
12834
+ "line": 106
12532
12835
  },
12533
12836
  "name": "listElement",
12534
12837
  "optional": true,
@@ -12546,7 +12849,7 @@
12546
12849
  "immutable": true,
12547
12850
  "locationInModule": {
12548
12851
  "filename": "lib/iceberg/iceberg-type.ts",
12549
- "line": 91
12852
+ "line": 109
12550
12853
  },
12551
12854
  "name": "listElementRequired",
12552
12855
  "optional": true,
@@ -12564,7 +12867,7 @@
12564
12867
  "immutable": true,
12565
12868
  "locationInModule": {
12566
12869
  "filename": "lib/iceberg/iceberg-type.ts",
12567
- "line": 94
12870
+ "line": 112
12568
12871
  },
12569
12872
  "name": "mapKey",
12570
12873
  "optional": true,
@@ -12582,7 +12885,7 @@
12582
12885
  "immutable": true,
12583
12886
  "locationInModule": {
12584
12887
  "filename": "lib/iceberg/iceberg-type.ts",
12585
- "line": 97
12888
+ "line": 115
12586
12889
  },
12587
12890
  "name": "mapValue",
12588
12891
  "optional": true,
@@ -12600,7 +12903,7 @@
12600
12903
  "immutable": true,
12601
12904
  "locationInModule": {
12602
12905
  "filename": "lib/iceberg/iceberg-type.ts",
12603
- "line": 100
12906
+ "line": 118
12604
12907
  },
12605
12908
  "name": "mapValueRequired",
12606
12909
  "optional": true,
@@ -12618,7 +12921,7 @@
12618
12921
  "immutable": true,
12619
12922
  "locationInModule": {
12620
12923
  "filename": "lib/iceberg/iceberg-type.ts",
12621
- "line": 103
12924
+ "line": 121
12622
12925
  },
12623
12926
  "name": "structFields",
12624
12927
  "optional": true,
@@ -12635,6 +12938,6 @@
12635
12938
  "symbolId": "lib/iceberg/iceberg-type:IcebergTypeOptions"
12636
12939
  }
12637
12940
  },
12638
- "version": "0.7.4",
12639
- "fingerprint": "ipfRTU4eJw1GDXmLCb2H/wfnCACMF45Nl2x4vStfCrs="
12941
+ "version": "0.9.0",
12942
+ "fingerprint": "w78Lq+tpvw/XUnrkSpn/0T9r4++rJIOW4IGbKhXpH6Y="
12640
12943
  }