cdk-glue-iceberg-table 0.16.0 → 0.18.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 +261 -95
- package/README.md +123 -17
- package/dist/lib/iceberg/iceberg-partition-transform.js +1 -1
- package/dist/lib/iceberg/iceberg-schema-history.d.ts +3 -2
- package/dist/lib/iceberg/iceberg-schema-history.js +25 -4
- package/dist/lib/iceberg/iceberg-table-grants.d.ts +61 -28
- package/dist/lib/iceberg/iceberg-table-grants.js +120 -32
- package/dist/lib/iceberg/iceberg-table-properties.js +1 -1
- package/dist/lib/iceberg/iceberg-table-render.js +3 -2
- package/dist/lib/iceberg/iceberg-table.d.ts +26 -15
- package/dist/lib/iceberg/iceberg-table.js +26 -112
- package/dist/lib/iceberg/iceberg-type.js +1 -1
- package/dist/lib/iceberg/index.d.ts +1 -0
- package/dist/lib/iceberg/index.js +1 -1
- package/package.json +1 -1
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[](https://github.com/ksco92/arceus/actions/workflows/ci.yml)\n[](https://codecov.io/gh/ksco92/arceus)\n[](https://www.npmjs.com/package/cdk-glue-iceberg-table)\n[](https://pypi.org/project/cdk-glue-iceberg-table/)\n[](https://constructs.dev/packages/cdk-glue-iceberg-table)\n[](https://www.npmjs.com/package/cdk-glue-iceberg-table)\n[](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 on every PR by two\nconsumer jobs (`e2e-consumer` compiles and synthesizes an app against a\npinned published version, `packed-consumer` does the same against the PR's\nown `npm pack` tarball) plus real-AWS integration suites, including ones\nfor 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 (declared [in creation order](#using-icebergtable) for a new\ntable) so schema evolution never orphans existing data. It was the\nbasis of 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`, the `fromIcebergTableAttributes(...)` import factory, and `creationOrderFieldIds(columns)` (Python: `creation_order_field_ids`), which returns a map from field path to the id Glue gives that field in a new table; a name containing `.` or a backquote appears in backquotes.\n- **`IcebergSchemaHistory`** — `validateSchemaEvolution(previous, next)` (Python: `validate_schema_evolution`), which returns the unsafe changes from a table's history record to a definition (`IcebergTableSchema`) as `IcebergSchemaViolation`s, each carrying an `IcebergSchemaViolationKind` that names the class of unsafe change; `append`, `toJson` and `fromJson`, which record a definition in, write and read the history file (`IcebergSchemaHistoryFile`, `IcebergTableHistory`, `IcebergFieldHistory`, `IcebergPartitionFieldHistory`); and `updateFromCloudAssembly(directory)`, which records every table of a synthesized app. See [Checking changes against a schema history](#checking-changes-against-a-schema-history).\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, declared in creation order when the table is created (below), is\nwhat lets you add, rename, and drop columns across deploys without\ncorrupting 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 new table must declare its ids in creation order. When Glue creates\na table it does not keep the declared ids: it numbers the fields from\n1 in creation order and points the partition spec, sort order and\nidentifier fields at the new ids. An update Glue accepts stores the\ndeclared ids as given, so the first such update of a table created\nwith other ids renumbers its fields; for the update Glue rejects, see\n[Known limitations](#known-limitations). To number a new table, number\nthe top-level columns first, in order, then the nested fields of each\ncolumn in turn (a list's element; a map's key, then its value, then\nthe key's nested fields, then the value's; a struct's fields, then\ntheir nested fields). `IcebergTable.creationOrderFieldIds` returns\nthese ids by field path and ignores the ids in its input:\n\n```typescript\nconst columns = [\n { name: 'id', type: IcebergType.LONG, required: true, id: 1 },\n { name: 'tags', type: IcebergType.list({ element: IcebergType.STRING, elementId: 4 }), id: 2 },\n {\n name: 'attrs',\n type: IcebergType.map({ key: IcebergType.STRING, keyId: 5, value: IcebergType.STRING, valueId: 6 }),\n id: 3,\n },\n];\nIcebergTable.creationOrderFieldIds(columns);\n// { id: 1, tags: 2, attrs: 3, 'tags.element': 4, 'attrs.key': 5, 'attrs.value': 6 }\n```\n\nIds out of creation order are for fields a later deploy adds; see\n[Evolving schema and partitions](#evolving-schema-and-partitions).\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), and `cdk synth`\nrejects an identifier column of type float, double, list, map, struct,\nunknown, variant, geometry or geography. The construct prefixes each\nidentifier column's `doc` with `(PK) `, so a `doc` you write must not\nstart with `(PK) `; see [Evolving schema and\npartitions](#evolving-schema-and-partitions).\n\nEvery string you pass is a literal string, not a token, and an\nenum-typed one must be a member of its enum; the exceptions are\n`location`, `comment`, table property values, and the `tableName` of\nan imported table.\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.1 + Iceberg 1.11.0 (the integration-test runner) | Yes | Reads and writes tables the construct creates, including deletion vectors, row lineage, `variant` and `unknown`, except tables with a `geometry`, `geography` or nanosecond-timestamp column ([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 run on Glue 6.0's Spark 4.1.1 and Iceberg 1.11.0 (`scripts/spark/spark-env.sh`); the Glue job runtime itself is not exercised. |\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.\" The v2 integration suites also run through Athena (see [Does it work with Athena and Lake Formation?](#does-it-work-with-athena-and-lake-formation)); no v3 table is queried through Athena. |\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 to the\nid the table holds and never reused. Adds, renames (same `id`, new\n`name`), and drops all flow through `cdk deploy` alone — no\nout-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\nSuch an id is out of creation order, which is expected once a table\nhas evolved: creation order applies only to the ids a table is created\nwith (see [Using `IcebergTable`](#using-icebergtable)).\n\nUpgrading from a version before 0.12.0, which numbered nested fields\nitself: declare the ids the table's current `metadata.json` holds,\ntop-level and nested (each field `id`, `element-id`, `key-id` and\n`value-id`), or the next deploy renumbers the fields that differ and\nexisting data files read under the wrong field. A nested type object\nshared by two columns now fails synth with a duplicate id; give each\ncolumn its own nested type with its own ids. The list element and map\nvalue nullability 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\nA changed `sortOrder` also flows through `cdk deploy`. Glue adds it to\n`sort-orders` under the next `order-id` and points\n`default-sort-order-id` at it; the earlier orders stay in the list.\nA change to `tableProperties` alone writes new metadata that keeps the\nsame `current-schema-id`, partition spec and sort order.\n\n### Checking changes against a schema history\n\nThe construct never reads the deployed table, so on its own it cannot\ntell that an id belonged to a field dropped two deploys ago. A schema\nhistory file committed beside the app gives synth that record without\nan AWS call. Point `schemaHistoryFile` at the history file of the\ntable's database:\n\n```typescript\nnew IcebergTable(this, 'Orders', {\n // ...\n schemaHistoryFile: path.join(__dirname, 'analytics.schema-history.json'),\n});\n```\n\nA relative path resolves against the working directory, which is the\ndirectory holding `cdk.json` when the `cdk` CLI runs the app. Create\nthe file once with the content `{\"tables\": []}`. Records are keyed by\ntable name, so give each Glue database its own file.\n\nEvery synth (`cdk synth`, `cdk diff`, `cdk deploy`, and the CI job\nthat runs one) then compares each table with its record and fails,\nlisting every problem, when the definition:\n\n- gives a column or nested field id in the record to a different\n field: a dropped field's id, or the id of a field whose\n path is still in the definition under another id;\n- keeps a field's path but changes its id, as in the nested ids\n `4, 5, 6` becoming `5, 6, 7` after a column is added;\n- changes a field's type, except `int` to `long`, `float` to `double`,\n and a wider decimal precision at the same scale;\n- makes an optional field required;\n- drops a column that any recorded partition spec was sourced from;\n- keeps a partition `fieldId` with a different source column or\n transform.\n\nFields are identified by id, so a rename passes. A table with no\nrecord passes. Synth never writes the file; record a change once it\npasses synth, and commit the file with the change:\n\n```bash\ncdk synth --quiet\nnode -e \"console.log(require('cdk-glue-iceberg-table').IcebergSchemaHistory.updateFromCloudAssembly('cdk.out'))\"\n```\n\nFrom a Python app, the second command is:\n\n```bash\npython -c \"from cdk_glue_iceberg_table import IcebergSchemaHistory; print(IcebergSchemaHistory.update_from_cloud_assembly('cdk.out'))\"\n```\n\n`updateFromCloudAssembly` records every table of the assembly that\nsets `schemaHistoryFile` in that file and returns the files it wrote.\nThe record keeps every id the table has used: a dropped field stays\nwith `\"dropped\": true`, and a partition field stays after it leaves\nthe spec. The file must already exist, and nothing is written when any\ntable is an unsafe change. A column replaced under the same name needs\ntwo recorded changes: drop it, then add it with a new id.\n\n`IcebergSchemaHistory.validateSchemaEvolution(previous, next)` runs\nthe same checks on one table record without the prop, and\n`IcebergSchemaHistory.append`, `toJson` and `fromJson` record a\ndefinition in, write and read the file format.\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 prevents only with a [schema history\nfile](#checking-changes-against-a-schema-history). See the next\nsection.)\n\n## Known limitations\n\n- **Creation order is not checked.** The construct cannot tell at synth whether a table is new or already deployed, so it accepts a new table whose ids are not in creation order (the rule is under [Using `IcebergTable`](#using-icebergtable)). When the first update of such a table changes the id of a column an identity partition is sourced from, Glue rejects the update with `Cannot create identity partition sourced from different field in schema` and the CloudFormation rollback fails the same way, leaving the stack in `UPDATE_ROLLBACK_FAILED`.\n- **Field-id reuse across deploys is detected only with a schema history file.** 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) and never reads the live table state; across deploys, only a [schema history file](#checking-changes-against-a-schema-history) catches reuse. Without it, treat dropped ids as retired forever.\n- **Partition field-id reuse across deploys is detected only with a schema history file.** The same live-state blindness applies to partition `fieldId`s: the construct validates them within one deploy (integer >= 1000, unique in the spec), and only a [schema history file](#checking-changes-against-a-schema-history) tells it 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. Without the history file, 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- **A rolled-back deploy leaves its schema in the table's history.** When a deploy that adds a column updates the table and then fails on another resource, the stack ends in `UPDATE_ROLLBACK_COMPLETE` and `current-schema-id` is back to its earlier value, so the column is gone and the rows read as before. The schema that held the column stays in `schemas`, and `last-column-id` stays at the column's id. A clean redeploy of the same change makes that schema current again without adding a schema. Treat an id from a rolled-back deploy as used: give it only to the column that deploy added.\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- **The schema history check covers only the changes it lists.** It does not see a change an engine makes with `ALTER TABLE` (Spark, Athena), whose ids the file never records, or a deploy whose definition was not recorded in the file. It does not check sort order or identifier field changes or report an added required field, top level or nested, and it treats a field moved into another struct under its id as a rename. It reports the format v3 promotions `unknown` to any type and `date` to `timestamp` or `timestamp_ns` as type 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.** 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 Spark 4.1.1 with Iceberg 1.11.0.** In [`TypeToSparkType`](https://github.com/apache/iceberg/blob/apache-iceberg-1.11.0/spark/v4.1/spark/src/main/java/org/apache/iceberg/spark/TypeToSparkType.java) at the `apache-iceberg-1.11.0` tag, `primitive()` has no case for the `TIMESTAMP_NANO` type id, so a table with a `timestamp_ns` or `timestamptz_ns` column reaches the `Cannot convert unsupported type to Spark` error. The integration suite asserts these columns from `metadata.json` only.\n- **Geometry and geography columns are catalog-only for Spark 4.1.1 with Iceberg 1.11.0, the versions AWS Glue 6.0 ships.** The first Spark read of a table holding a `geography` and a `geometry` column failed with `UnsupportedOperationException: Cannot convert unsupported type to Spark: geography(OGC:CRS84, spherical)` on those versions. [`TypeToSparkType`](https://github.com/apache/iceberg/blob/apache-iceberg-1.11.0/spark/v4.1/spark/src/main/java/org/apache/iceberg/spark/TypeToSparkType.java) at the `apache-iceberg-1.11.0` tag has no conversion for `geometry` either. The integration suite deploys these columns on a table no Spark job opens and asserts them from `metadata.json` only.\n- **Athena DDL features that don't surface through CFN** (e.g. `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 unless a [schema history file](#checking-changes-against-a-schema-history) records the column as a partition source, and 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 to the id the table\nholds 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 (declared in creation order for a new table),\nand `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)). The demo app in the\n[`arceus`](https://github.com/ksco92/arceus) repo registers its tables\nwith Lake Formation, and its v2 integration suites query them through\nAthena as well as Spark, on the same tables:\n\n- merge-on-read `INSERT`, `UPDATE`, `DELETE` and `MERGE INTO`, time\n travel (`FOR VERSION AS OF` / `FOR TIMESTAMP AS OF`), `OPTIMIZE ...\n REWRITE DATA USING BIN_PACK`, and `VACUUM`;\n- a read after every schema, partition, identifier and nested-field\n evolution step;\n- the `(PK) ` comment on identifier columns, read from\n `information_schema.columns`;\n- rows written by Spark read through Athena, and rows written by Athena\n read through Spark.\n\nThe suites grant the querying principal `SELECT`, `INSERT`, `DELETE`,\n`ALTER` and `DESCRIBE` through Lake Formation. The construct's `grant*`\nhelpers issue IAM grants only; under Lake Formation you add the\nmatching 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[](https://github.com/ksco92/arceus/actions/workflows/ci.yml)\n[](https://codecov.io/gh/ksco92/arceus)\n[](https://www.npmjs.com/package/cdk-glue-iceberg-table)\n[](https://pypi.org/project/cdk-glue-iceberg-table/)\n[](https://constructs.dev/packages/cdk-glue-iceberg-table)\n[](https://www.npmjs.com/package/cdk-glue-iceberg-table)\n[](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 on every PR by two\nconsumer jobs (`e2e-consumer` compiles and synthesizes an app against a\npinned published version, `packed-consumer` does the same against the PR's\nown `npm pack` tarball) plus real-AWS integration suites, including ones\nfor 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 (declared [in creation order](#using-icebergtable) for a new\ntable) so schema evolution never orphans existing data. It was the\nbasis of 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` (each taking an optional `IcebergTableGrantOptions`), the `fromIcebergTableAttributes(...)` import factory, and `creationOrderFieldIds(columns)` (Python: `creation_order_field_ids`), which returns a map from field path to the id Glue gives that field in a new table; a name containing `.` or a backquote appears in backquotes.\n- **`IcebergSchemaHistory`** — `validateSchemaEvolution(previous, next)` (Python: `validate_schema_evolution`), which returns the unsafe changes from a table's history record to a definition (`IcebergTableSchema`) as `IcebergSchemaViolation`s, each carrying an `IcebergSchemaViolationKind` that names the class of unsafe change; `append`, `toJson` and `fromJson`, which record a definition in, write and read the history file (`IcebergSchemaHistoryFile`, `IcebergTableHistory`, `IcebergFieldHistory`, `IcebergPartitionFieldHistory`); and `updateFromCloudAssembly(directory)`, which records every table of a synthesized app. See [Checking changes against a schema history](#checking-changes-against-a-schema-history).\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, declared in creation order when the table is created (below), is\nwhat lets you add, rename, and drop columns across deploys without\ncorrupting 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 new table must declare its ids in creation order. When Glue creates\na table it does not keep the declared ids: it numbers the fields from\n1 in creation order and points the partition spec, sort order and\nidentifier fields at the new ids. An update Glue accepts stores the\ndeclared ids as given, so the first such update of a table created\nwith other ids renumbers its fields; for the update Glue rejects, see\n[Known limitations](#known-limitations). To number a new table, number\nthe top-level columns first, in order, then the nested fields of each\ncolumn in turn (a list's element; a map's key, then its value, then\nthe key's nested fields, then the value's; a struct's fields, then\ntheir nested fields). `IcebergTable.creationOrderFieldIds` returns\nthese ids by field path and ignores the ids in its input:\n\n```typescript\nconst columns = [\n { name: 'id', type: IcebergType.LONG, required: true, id: 1 },\n { name: 'tags', type: IcebergType.list({ element: IcebergType.STRING, elementId: 4 }), id: 2 },\n {\n name: 'attrs',\n type: IcebergType.map({ key: IcebergType.STRING, keyId: 5, value: IcebergType.STRING, valueId: 6 }),\n id: 3,\n },\n];\nIcebergTable.creationOrderFieldIds(columns);\n// { id: 1, tags: 2, attrs: 3, 'tags.element': 4, 'attrs.key': 5, 'attrs.value': 6 }\n```\n\nIds out of creation order are for fields a later deploy adds; see\n[Evolving schema and partitions](#evolving-schema-and-partitions).\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), and `cdk synth`\nrejects an identifier column of type float, double, list, map, struct,\nunknown, variant, geometry or geography. The construct prefixes each\nidentifier column's `doc` with `(PK) `, so a `doc` you write must not\nstart with `(PK) `; see [Evolving schema and\npartitions](#evolving-schema-and-partitions).\n\nEvery string you pass is a literal string, not a token, and an\nenum-typed one must be a member of its enum; the exceptions are\n`location`, `comment`, table property values, and the `tableName` of\nan imported table.\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.1 + Iceberg 1.11.0 (the integration-test runner) | Yes | Reads and writes tables the construct creates, including deletion vectors, row lineage, `variant` and `unknown`, except tables with a `geometry`, `geography` or nanosecond-timestamp column ([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 run on Glue 6.0's Spark 4.1.1 and Iceberg 1.11.0 (`scripts/spark/spark-env.sh`); the Glue job runtime itself is not exercised. |\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.\" The v2 integration suites also run through Athena (see [Does it work with Athena and Lake Formation?](#does-it-work-with-athena-and-lake-formation)); no v3 table is queried through Athena. |\n\n### Granting access\n\n```typescript\nconst table = new IcebergTable(this, 'Orders', {\n // ...\n encryptionKey: bucketKey, // the key the table's bucket encrypts objects with\n});\ntable.grantRead(role);\ntable.grantWrite(role);\ntable.grantReadWrite(role, {\n catalogEncryptionKey: catalogKey, // the Data Catalog's SSE-KMS key\n lakeFormationDataAccess: true, // Athena on a location registered with Lake Formation\n});\n```\n\nEach method issues these statements and no others:\n\n| Statement | `grantRead` | `grantWrite` | `grantReadWrite` | Resource |\n| --- | --- | --- | --- | --- |\n| Glue | `glue:BatchGetPartition`, `glue:GetDatabase`, `glue:GetPartition`, `glue:GetPartitions`, `glue:GetTable`, `glue:GetTables`, `glue:GetTableVersion`, `glue:GetTableVersions` | `glue:BatchCreatePartition`, `glue:BatchDeletePartition`, `glue:CreatePartition`, `glue:DeletePartition`, `glue:UpdatePartition`, `glue:UpdateTable` | both lists | `arn:<partition>:glue:<region>:<account>:catalog`, the database ARN and the table ARN |\n| S3 list | `s3:ListBucket` | none | `s3:ListBucket` | the bucket, with condition `StringLike` `s3:prefix` = `<prefix>*` or `<prefix>` |\n| S3 bucket | `s3:GetBucketLocation` | `s3:ListBucketMultipartUploads` | both | the bucket |\n| S3 objects | `s3:GetObject` | `s3:PutObject`, `s3:DeleteObject`, `s3:AbortMultipartUpload`, `s3:ListMultipartUploadParts` | both lists | `<bucket>/<prefix>*` |\n| Table key, when `encryptionKey` is set | `kms:Decrypt` | `kms:Decrypt`, `kms:GenerateDataKey` | `kms:Decrypt`, `kms:GenerateDataKey` | the key |\n| Catalog key, when `catalogEncryptionKey` is passed | `kms:Decrypt` | `kms:Decrypt`, `kms:Encrypt`, `kms:GenerateDataKey` | `kms:Decrypt`, `kms:Encrypt`, `kms:GenerateDataKey` | the key |\n| Lake Formation, when `lakeFormationDataAccess` is `true` | `lakeformation:GetDataAccess` | `lakeformation:GetDataAccess` | `lakeformation:GetDataAccess` | `*` |\n\nThe KMS statements are on the whole key: `IKey.grant` adds no\nencryption-context condition, so a key shared with other data (a bucket\nor lake key, the catalog key) is covered for everything it encrypts,\nnot only this table.\n\n`lakeformation:GetDataAccess` is the one statement on `*`, because Lake\nFormation supports no resource for it. It is issued only with\n`lakeFormationDataAccess: true`; with it, Lake Formation vends\ncredentials for every table the principal holds Lake Formation\npermissions on, which includes tables open to `IAM_ALLOWED_PRINCIPALS`.\n\nPass `catalogEncryptionKey` when the Data Catalog is encrypted with a\ncustomer managed key.\n\nLake Formation permissions themselves (`AWS::LakeFormation::Permissions`)\nare yours to create:\n\n```typescript\nimport { CfnPermissions } from 'aws-cdk-lib/aws-lakeformation';\n\nnew CfnPermissions(this, 'OrdersReader', {\n dataLakePrincipal: { dataLakePrincipalIdentifier: role.roleArn },\n resource: {\n tableResource: {\n catalogId: this.account,\n databaseName: table.database.databaseName,\n name: table.tableName,\n },\n },\n permissions: ['SELECT', 'DESCRIBE'],\n});\n```\n\nAdd `INSERT`, `DELETE` and `ALTER` for a principal that writes.\n\nIn Python the new names are `encryption_key`, and the grant options are\nthe keyword arguments `lake_formation_data_access` and\n`catalog_encryption_key`.\n\nUpgrading from a version before 0.17.0: existing `grantRead`,\n`grantWrite` and `grantReadWrite` policies change with no code edit.\nThe Glue statement names the catalog and database ARNs as well as the\ntable, and read grants add `glue:GetDatabase`. Nothing for KMS or Lake\nFormation is issued unless the new prop or options are passed.\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 encryptionKey: bucketKey, // optional; grants then cover the key\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 to the\nid the table holds and never reused. Adds, renames (same `id`, new\n`name`), and drops all flow through `cdk deploy` alone — no\nout-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\nSuch an id is out of creation order, which is expected once a table\nhas evolved: creation order applies only to the ids a table is created\nwith (see [Using `IcebergTable`](#using-icebergtable)).\n\nUpgrading from a version before 0.12.0, which numbered nested fields\nitself: declare the ids the table's current `metadata.json` holds,\ntop-level and nested (each field `id`, `element-id`, `key-id` and\n`value-id`), or the next deploy renumbers the fields that differ and\nexisting data files read under the wrong field. A nested type object\nshared by two columns now fails synth with a duplicate id; give each\ncolumn its own nested type with its own ids. The list element and map\nvalue nullability 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\nA changed `sortOrder` also flows through `cdk deploy`. Glue adds it to\n`sort-orders` under the next `order-id` and points\n`default-sort-order-id` at it; the earlier orders stay in the list.\nA change to `tableProperties` alone writes new metadata that keeps the\nsame `current-schema-id`, partition spec and sort order.\n\n### Checking changes against a schema history\n\nThe construct never reads the deployed table, so on its own it cannot\ntell that an id belonged to a field dropped two deploys ago. A schema\nhistory file committed beside the app gives synth that record without\nan AWS call. Point `schemaHistoryFile` at the history file of the\ntable's database:\n\n```typescript\nnew IcebergTable(this, 'Orders', {\n // ...\n schemaHistoryFile: path.join(__dirname, 'analytics.schema-history.json'),\n});\n```\n\nA relative path resolves against the working directory, which is the\ndirectory holding `cdk.json` when the `cdk` CLI runs the app. Create\nthe file once with the content `{\"tables\": []}`; if a table already\nexists in Glue, read\n[Adopting a table that exists in Glue](#adopting-a-table-that-exists-in-glue)\nfirst. Records are keyed by table name, so give each Glue database its\nown file.\n\nEvery synth (`cdk synth`, `cdk diff`, `cdk deploy`, and the CI job\nthat runs one) then compares each table with its record and fails,\nlisting every problem, when the definition:\n\n- gives a column or nested field id in the record to a different\n field: a dropped field's id, or the id of a field whose\n path is still in the definition under another id;\n- keeps a field's path but changes its id, as in the nested ids\n `4, 5, 6` becoming `5, 6, 7` after a column is added;\n- changes a field's type, except `int` to `long`, `float` to `double`,\n and a wider decimal precision at the same scale;\n- makes an optional field required;\n- drops a column that any recorded partition spec was sourced from;\n- keeps a partition `fieldId` with a different source column or\n transform.\n\nFields are identified by id, so a rename passes. A table with no\nrecord is a new table: synth fails unless its ids are the ones Glue\nassigns at creation (the rule is under\n[Using `IcebergTable`](#using-icebergtable)), listing each field with\nits declared id and the id Glue assigns, so the first record of a table\nis written from a creation-order schema. A table with a record is not\nheld to creation order. Synth never writes the file; record a change\nonce it passes synth, and commit the file with the change:\n\n```bash\ncdk synth --quiet\nnode -e \"console.log(require('cdk-glue-iceberg-table').IcebergSchemaHistory.updateFromCloudAssembly('cdk.out'))\"\n```\n\nFrom a Python app, the second command is:\n\n```bash\npython -c \"from cdk_glue_iceberg_table import IcebergSchemaHistory; print(IcebergSchemaHistory.update_from_cloud_assembly('cdk.out'))\"\n```\n\n`updateFromCloudAssembly` records every table of the assembly that\nsets `schemaHistoryFile` in that file and returns the files it wrote.\nThe record keeps every id the table has used: a dropped field stays\nwith `\"dropped\": true`, and a partition field stays after it leaves\nthe spec. The file must already exist, and nothing is written when any\ntable is an unsafe change. A column replaced under the same name needs\ntwo recorded changes: drop it, then add it with a new id.\n\n`IcebergSchemaHistory.validateSchemaEvolution(previous, next)` runs\nthe same checks on one table record without the prop, and\n`IcebergSchemaHistory.append`, `toJson` and `fromJson` record a\ndefinition in, write and read the file format.\n\n#### Adopting a table that exists in Glue\n\nGlue ignores the ids a table declares when it creates the table and\nstores them as given from the first update of any kind. Before\nrecording anything, make the declared ids, top-level and nested, equal\nthe ids in the table's current `metadata.json`, whose location is the\ntable's `metadata_location` parameter (`aws glue get-table`). If those\nids are in creation order, declare them and write no record by hand:\nthat covers a table created in creation order and a table created out\nof order and never updated, which holds creation-order ids whatever it\ndeclared. Otherwise write the record from the definition that now\ndeclares the table's ids; `IcebergSchemaHistory.append` and `toJson`\ndo not run the creation-order check:\n\n```typescript\nconst history = IcebergSchemaHistory.append({ tables: [] }, 'orders', { columns, partitionSpec });\nfs.writeFileSync('analytics.schema-history.json', IcebergSchemaHistory.toJson(history));\n```\n\nFrom a Python app (`partition_spec` is optional, and the history is\npassed on to the next `append` for another table):\n\n```python\nhistory = IcebergSchemaHistory.append({\"tables\": []}, \"orders\", columns=columns, partition_spec=partition_spec)\nwith open(\"analytics.schema-history.json\", \"w\") as f:\n f.write(IcebergSchemaHistory.to_json(tables=history.tables))\n```\n\nRemove a table's record from the file before the table is dropped and\nrecreated: Glue assigns fresh ids at the new CREATE, so the new table\ndeclares creation-order ids.\n\nUpgrading from a version before 0.18.0: an app that sets\n`schemaHistoryFile` and has a table with no record whose ids are not in\ncreation order now fails synth; follow the steps above.\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 prevents only with a [schema history\nfile](#checking-changes-against-a-schema-history). See the next\nsection.)\n\n## Known limitations\n\n- **Creation order is checked only with a schema history file.** Without the file the construct does not detect ids that Glue will reassign at creation; with it, a table with no record is checked ([rule](#checking-changes-against-a-schema-history)). When the first update of such a table changes the id of a column an identity partition is sourced from, Glue rejects the update with `Cannot create identity partition sourced from different field in schema` and the CloudFormation rollback fails the same way, leaving the stack in `UPDATE_ROLLBACK_FAILED`.\n- **Field-id reuse across deploys is detected only with a schema history file.** 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) and never reads the live table state; across deploys, only a [schema history file](#checking-changes-against-a-schema-history) catches reuse. Without it, treat dropped ids as retired forever.\n- **Partition field-id reuse across deploys is detected only with a schema history file.** The same live-state blindness applies to partition `fieldId`s: the construct validates them within one deploy (integer >= 1000, unique in the spec), and only a [schema history file](#checking-changes-against-a-schema-history) tells it 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. Without the history file, 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- **A rolled-back deploy leaves its schema in the table's history.** When a deploy that adds a column updates the table and then fails on another resource, the stack ends in `UPDATE_ROLLBACK_COMPLETE` and `current-schema-id` is back to its earlier value, so the column is gone and the rows read as before. The schema that held the column stays in `schemas`, and `last-column-id` stays at the column's id. A clean redeploy of the same change makes that schema current again without adding a schema. Treat an id from a rolled-back deploy as used: give it only to the column that deploy added.\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- **The schema history check covers only the changes it lists.** It does not see a change an engine makes with `ALTER TABLE` (Spark, Athena), whose ids the file never records, or a deploy whose definition was not recorded in the file. It does not check sort order or identifier field changes or report an added required field, top level or nested, and it treats a field moved into another struct under its id as a rename. It reports the format v3 promotions `unknown` to any type and `date` to `timestamp` or `timestamp_ns` as type 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.** 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 (remove its [schema history record](#adopting-a-table-that-exists-in-glue) first). 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 Spark 4.1.1 with Iceberg 1.11.0.** In [`TypeToSparkType`](https://github.com/apache/iceberg/blob/apache-iceberg-1.11.0/spark/v4.1/spark/src/main/java/org/apache/iceberg/spark/TypeToSparkType.java) at the `apache-iceberg-1.11.0` tag, `primitive()` has no case for the `TIMESTAMP_NANO` type id, so a table with a `timestamp_ns` or `timestamptz_ns` column reaches the `Cannot convert unsupported type to Spark` error. The integration suite asserts these columns from `metadata.json` only.\n- **Geometry and geography columns are catalog-only for Spark 4.1.1 with Iceberg 1.11.0, the versions AWS Glue 6.0 ships.** The first Spark read of a table holding a `geography` and a `geometry` column failed with `UnsupportedOperationException: Cannot convert unsupported type to Spark: geography(OGC:CRS84, spherical)` on those versions. [`TypeToSparkType`](https://github.com/apache/iceberg/blob/apache-iceberg-1.11.0/spark/v4.1/spark/src/main/java/org/apache/iceberg/spark/TypeToSparkType.java) at the `apache-iceberg-1.11.0` tag has no conversion for `geometry` either. The integration suite deploys these columns on a table no Spark job opens and asserts them from `metadata.json` only.\n- **Athena DDL features that don't surface through CFN** (e.g. `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 unless a [schema history file](#checking-changes-against-a-schema-history) records the column as a partition source, and 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 to the id the table\nholds 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 (declared in creation order for a new table),\nand `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)). The demo app in the\n[`arceus`](https://github.com/ksco92/arceus) repo registers its tables\nwith Lake Formation, and its v2 integration suites query them through\nAthena as well as Spark, on the same tables:\n\n- merge-on-read `INSERT`, `UPDATE`, `DELETE` and `MERGE INTO`, time\n travel (`FOR VERSION AS OF` / `FOR TIMESTAMP AS OF`), `OPTIMIZE ...\n REWRITE DATA USING BIN_PACK`, and `VACUUM`;\n- a read after every schema, partition, identifier and nested-field\n evolution step;\n- the `(PK) ` comment on identifier columns, read from\n `information_schema.columns`;\n- rows written by Spark read through Athena, and rows written by Athena\n read through Spark;\n- reads and writes through Spark and Athena as roles whose table\n permissions come from `grantRead` and `grantReadWrite`, and a denied\n write as the `grantRead` role.\n\nThe suites grant the querying principal `SELECT`, `INSERT`, `DELETE`,\n`ALTER` and `DESCRIBE` through Lake Formation. 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":
|
|
9782
|
+
"line": 244
|
|
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":
|
|
9793
|
+
"line": 261
|
|
9794
9794
|
},
|
|
9795
9795
|
"name": "grantRead",
|
|
9796
9796
|
"parameters": [
|
|
@@ -9799,6 +9799,13 @@
|
|
|
9799
9799
|
"type": {
|
|
9800
9800
|
"fqn": "aws-cdk-lib.aws_iam.IGrantable"
|
|
9801
9801
|
}
|
|
9802
|
+
},
|
|
9803
|
+
{
|
|
9804
|
+
"name": "options",
|
|
9805
|
+
"optional": true,
|
|
9806
|
+
"type": {
|
|
9807
|
+
"fqn": "cdk-glue-iceberg-table.IcebergTableGrantOptions"
|
|
9808
|
+
}
|
|
9802
9809
|
}
|
|
9803
9810
|
],
|
|
9804
9811
|
"returns": {
|
|
@@ -9815,7 +9822,7 @@
|
|
|
9815
9822
|
},
|
|
9816
9823
|
"locationInModule": {
|
|
9817
9824
|
"filename": "lib/iceberg/iceberg-table.ts",
|
|
9818
|
-
"line":
|
|
9825
|
+
"line": 267
|
|
9819
9826
|
},
|
|
9820
9827
|
"name": "grantReadWrite",
|
|
9821
9828
|
"parameters": [
|
|
@@ -9824,6 +9831,13 @@
|
|
|
9824
9831
|
"type": {
|
|
9825
9832
|
"fqn": "aws-cdk-lib.aws_iam.IGrantable"
|
|
9826
9833
|
}
|
|
9834
|
+
},
|
|
9835
|
+
{
|
|
9836
|
+
"name": "options",
|
|
9837
|
+
"optional": true,
|
|
9838
|
+
"type": {
|
|
9839
|
+
"fqn": "cdk-glue-iceberg-table.IcebergTableGrantOptions"
|
|
9840
|
+
}
|
|
9827
9841
|
}
|
|
9828
9842
|
],
|
|
9829
9843
|
"returns": {
|
|
@@ -9840,7 +9854,7 @@
|
|
|
9840
9854
|
},
|
|
9841
9855
|
"locationInModule": {
|
|
9842
9856
|
"filename": "lib/iceberg/iceberg-table.ts",
|
|
9843
|
-
"line":
|
|
9857
|
+
"line": 264
|
|
9844
9858
|
},
|
|
9845
9859
|
"name": "grantWrite",
|
|
9846
9860
|
"parameters": [
|
|
@@ -9849,6 +9863,13 @@
|
|
|
9849
9863
|
"type": {
|
|
9850
9864
|
"fqn": "aws-cdk-lib.aws_iam.IGrantable"
|
|
9851
9865
|
}
|
|
9866
|
+
},
|
|
9867
|
+
{
|
|
9868
|
+
"name": "options",
|
|
9869
|
+
"optional": true,
|
|
9870
|
+
"type": {
|
|
9871
|
+
"fqn": "cdk-glue-iceberg-table.IcebergTableGrantOptions"
|
|
9872
|
+
}
|
|
9852
9873
|
}
|
|
9853
9874
|
],
|
|
9854
9875
|
"returns": {
|
|
@@ -9869,7 +9890,7 @@
|
|
|
9869
9890
|
"immutable": true,
|
|
9870
9891
|
"locationInModule": {
|
|
9871
9892
|
"filename": "lib/iceberg/iceberg-table.ts",
|
|
9872
|
-
"line":
|
|
9893
|
+
"line": 252
|
|
9873
9894
|
},
|
|
9874
9895
|
"name": "database",
|
|
9875
9896
|
"type": {
|
|
@@ -9885,7 +9906,7 @@
|
|
|
9885
9906
|
"immutable": true,
|
|
9886
9907
|
"locationInModule": {
|
|
9887
9908
|
"filename": "lib/iceberg/iceberg-table.ts",
|
|
9888
|
-
"line":
|
|
9909
|
+
"line": 255
|
|
9889
9910
|
},
|
|
9890
9911
|
"name": "location",
|
|
9891
9912
|
"type": {
|
|
@@ -9901,7 +9922,7 @@
|
|
|
9901
9922
|
"immutable": true,
|
|
9902
9923
|
"locationInModule": {
|
|
9903
9924
|
"filename": "lib/iceberg/iceberg-table.ts",
|
|
9904
|
-
"line":
|
|
9925
|
+
"line": 246
|
|
9905
9926
|
},
|
|
9906
9927
|
"name": "tableArn",
|
|
9907
9928
|
"type": {
|
|
@@ -9917,12 +9938,29 @@
|
|
|
9917
9938
|
"immutable": true,
|
|
9918
9939
|
"locationInModule": {
|
|
9919
9940
|
"filename": "lib/iceberg/iceberg-table.ts",
|
|
9920
|
-
"line":
|
|
9941
|
+
"line": 249
|
|
9921
9942
|
},
|
|
9922
9943
|
"name": "tableName",
|
|
9923
9944
|
"type": {
|
|
9924
9945
|
"primitive": "string"
|
|
9925
9946
|
}
|
|
9947
|
+
},
|
|
9948
|
+
{
|
|
9949
|
+
"abstract": true,
|
|
9950
|
+
"docs": {
|
|
9951
|
+
"stability": "experimental",
|
|
9952
|
+
"summary": "KMS key the table's objects are encrypted with, when known."
|
|
9953
|
+
},
|
|
9954
|
+
"immutable": true,
|
|
9955
|
+
"locationInModule": {
|
|
9956
|
+
"filename": "lib/iceberg/iceberg-table.ts",
|
|
9957
|
+
"line": 258
|
|
9958
|
+
},
|
|
9959
|
+
"name": "encryptionKey",
|
|
9960
|
+
"optional": true,
|
|
9961
|
+
"type": {
|
|
9962
|
+
"fqn": "aws-cdk-lib.aws_kms.IKey"
|
|
9963
|
+
}
|
|
9926
9964
|
}
|
|
9927
9965
|
],
|
|
9928
9966
|
"symbolId": "lib/iceberg/iceberg-table:IIcebergTable"
|
|
@@ -9938,7 +9976,7 @@
|
|
|
9938
9976
|
"kind": "interface",
|
|
9939
9977
|
"locationInModule": {
|
|
9940
9978
|
"filename": "lib/iceberg/iceberg-table.ts",
|
|
9941
|
-
"line":
|
|
9979
|
+
"line": 89
|
|
9942
9980
|
},
|
|
9943
9981
|
"name": "IcebergColumn",
|
|
9944
9982
|
"properties": [
|
|
@@ -9952,7 +9990,7 @@
|
|
|
9952
9990
|
"immutable": true,
|
|
9953
9991
|
"locationInModule": {
|
|
9954
9992
|
"filename": "lib/iceberg/iceberg-table.ts",
|
|
9955
|
-
"line":
|
|
9993
|
+
"line": 110
|
|
9956
9994
|
},
|
|
9957
9995
|
"name": "id",
|
|
9958
9996
|
"type": {
|
|
@@ -9968,7 +10006,7 @@
|
|
|
9968
10006
|
"immutable": true,
|
|
9969
10007
|
"locationInModule": {
|
|
9970
10008
|
"filename": "lib/iceberg/iceberg-table.ts",
|
|
9971
|
-
"line":
|
|
10009
|
+
"line": 91
|
|
9972
10010
|
},
|
|
9973
10011
|
"name": "name",
|
|
9974
10012
|
"type": {
|
|
@@ -9984,7 +10022,7 @@
|
|
|
9984
10022
|
"immutable": true,
|
|
9985
10023
|
"locationInModule": {
|
|
9986
10024
|
"filename": "lib/iceberg/iceberg-table.ts",
|
|
9987
|
-
"line":
|
|
10025
|
+
"line": 94
|
|
9988
10026
|
},
|
|
9989
10027
|
"name": "type",
|
|
9990
10028
|
"type": {
|
|
@@ -10001,7 +10039,7 @@
|
|
|
10001
10039
|
"immutable": true,
|
|
10002
10040
|
"locationInModule": {
|
|
10003
10041
|
"filename": "lib/iceberg/iceberg-table.ts",
|
|
10004
|
-
"line":
|
|
10042
|
+
"line": 103
|
|
10005
10043
|
},
|
|
10006
10044
|
"name": "doc",
|
|
10007
10045
|
"optional": true,
|
|
@@ -10019,7 +10057,7 @@
|
|
|
10019
10057
|
"immutable": true,
|
|
10020
10058
|
"locationInModule": {
|
|
10021
10059
|
"filename": "lib/iceberg/iceberg-table.ts",
|
|
10022
|
-
"line":
|
|
10060
|
+
"line": 100
|
|
10023
10061
|
},
|
|
10024
10062
|
"name": "required",
|
|
10025
10063
|
"optional": true,
|
|
@@ -10126,7 +10164,7 @@
|
|
|
10126
10164
|
"kind": "interface",
|
|
10127
10165
|
"locationInModule": {
|
|
10128
10166
|
"filename": "lib/iceberg/iceberg-schema-history.ts",
|
|
10129
|
-
"line":
|
|
10167
|
+
"line": 30
|
|
10130
10168
|
},
|
|
10131
10169
|
"name": "IcebergFieldHistory",
|
|
10132
10170
|
"properties": [
|
|
@@ -10140,7 +10178,7 @@
|
|
|
10140
10178
|
"immutable": true,
|
|
10141
10179
|
"locationInModule": {
|
|
10142
10180
|
"filename": "lib/iceberg/iceberg-schema-history.ts",
|
|
10143
|
-
"line":
|
|
10181
|
+
"line": 44
|
|
10144
10182
|
},
|
|
10145
10183
|
"name": "dropped",
|
|
10146
10184
|
"type": {
|
|
@@ -10156,7 +10194,7 @@
|
|
|
10156
10194
|
"immutable": true,
|
|
10157
10195
|
"locationInModule": {
|
|
10158
10196
|
"filename": "lib/iceberg/iceberg-schema-history.ts",
|
|
10159
|
-
"line":
|
|
10197
|
+
"line": 32
|
|
10160
10198
|
},
|
|
10161
10199
|
"name": "id",
|
|
10162
10200
|
"type": {
|
|
@@ -10172,7 +10210,7 @@
|
|
|
10172
10210
|
"immutable": true,
|
|
10173
10211
|
"locationInModule": {
|
|
10174
10212
|
"filename": "lib/iceberg/iceberg-schema-history.ts",
|
|
10175
|
-
"line":
|
|
10213
|
+
"line": 35
|
|
10176
10214
|
},
|
|
10177
10215
|
"name": "path",
|
|
10178
10216
|
"type": {
|
|
@@ -10188,7 +10226,7 @@
|
|
|
10188
10226
|
"immutable": true,
|
|
10189
10227
|
"locationInModule": {
|
|
10190
10228
|
"filename": "lib/iceberg/iceberg-schema-history.ts",
|
|
10191
|
-
"line":
|
|
10229
|
+
"line": 41
|
|
10192
10230
|
},
|
|
10193
10231
|
"name": "required",
|
|
10194
10232
|
"type": {
|
|
@@ -10204,7 +10242,7 @@
|
|
|
10204
10242
|
"immutable": true,
|
|
10205
10243
|
"locationInModule": {
|
|
10206
10244
|
"filename": "lib/iceberg/iceberg-schema-history.ts",
|
|
10207
|
-
"line":
|
|
10245
|
+
"line": 38
|
|
10208
10246
|
},
|
|
10209
10247
|
"name": "type",
|
|
10210
10248
|
"type": {
|
|
@@ -10432,7 +10470,7 @@
|
|
|
10432
10470
|
"kind": "enum",
|
|
10433
10471
|
"locationInModule": {
|
|
10434
10472
|
"filename": "lib/iceberg/iceberg-table.ts",
|
|
10435
|
-
"line":
|
|
10473
|
+
"line": 76
|
|
10436
10474
|
},
|
|
10437
10475
|
"members": [
|
|
10438
10476
|
{
|
|
@@ -10464,7 +10502,7 @@
|
|
|
10464
10502
|
"kind": "interface",
|
|
10465
10503
|
"locationInModule": {
|
|
10466
10504
|
"filename": "lib/iceberg/iceberg-table.ts",
|
|
10467
|
-
"line":
|
|
10505
|
+
"line": 114
|
|
10468
10506
|
},
|
|
10469
10507
|
"name": "IcebergPartitionField",
|
|
10470
10508
|
"properties": [
|
|
@@ -10478,7 +10516,7 @@
|
|
|
10478
10516
|
"immutable": true,
|
|
10479
10517
|
"locationInModule": {
|
|
10480
10518
|
"filename": "lib/iceberg/iceberg-table.ts",
|
|
10481
|
-
"line":
|
|
10519
|
+
"line": 145
|
|
10482
10520
|
},
|
|
10483
10521
|
"name": "fieldId",
|
|
10484
10522
|
"type": {
|
|
@@ -10494,7 +10532,7 @@
|
|
|
10494
10532
|
"immutable": true,
|
|
10495
10533
|
"locationInModule": {
|
|
10496
10534
|
"filename": "lib/iceberg/iceberg-table.ts",
|
|
10497
|
-
"line":
|
|
10535
|
+
"line": 116
|
|
10498
10536
|
},
|
|
10499
10537
|
"name": "sourceColumn",
|
|
10500
10538
|
"type": {
|
|
@@ -10510,7 +10548,7 @@
|
|
|
10510
10548
|
"immutable": true,
|
|
10511
10549
|
"locationInModule": {
|
|
10512
10550
|
"filename": "lib/iceberg/iceberg-table.ts",
|
|
10513
|
-
"line":
|
|
10551
|
+
"line": 119
|
|
10514
10552
|
},
|
|
10515
10553
|
"name": "transform",
|
|
10516
10554
|
"type": {
|
|
@@ -10527,7 +10565,7 @@
|
|
|
10527
10565
|
"immutable": true,
|
|
10528
10566
|
"locationInModule": {
|
|
10529
10567
|
"filename": "lib/iceberg/iceberg-table.ts",
|
|
10530
|
-
"line":
|
|
10568
|
+
"line": 126
|
|
10531
10569
|
},
|
|
10532
10570
|
"name": "name",
|
|
10533
10571
|
"optional": true,
|
|
@@ -10549,7 +10587,7 @@
|
|
|
10549
10587
|
"kind": "interface",
|
|
10550
10588
|
"locationInModule": {
|
|
10551
10589
|
"filename": "lib/iceberg/iceberg-schema-history.ts",
|
|
10552
|
-
"line":
|
|
10590
|
+
"line": 48
|
|
10553
10591
|
},
|
|
10554
10592
|
"name": "IcebergPartitionFieldHistory",
|
|
10555
10593
|
"properties": [
|
|
@@ -10562,7 +10600,7 @@
|
|
|
10562
10600
|
"immutable": true,
|
|
10563
10601
|
"locationInModule": {
|
|
10564
10602
|
"filename": "lib/iceberg/iceberg-schema-history.ts",
|
|
10565
|
-
"line":
|
|
10603
|
+
"line": 50
|
|
10566
10604
|
},
|
|
10567
10605
|
"name": "fieldId",
|
|
10568
10606
|
"type": {
|
|
@@ -10578,7 +10616,7 @@
|
|
|
10578
10616
|
"immutable": true,
|
|
10579
10617
|
"locationInModule": {
|
|
10580
10618
|
"filename": "lib/iceberg/iceberg-schema-history.ts",
|
|
10581
|
-
"line":
|
|
10619
|
+
"line": 53
|
|
10582
10620
|
},
|
|
10583
10621
|
"name": "name",
|
|
10584
10622
|
"type": {
|
|
@@ -10594,7 +10632,7 @@
|
|
|
10594
10632
|
"immutable": true,
|
|
10595
10633
|
"locationInModule": {
|
|
10596
10634
|
"filename": "lib/iceberg/iceberg-schema-history.ts",
|
|
10597
|
-
"line":
|
|
10635
|
+
"line": 56
|
|
10598
10636
|
},
|
|
10599
10637
|
"name": "sourceId",
|
|
10600
10638
|
"type": {
|
|
@@ -10610,7 +10648,7 @@
|
|
|
10610
10648
|
"immutable": true,
|
|
10611
10649
|
"locationInModule": {
|
|
10612
10650
|
"filename": "lib/iceberg/iceberg-schema-history.ts",
|
|
10613
|
-
"line":
|
|
10651
|
+
"line": 59
|
|
10614
10652
|
},
|
|
10615
10653
|
"name": "transform",
|
|
10616
10654
|
"type": {
|
|
@@ -11291,7 +11329,7 @@
|
|
|
11291
11329
|
"kind": "class",
|
|
11292
11330
|
"locationInModule": {
|
|
11293
11331
|
"filename": "lib/iceberg/iceberg-schema-history.ts",
|
|
11294
|
-
"line":
|
|
11332
|
+
"line": 126
|
|
11295
11333
|
},
|
|
11296
11334
|
"methods": [
|
|
11297
11335
|
{
|
|
@@ -11302,7 +11340,7 @@
|
|
|
11302
11340
|
},
|
|
11303
11341
|
"locationInModule": {
|
|
11304
11342
|
"filename": "lib/iceberg/iceberg-schema-history.ts",
|
|
11305
|
-
"line":
|
|
11343
|
+
"line": 154
|
|
11306
11344
|
},
|
|
11307
11345
|
"name": "append",
|
|
11308
11346
|
"parameters": [
|
|
@@ -11349,7 +11387,7 @@
|
|
|
11349
11387
|
},
|
|
11350
11388
|
"locationInModule": {
|
|
11351
11389
|
"filename": "lib/iceberg/iceberg-schema-history.ts",
|
|
11352
|
-
"line":
|
|
11390
|
+
"line": 199
|
|
11353
11391
|
},
|
|
11354
11392
|
"name": "fromJson",
|
|
11355
11393
|
"parameters": [
|
|
@@ -11377,7 +11415,7 @@
|
|
|
11377
11415
|
},
|
|
11378
11416
|
"locationInModule": {
|
|
11379
11417
|
"filename": "lib/iceberg/iceberg-schema-history.ts",
|
|
11380
|
-
"line":
|
|
11418
|
+
"line": 167
|
|
11381
11419
|
},
|
|
11382
11420
|
"name": "toJson",
|
|
11383
11421
|
"parameters": [
|
|
@@ -11406,7 +11444,7 @@
|
|
|
11406
11444
|
},
|
|
11407
11445
|
"locationInModule": {
|
|
11408
11446
|
"filename": "lib/iceberg/iceberg-schema-history.ts",
|
|
11409
|
-
"line":
|
|
11447
|
+
"line": 209
|
|
11410
11448
|
},
|
|
11411
11449
|
"name": "updateFromCloudAssembly",
|
|
11412
11450
|
"parameters": [
|
|
@@ -11440,7 +11478,7 @@
|
|
|
11440
11478
|
},
|
|
11441
11479
|
"locationInModule": {
|
|
11442
11480
|
"filename": "lib/iceberg/iceberg-schema-history.ts",
|
|
11443
|
-
"line":
|
|
11481
|
+
"line": 133
|
|
11444
11482
|
},
|
|
11445
11483
|
"name": "validateSchemaEvolution",
|
|
11446
11484
|
"parameters": [
|
|
@@ -11490,7 +11528,7 @@
|
|
|
11490
11528
|
"kind": "interface",
|
|
11491
11529
|
"locationInModule": {
|
|
11492
11530
|
"filename": "lib/iceberg/iceberg-schema-history.ts",
|
|
11493
|
-
"line":
|
|
11531
|
+
"line": 75
|
|
11494
11532
|
},
|
|
11495
11533
|
"name": "IcebergSchemaHistoryFile",
|
|
11496
11534
|
"properties": [
|
|
@@ -11503,7 +11541,7 @@
|
|
|
11503
11541
|
"immutable": true,
|
|
11504
11542
|
"locationInModule": {
|
|
11505
11543
|
"filename": "lib/iceberg/iceberg-schema-history.ts",
|
|
11506
|
-
"line":
|
|
11544
|
+
"line": 77
|
|
11507
11545
|
},
|
|
11508
11546
|
"name": "tables",
|
|
11509
11547
|
"type": {
|
|
@@ -11529,7 +11567,7 @@
|
|
|
11529
11567
|
"kind": "interface",
|
|
11530
11568
|
"locationInModule": {
|
|
11531
11569
|
"filename": "lib/iceberg/iceberg-schema-history.ts",
|
|
11532
|
-
"line":
|
|
11570
|
+
"line": 111
|
|
11533
11571
|
},
|
|
11534
11572
|
"name": "IcebergSchemaViolation",
|
|
11535
11573
|
"properties": [
|
|
@@ -11542,7 +11580,7 @@
|
|
|
11542
11580
|
"immutable": true,
|
|
11543
11581
|
"locationInModule": {
|
|
11544
11582
|
"filename": "lib/iceberg/iceberg-schema-history.ts",
|
|
11545
|
-
"line":
|
|
11583
|
+
"line": 113
|
|
11546
11584
|
},
|
|
11547
11585
|
"name": "kind",
|
|
11548
11586
|
"type": {
|
|
@@ -11558,7 +11596,7 @@
|
|
|
11558
11596
|
"immutable": true,
|
|
11559
11597
|
"locationInModule": {
|
|
11560
11598
|
"filename": "lib/iceberg/iceberg-schema-history.ts",
|
|
11561
|
-
"line":
|
|
11599
|
+
"line": 116
|
|
11562
11600
|
},
|
|
11563
11601
|
"name": "message",
|
|
11564
11602
|
"type": {
|
|
@@ -11578,7 +11616,7 @@
|
|
|
11578
11616
|
"kind": "enum",
|
|
11579
11617
|
"locationInModule": {
|
|
11580
11618
|
"filename": "lib/iceberg/iceberg-schema-history.ts",
|
|
11581
|
-
"line":
|
|
11619
|
+
"line": 90
|
|
11582
11620
|
},
|
|
11583
11621
|
"members": [
|
|
11584
11622
|
{
|
|
@@ -11637,7 +11675,7 @@
|
|
|
11637
11675
|
"kind": "enum",
|
|
11638
11676
|
"locationInModule": {
|
|
11639
11677
|
"filename": "lib/iceberg/iceberg-table.ts",
|
|
11640
|
-
"line":
|
|
11678
|
+
"line": 67
|
|
11641
11679
|
},
|
|
11642
11680
|
"members": [
|
|
11643
11681
|
{
|
|
@@ -11669,7 +11707,7 @@
|
|
|
11669
11707
|
"kind": "interface",
|
|
11670
11708
|
"locationInModule": {
|
|
11671
11709
|
"filename": "lib/iceberg/iceberg-table.ts",
|
|
11672
|
-
"line":
|
|
11710
|
+
"line": 149
|
|
11673
11711
|
},
|
|
11674
11712
|
"name": "IcebergSortField",
|
|
11675
11713
|
"properties": [
|
|
@@ -11682,7 +11720,7 @@
|
|
|
11682
11720
|
"immutable": true,
|
|
11683
11721
|
"locationInModule": {
|
|
11684
11722
|
"filename": "lib/iceberg/iceberg-table.ts",
|
|
11685
|
-
"line":
|
|
11723
|
+
"line": 151
|
|
11686
11724
|
},
|
|
11687
11725
|
"name": "sourceColumn",
|
|
11688
11726
|
"type": {
|
|
@@ -11699,7 +11737,7 @@
|
|
|
11699
11737
|
"immutable": true,
|
|
11700
11738
|
"locationInModule": {
|
|
11701
11739
|
"filename": "lib/iceberg/iceberg-table.ts",
|
|
11702
|
-
"line":
|
|
11740
|
+
"line": 157
|
|
11703
11741
|
},
|
|
11704
11742
|
"name": "direction",
|
|
11705
11743
|
"optional": true,
|
|
@@ -11717,7 +11755,7 @@
|
|
|
11717
11755
|
"immutable": true,
|
|
11718
11756
|
"locationInModule": {
|
|
11719
11757
|
"filename": "lib/iceberg/iceberg-table.ts",
|
|
11720
|
-
"line":
|
|
11758
|
+
"line": 160
|
|
11721
11759
|
},
|
|
11722
11760
|
"name": "nullOrder",
|
|
11723
11761
|
"optional": true,
|
|
@@ -11735,7 +11773,7 @@
|
|
|
11735
11773
|
"immutable": true,
|
|
11736
11774
|
"locationInModule": {
|
|
11737
11775
|
"filename": "lib/iceberg/iceberg-table.ts",
|
|
11738
|
-
"line":
|
|
11776
|
+
"line": 154
|
|
11739
11777
|
},
|
|
11740
11778
|
"name": "transform",
|
|
11741
11779
|
"optional": true,
|
|
@@ -11862,7 +11900,7 @@
|
|
|
11862
11900
|
},
|
|
11863
11901
|
"locationInModule": {
|
|
11864
11902
|
"filename": "lib/iceberg/iceberg-table.ts",
|
|
11865
|
-
"line":
|
|
11903
|
+
"line": 311
|
|
11866
11904
|
},
|
|
11867
11905
|
"parameters": [
|
|
11868
11906
|
{
|
|
@@ -11891,7 +11929,7 @@
|
|
|
11891
11929
|
"kind": "class",
|
|
11892
11930
|
"locationInModule": {
|
|
11893
11931
|
"filename": "lib/iceberg/iceberg-table.ts",
|
|
11894
|
-
"line":
|
|
11932
|
+
"line": 284
|
|
11895
11933
|
},
|
|
11896
11934
|
"methods": [
|
|
11897
11935
|
{
|
|
@@ -11901,7 +11939,7 @@
|
|
|
11901
11939
|
},
|
|
11902
11940
|
"locationInModule": {
|
|
11903
11941
|
"filename": "lib/iceberg/iceberg-table.ts",
|
|
11904
|
-
"line":
|
|
11942
|
+
"line": 390
|
|
11905
11943
|
},
|
|
11906
11944
|
"name": "creationOrderFieldIds",
|
|
11907
11945
|
"parameters": [
|
|
@@ -11940,7 +11978,7 @@
|
|
|
11940
11978
|
},
|
|
11941
11979
|
"locationInModule": {
|
|
11942
11980
|
"filename": "lib/iceberg/iceberg-table.ts",
|
|
11943
|
-
"line":
|
|
11981
|
+
"line": 400
|
|
11944
11982
|
},
|
|
11945
11983
|
"name": "fromIcebergTableAttributes",
|
|
11946
11984
|
"parameters": [
|
|
@@ -11973,11 +12011,11 @@
|
|
|
11973
12011
|
{
|
|
11974
12012
|
"docs": {
|
|
11975
12013
|
"stability": "experimental",
|
|
11976
|
-
"summary": "Grant Glue
|
|
12014
|
+
"summary": "Grant Glue + S3 read on this table."
|
|
11977
12015
|
},
|
|
11978
12016
|
"locationInModule": {
|
|
11979
12017
|
"filename": "lib/iceberg/iceberg-table.ts",
|
|
11980
|
-
"line":
|
|
12018
|
+
"line": 447
|
|
11981
12019
|
},
|
|
11982
12020
|
"name": "grantRead",
|
|
11983
12021
|
"overrides": "cdk-glue-iceberg-table.IIcebergTable",
|
|
@@ -11987,6 +12025,13 @@
|
|
|
11987
12025
|
"type": {
|
|
11988
12026
|
"fqn": "aws-cdk-lib.aws_iam.IGrantable"
|
|
11989
12027
|
}
|
|
12028
|
+
},
|
|
12029
|
+
{
|
|
12030
|
+
"name": "options",
|
|
12031
|
+
"optional": true,
|
|
12032
|
+
"type": {
|
|
12033
|
+
"fqn": "cdk-glue-iceberg-table.IcebergTableGrantOptions"
|
|
12034
|
+
}
|
|
11990
12035
|
}
|
|
11991
12036
|
],
|
|
11992
12037
|
"returns": {
|
|
@@ -12002,7 +12047,7 @@
|
|
|
12002
12047
|
},
|
|
12003
12048
|
"locationInModule": {
|
|
12004
12049
|
"filename": "lib/iceberg/iceberg-table.ts",
|
|
12005
|
-
"line":
|
|
12050
|
+
"line": 457
|
|
12006
12051
|
},
|
|
12007
12052
|
"name": "grantReadWrite",
|
|
12008
12053
|
"overrides": "cdk-glue-iceberg-table.IIcebergTable",
|
|
@@ -12012,6 +12057,13 @@
|
|
|
12012
12057
|
"type": {
|
|
12013
12058
|
"fqn": "aws-cdk-lib.aws_iam.IGrantable"
|
|
12014
12059
|
}
|
|
12060
|
+
},
|
|
12061
|
+
{
|
|
12062
|
+
"name": "options",
|
|
12063
|
+
"optional": true,
|
|
12064
|
+
"type": {
|
|
12065
|
+
"fqn": "cdk-glue-iceberg-table.IcebergTableGrantOptions"
|
|
12066
|
+
}
|
|
12015
12067
|
}
|
|
12016
12068
|
],
|
|
12017
12069
|
"returns": {
|
|
@@ -12023,11 +12075,11 @@
|
|
|
12023
12075
|
{
|
|
12024
12076
|
"docs": {
|
|
12025
12077
|
"stability": "experimental",
|
|
12026
|
-
"summary": "Grant Glue
|
|
12078
|
+
"summary": "Grant Glue + S3 write on this table."
|
|
12027
12079
|
},
|
|
12028
12080
|
"locationInModule": {
|
|
12029
12081
|
"filename": "lib/iceberg/iceberg-table.ts",
|
|
12030
|
-
"line":
|
|
12082
|
+
"line": 452
|
|
12031
12083
|
},
|
|
12032
12084
|
"name": "grantWrite",
|
|
12033
12085
|
"overrides": "cdk-glue-iceberg-table.IIcebergTable",
|
|
@@ -12037,6 +12089,13 @@
|
|
|
12037
12089
|
"type": {
|
|
12038
12090
|
"fqn": "aws-cdk-lib.aws_iam.IGrantable"
|
|
12039
12091
|
}
|
|
12092
|
+
},
|
|
12093
|
+
{
|
|
12094
|
+
"name": "options",
|
|
12095
|
+
"optional": true,
|
|
12096
|
+
"type": {
|
|
12097
|
+
"fqn": "cdk-glue-iceberg-table.IcebergTableGrantOptions"
|
|
12098
|
+
}
|
|
12040
12099
|
}
|
|
12041
12100
|
],
|
|
12042
12101
|
"returns": {
|
|
@@ -12056,7 +12115,7 @@
|
|
|
12056
12115
|
"immutable": true,
|
|
12057
12116
|
"locationInModule": {
|
|
12058
12117
|
"filename": "lib/iceberg/iceberg-table.ts",
|
|
12059
|
-
"line":
|
|
12118
|
+
"line": 292
|
|
12060
12119
|
},
|
|
12061
12120
|
"name": "database",
|
|
12062
12121
|
"overrides": "cdk-glue-iceberg-table.IIcebergTable",
|
|
@@ -12072,7 +12131,7 @@
|
|
|
12072
12131
|
"immutable": true,
|
|
12073
12132
|
"locationInModule": {
|
|
12074
12133
|
"filename": "lib/iceberg/iceberg-table.ts",
|
|
12075
|
-
"line":
|
|
12134
|
+
"line": 301
|
|
12076
12135
|
},
|
|
12077
12136
|
"name": "dataFormat",
|
|
12078
12137
|
"type": {
|
|
@@ -12087,7 +12146,7 @@
|
|
|
12087
12146
|
"immutable": true,
|
|
12088
12147
|
"locationInModule": {
|
|
12089
12148
|
"filename": "lib/iceberg/iceberg-table.ts",
|
|
12090
|
-
"line":
|
|
12149
|
+
"line": 304
|
|
12091
12150
|
},
|
|
12092
12151
|
"name": "formatVersion",
|
|
12093
12152
|
"type": {
|
|
@@ -12102,7 +12161,7 @@
|
|
|
12102
12161
|
"immutable": true,
|
|
12103
12162
|
"locationInModule": {
|
|
12104
12163
|
"filename": "lib/iceberg/iceberg-table.ts",
|
|
12105
|
-
"line":
|
|
12164
|
+
"line": 295
|
|
12106
12165
|
},
|
|
12107
12166
|
"name": "location",
|
|
12108
12167
|
"overrides": "cdk-glue-iceberg-table.IIcebergTable",
|
|
@@ -12118,7 +12177,7 @@
|
|
|
12118
12177
|
"immutable": true,
|
|
12119
12178
|
"locationInModule": {
|
|
12120
12179
|
"filename": "lib/iceberg/iceberg-table.ts",
|
|
12121
|
-
"line":
|
|
12180
|
+
"line": 307
|
|
12122
12181
|
},
|
|
12123
12182
|
"name": "resource",
|
|
12124
12183
|
"type": {
|
|
@@ -12133,7 +12192,7 @@
|
|
|
12133
12192
|
"immutable": true,
|
|
12134
12193
|
"locationInModule": {
|
|
12135
12194
|
"filename": "lib/iceberg/iceberg-table.ts",
|
|
12136
|
-
"line":
|
|
12195
|
+
"line": 286
|
|
12137
12196
|
},
|
|
12138
12197
|
"name": "tableArn",
|
|
12139
12198
|
"overrides": "cdk-glue-iceberg-table.IIcebergTable",
|
|
@@ -12149,13 +12208,30 @@
|
|
|
12149
12208
|
"immutable": true,
|
|
12150
12209
|
"locationInModule": {
|
|
12151
12210
|
"filename": "lib/iceberg/iceberg-table.ts",
|
|
12152
|
-
"line":
|
|
12211
|
+
"line": 289
|
|
12153
12212
|
},
|
|
12154
12213
|
"name": "tableName",
|
|
12155
12214
|
"overrides": "cdk-glue-iceberg-table.IIcebergTable",
|
|
12156
12215
|
"type": {
|
|
12157
12216
|
"primitive": "string"
|
|
12158
12217
|
}
|
|
12218
|
+
},
|
|
12219
|
+
{
|
|
12220
|
+
"docs": {
|
|
12221
|
+
"stability": "experimental",
|
|
12222
|
+
"summary": "KMS key the table's objects are encrypted with, as given in the props."
|
|
12223
|
+
},
|
|
12224
|
+
"immutable": true,
|
|
12225
|
+
"locationInModule": {
|
|
12226
|
+
"filename": "lib/iceberg/iceberg-table.ts",
|
|
12227
|
+
"line": 298
|
|
12228
|
+
},
|
|
12229
|
+
"name": "encryptionKey",
|
|
12230
|
+
"optional": true,
|
|
12231
|
+
"overrides": "cdk-glue-iceberg-table.IIcebergTable",
|
|
12232
|
+
"type": {
|
|
12233
|
+
"fqn": "aws-cdk-lib.aws_kms.IKey"
|
|
12234
|
+
}
|
|
12159
12235
|
}
|
|
12160
12236
|
],
|
|
12161
12237
|
"symbolId": "lib/iceberg/iceberg-table:IcebergTable"
|
|
@@ -12171,7 +12247,7 @@
|
|
|
12171
12247
|
"kind": "interface",
|
|
12172
12248
|
"locationInModule": {
|
|
12173
12249
|
"filename": "lib/iceberg/iceberg-table.ts",
|
|
12174
|
-
"line":
|
|
12250
|
+
"line": 463
|
|
12175
12251
|
},
|
|
12176
12252
|
"name": "IcebergTableAttributes",
|
|
12177
12253
|
"properties": [
|
|
@@ -12184,7 +12260,7 @@
|
|
|
12184
12260
|
"immutable": true,
|
|
12185
12261
|
"locationInModule": {
|
|
12186
12262
|
"filename": "lib/iceberg/iceberg-table.ts",
|
|
12187
|
-
"line":
|
|
12263
|
+
"line": 465
|
|
12188
12264
|
},
|
|
12189
12265
|
"name": "database",
|
|
12190
12266
|
"type": {
|
|
@@ -12200,7 +12276,7 @@
|
|
|
12200
12276
|
"immutable": true,
|
|
12201
12277
|
"locationInModule": {
|
|
12202
12278
|
"filename": "lib/iceberg/iceberg-table.ts",
|
|
12203
|
-
"line":
|
|
12279
|
+
"line": 471
|
|
12204
12280
|
},
|
|
12205
12281
|
"name": "location",
|
|
12206
12282
|
"type": {
|
|
@@ -12216,16 +12292,88 @@
|
|
|
12216
12292
|
"immutable": true,
|
|
12217
12293
|
"locationInModule": {
|
|
12218
12294
|
"filename": "lib/iceberg/iceberg-table.ts",
|
|
12219
|
-
"line":
|
|
12295
|
+
"line": 468
|
|
12220
12296
|
},
|
|
12221
12297
|
"name": "tableName",
|
|
12222
12298
|
"type": {
|
|
12223
12299
|
"primitive": "string"
|
|
12224
12300
|
}
|
|
12301
|
+
},
|
|
12302
|
+
{
|
|
12303
|
+
"abstract": true,
|
|
12304
|
+
"docs": {
|
|
12305
|
+
"remarks": "grants add the actions of `IcebergTableProps.encryptionKey` on the whole key.",
|
|
12306
|
+
"stability": "experimental",
|
|
12307
|
+
"summary": "KMS key the table's objects are encrypted with;"
|
|
12308
|
+
},
|
|
12309
|
+
"immutable": true,
|
|
12310
|
+
"locationInModule": {
|
|
12311
|
+
"filename": "lib/iceberg/iceberg-table.ts",
|
|
12312
|
+
"line": 474
|
|
12313
|
+
},
|
|
12314
|
+
"name": "encryptionKey",
|
|
12315
|
+
"optional": true,
|
|
12316
|
+
"type": {
|
|
12317
|
+
"fqn": "aws-cdk-lib.aws_kms.IKey"
|
|
12318
|
+
}
|
|
12225
12319
|
}
|
|
12226
12320
|
],
|
|
12227
12321
|
"symbolId": "lib/iceberg/iceberg-table:IcebergTableAttributes"
|
|
12228
12322
|
},
|
|
12323
|
+
"cdk-glue-iceberg-table.IcebergTableGrantOptions": {
|
|
12324
|
+
"assembly": "cdk-glue-iceberg-table",
|
|
12325
|
+
"datatype": true,
|
|
12326
|
+
"docs": {
|
|
12327
|
+
"stability": "experimental",
|
|
12328
|
+
"summary": "Options for `grantRead`, `grantWrite` and `grantReadWrite` on an Iceberg table."
|
|
12329
|
+
},
|
|
12330
|
+
"fqn": "cdk-glue-iceberg-table.IcebergTableGrantOptions",
|
|
12331
|
+
"kind": "interface",
|
|
12332
|
+
"locationInModule": {
|
|
12333
|
+
"filename": "lib/iceberg/iceberg-table-grants.ts",
|
|
12334
|
+
"line": 193
|
|
12335
|
+
},
|
|
12336
|
+
"name": "IcebergTableGrantOptions",
|
|
12337
|
+
"properties": [
|
|
12338
|
+
{
|
|
12339
|
+
"abstract": true,
|
|
12340
|
+
"docs": {
|
|
12341
|
+
"remarks": "Read grants add `kms:Decrypt`; write grants add `kms:Decrypt`,\n`kms:Encrypt` and `kms:GenerateDataKey`, on the whole key.",
|
|
12342
|
+
"stability": "experimental",
|
|
12343
|
+
"summary": "KMS key the account's Data Catalog is encrypted with (`SSE-KMS`)."
|
|
12344
|
+
},
|
|
12345
|
+
"immutable": true,
|
|
12346
|
+
"locationInModule": {
|
|
12347
|
+
"filename": "lib/iceberg/iceberg-table-grants.ts",
|
|
12348
|
+
"line": 206
|
|
12349
|
+
},
|
|
12350
|
+
"name": "catalogEncryptionKey",
|
|
12351
|
+
"optional": true,
|
|
12352
|
+
"type": {
|
|
12353
|
+
"fqn": "aws-cdk-lib.aws_kms.IKey"
|
|
12354
|
+
}
|
|
12355
|
+
},
|
|
12356
|
+
{
|
|
12357
|
+
"abstract": true,
|
|
12358
|
+
"docs": {
|
|
12359
|
+
"remarks": "The Lake\nFormation permissions themselves are not created. Defaults to `false`.",
|
|
12360
|
+
"stability": "experimental",
|
|
12361
|
+
"summary": "Add `lakeformation:GetDataAccess` on `*`, which Athena needs to read a table whose location is registered with Lake Formation."
|
|
12362
|
+
},
|
|
12363
|
+
"immutable": true,
|
|
12364
|
+
"locationInModule": {
|
|
12365
|
+
"filename": "lib/iceberg/iceberg-table-grants.ts",
|
|
12366
|
+
"line": 199
|
|
12367
|
+
},
|
|
12368
|
+
"name": "lakeFormationDataAccess",
|
|
12369
|
+
"optional": true,
|
|
12370
|
+
"type": {
|
|
12371
|
+
"primitive": "boolean"
|
|
12372
|
+
}
|
|
12373
|
+
}
|
|
12374
|
+
],
|
|
12375
|
+
"symbolId": "lib/iceberg/iceberg-table-grants:IcebergTableGrantOptions"
|
|
12376
|
+
},
|
|
12229
12377
|
"cdk-glue-iceberg-table.IcebergTableHistory": {
|
|
12230
12378
|
"assembly": "cdk-glue-iceberg-table",
|
|
12231
12379
|
"datatype": true,
|
|
@@ -12237,7 +12385,7 @@
|
|
|
12237
12385
|
"kind": "interface",
|
|
12238
12386
|
"locationInModule": {
|
|
12239
12387
|
"filename": "lib/iceberg/iceberg-schema-history.ts",
|
|
12240
|
-
"line":
|
|
12388
|
+
"line": 63
|
|
12241
12389
|
},
|
|
12242
12390
|
"name": "IcebergTableHistory",
|
|
12243
12391
|
"properties": [
|
|
@@ -12250,7 +12398,7 @@
|
|
|
12250
12398
|
"immutable": true,
|
|
12251
12399
|
"locationInModule": {
|
|
12252
12400
|
"filename": "lib/iceberg/iceberg-schema-history.ts",
|
|
12253
|
-
"line":
|
|
12401
|
+
"line": 68
|
|
12254
12402
|
},
|
|
12255
12403
|
"name": "fields",
|
|
12256
12404
|
"type": {
|
|
@@ -12271,7 +12419,7 @@
|
|
|
12271
12419
|
"immutable": true,
|
|
12272
12420
|
"locationInModule": {
|
|
12273
12421
|
"filename": "lib/iceberg/iceberg-schema-history.ts",
|
|
12274
|
-
"line":
|
|
12422
|
+
"line": 71
|
|
12275
12423
|
},
|
|
12276
12424
|
"name": "partitionFields",
|
|
12277
12425
|
"type": {
|
|
@@ -12292,7 +12440,7 @@
|
|
|
12292
12440
|
"immutable": true,
|
|
12293
12441
|
"locationInModule": {
|
|
12294
12442
|
"filename": "lib/iceberg/iceberg-schema-history.ts",
|
|
12295
|
-
"line":
|
|
12443
|
+
"line": 65
|
|
12296
12444
|
},
|
|
12297
12445
|
"name": "tableName",
|
|
12298
12446
|
"type": {
|
|
@@ -12313,7 +12461,7 @@
|
|
|
12313
12461
|
"kind": "interface",
|
|
12314
12462
|
"locationInModule": {
|
|
12315
12463
|
"filename": "lib/iceberg/iceberg-table.ts",
|
|
12316
|
-
"line":
|
|
12464
|
+
"line": 164
|
|
12317
12465
|
},
|
|
12318
12466
|
"name": "IcebergTableProps",
|
|
12319
12467
|
"properties": [
|
|
@@ -12327,7 +12475,7 @@
|
|
|
12327
12475
|
"immutable": true,
|
|
12328
12476
|
"locationInModule": {
|
|
12329
12477
|
"filename": "lib/iceberg/iceberg-table.ts",
|
|
12330
|
-
"line":
|
|
12478
|
+
"line": 172
|
|
12331
12479
|
},
|
|
12332
12480
|
"name": "columns",
|
|
12333
12481
|
"type": {
|
|
@@ -12348,7 +12496,7 @@
|
|
|
12348
12496
|
"immutable": true,
|
|
12349
12497
|
"locationInModule": {
|
|
12350
12498
|
"filename": "lib/iceberg/iceberg-table.ts",
|
|
12351
|
-
"line":
|
|
12499
|
+
"line": 166
|
|
12352
12500
|
},
|
|
12353
12501
|
"name": "database",
|
|
12354
12502
|
"type": {
|
|
@@ -12365,7 +12513,7 @@
|
|
|
12365
12513
|
"immutable": true,
|
|
12366
12514
|
"locationInModule": {
|
|
12367
12515
|
"filename": "lib/iceberg/iceberg-table.ts",
|
|
12368
|
-
"line":
|
|
12516
|
+
"line": 205
|
|
12369
12517
|
},
|
|
12370
12518
|
"name": "formatVersion",
|
|
12371
12519
|
"type": {
|
|
@@ -12382,7 +12530,7 @@
|
|
|
12382
12530
|
"immutable": true,
|
|
12383
12531
|
"locationInModule": {
|
|
12384
12532
|
"filename": "lib/iceberg/iceberg-table.ts",
|
|
12385
|
-
"line":
|
|
12533
|
+
"line": 175
|
|
12386
12534
|
},
|
|
12387
12535
|
"name": "location",
|
|
12388
12536
|
"type": {
|
|
@@ -12398,7 +12546,7 @@
|
|
|
12398
12546
|
"immutable": true,
|
|
12399
12547
|
"locationInModule": {
|
|
12400
12548
|
"filename": "lib/iceberg/iceberg-table.ts",
|
|
12401
|
-
"line":
|
|
12549
|
+
"line": 169
|
|
12402
12550
|
},
|
|
12403
12551
|
"name": "tableName",
|
|
12404
12552
|
"type": {
|
|
@@ -12415,7 +12563,7 @@
|
|
|
12415
12563
|
"immutable": true,
|
|
12416
12564
|
"locationInModule": {
|
|
12417
12565
|
"filename": "lib/iceberg/iceberg-table.ts",
|
|
12418
|
-
"line":
|
|
12566
|
+
"line": 225
|
|
12419
12567
|
},
|
|
12420
12568
|
"name": "comment",
|
|
12421
12569
|
"optional": true,
|
|
@@ -12433,7 +12581,7 @@
|
|
|
12433
12581
|
"immutable": true,
|
|
12434
12582
|
"locationInModule": {
|
|
12435
12583
|
"filename": "lib/iceberg/iceberg-table.ts",
|
|
12436
|
-
"line":
|
|
12584
|
+
"line": 202
|
|
12437
12585
|
},
|
|
12438
12586
|
"name": "dataFormat",
|
|
12439
12587
|
"optional": true,
|
|
@@ -12441,6 +12589,24 @@
|
|
|
12441
12589
|
"fqn": "cdk-glue-iceberg-table.IcebergDataFormat"
|
|
12442
12590
|
}
|
|
12443
12591
|
},
|
|
12592
|
+
{
|
|
12593
|
+
"abstract": true,
|
|
12594
|
+
"docs": {
|
|
12595
|
+
"remarks": "When set, read grants\nadd `kms:Decrypt` and write grants add `kms:Decrypt` and\n`kms:GenerateDataKey`, on the whole key. Defaults to no KMS permission.",
|
|
12596
|
+
"stability": "experimental",
|
|
12597
|
+
"summary": "KMS key the table's bucket encrypts objects with."
|
|
12598
|
+
},
|
|
12599
|
+
"immutable": true,
|
|
12600
|
+
"locationInModule": {
|
|
12601
|
+
"filename": "lib/iceberg/iceberg-table.ts",
|
|
12602
|
+
"line": 182
|
|
12603
|
+
},
|
|
12604
|
+
"name": "encryptionKey",
|
|
12605
|
+
"optional": true,
|
|
12606
|
+
"type": {
|
|
12607
|
+
"fqn": "aws-cdk-lib.aws_kms.IKey"
|
|
12608
|
+
}
|
|
12609
|
+
},
|
|
12444
12610
|
{
|
|
12445
12611
|
"abstract": true,
|
|
12446
12612
|
"docs": {
|
|
@@ -12451,7 +12617,7 @@
|
|
|
12451
12617
|
"immutable": true,
|
|
12452
12618
|
"locationInModule": {
|
|
12453
12619
|
"filename": "lib/iceberg/iceberg-table.ts",
|
|
12454
|
-
"line":
|
|
12620
|
+
"line": 199
|
|
12455
12621
|
},
|
|
12456
12622
|
"name": "identifierFieldNames",
|
|
12457
12623
|
"optional": true,
|
|
@@ -12474,7 +12640,7 @@
|
|
|
12474
12640
|
"immutable": true,
|
|
12475
12641
|
"locationInModule": {
|
|
12476
12642
|
"filename": "lib/iceberg/iceberg-table.ts",
|
|
12477
|
-
"line":
|
|
12643
|
+
"line": 185
|
|
12478
12644
|
},
|
|
12479
12645
|
"name": "partitionSpec",
|
|
12480
12646
|
"optional": true,
|
|
@@ -12497,7 +12663,7 @@
|
|
|
12497
12663
|
"immutable": true,
|
|
12498
12664
|
"locationInModule": {
|
|
12499
12665
|
"filename": "lib/iceberg/iceberg-table.ts",
|
|
12500
|
-
"line":
|
|
12666
|
+
"line": 232
|
|
12501
12667
|
},
|
|
12502
12668
|
"name": "removalPolicy",
|
|
12503
12669
|
"optional": true,
|
|
@@ -12509,14 +12675,14 @@
|
|
|
12509
12675
|
"abstract": true,
|
|
12510
12676
|
"docs": {
|
|
12511
12677
|
"default": "- no history check",
|
|
12512
|
-
"remarks": "
|
|
12678
|
+
"remarks": "the README section \"Checking changes against a schema history\"\nlists what synth checks against it.",
|
|
12513
12679
|
"stability": "experimental",
|
|
12514
|
-
"summary": "Path of the committed schema history file of the table's database, relative to the working directory
|
|
12680
|
+
"summary": "Path of the committed schema history file of the table's database, relative to the working directory;"
|
|
12515
12681
|
},
|
|
12516
12682
|
"immutable": true,
|
|
12517
12683
|
"locationInModule": {
|
|
12518
12684
|
"filename": "lib/iceberg/iceberg-table.ts",
|
|
12519
|
-
"line":
|
|
12685
|
+
"line": 240
|
|
12520
12686
|
},
|
|
12521
12687
|
"name": "schemaHistoryFile",
|
|
12522
12688
|
"optional": true,
|
|
@@ -12534,7 +12700,7 @@
|
|
|
12534
12700
|
"immutable": true,
|
|
12535
12701
|
"locationInModule": {
|
|
12536
12702
|
"filename": "lib/iceberg/iceberg-table.ts",
|
|
12537
|
-
"line":
|
|
12703
|
+
"line": 188
|
|
12538
12704
|
},
|
|
12539
12705
|
"name": "sortOrder",
|
|
12540
12706
|
"optional": true,
|
|
@@ -12557,7 +12723,7 @@
|
|
|
12557
12723
|
"immutable": true,
|
|
12558
12724
|
"locationInModule": {
|
|
12559
12725
|
"filename": "lib/iceberg/iceberg-table.ts",
|
|
12560
|
-
"line":
|
|
12726
|
+
"line": 214
|
|
12561
12727
|
},
|
|
12562
12728
|
"name": "tableProperties",
|
|
12563
12729
|
"optional": true,
|
|
@@ -12584,7 +12750,7 @@
|
|
|
12584
12750
|
"kind": "interface",
|
|
12585
12751
|
"locationInModule": {
|
|
12586
12752
|
"filename": "lib/iceberg/iceberg-schema-history.ts",
|
|
12587
|
-
"line":
|
|
12753
|
+
"line": 81
|
|
12588
12754
|
},
|
|
12589
12755
|
"name": "IcebergTableSchema",
|
|
12590
12756
|
"properties": [
|
|
@@ -12597,7 +12763,7 @@
|
|
|
12597
12763
|
"immutable": true,
|
|
12598
12764
|
"locationInModule": {
|
|
12599
12765
|
"filename": "lib/iceberg/iceberg-schema-history.ts",
|
|
12600
|
-
"line":
|
|
12766
|
+
"line": 83
|
|
12601
12767
|
},
|
|
12602
12768
|
"name": "columns",
|
|
12603
12769
|
"type": {
|
|
@@ -12618,7 +12784,7 @@
|
|
|
12618
12784
|
"immutable": true,
|
|
12619
12785
|
"locationInModule": {
|
|
12620
12786
|
"filename": "lib/iceberg/iceberg-schema-history.ts",
|
|
12621
|
-
"line":
|
|
12787
|
+
"line": 86
|
|
12622
12788
|
},
|
|
12623
12789
|
"name": "partitionSpec",
|
|
12624
12790
|
"optional": true,
|
|
@@ -13920,6 +14086,6 @@
|
|
|
13920
14086
|
"symbolId": "lib/iceberg/iceberg-type:IcebergTypeOptions"
|
|
13921
14087
|
}
|
|
13922
14088
|
},
|
|
13923
|
-
"version": "0.
|
|
13924
|
-
"fingerprint": "/
|
|
14089
|
+
"version": "0.18.0",
|
|
14090
|
+
"fingerprint": "OWf1rZSmSYIKKStrcsHF/tcYlEnyKUhwpxw+fQNY9QU="
|
|
13925
14091
|
}
|