creating-data-lake-table

Use aws s3tables create-table with the table bucket ARN, namespace, table name, ICEBERG format, and a metadata JSON containing the schema nested under an "iceberg" key. The table bucket and namespace must exist first, created via create-table-bucket and create-namespace.

Register a federated Glue catalog named s3tablescatalog pointing at your table bucket ARN, then pass the catalog in Athena's --query-execution-context as "s3tablescatalog/<bucket>". Do not put the catalog name in the SQL statement itself, and never include a LOCATION clause in the DDL.

The S3 Tables API is the default path for any user. Athena DDL suits users who want SQL or need ALTER TABLE schema evolution later. Glue ETL with Spark DDL fits ETL pipelines and requires Glue 5.1+ with catalog config passed via --conf job arguments.

S3 Tables uses the s3tables:* IAM namespace, not s3:*, so policies granting only s3 permissions fail. The querying principal needs s3tables:GetTable, GetTableData, and GetTableMetadataLocation on the bucket and table ARNs, plus glue:GetCatalog, GetDatabase, and GetTable.

Glue rejects mixed-case names with GENERIC_INTERNAL_ERROR, so all namespace and table names must be lowercase. Namespaces and table names must also avoid hyphens; use underscores instead, while table bucket names may contain hyphens.

Do not use it for importing existing files into tables, which belongs to data ingestion workflows, or for querying or locating existing tables. It also does not cover vector storage, which requires a different storage approach.