From c839e18711feb0362bda3cb1eb0b0ca01806829e Mon Sep 17 00:00:00 2001 From: Kat Batuigas Date: Wed, 10 Jun 2026 15:19:05 -0700 Subject: [PATCH 1/2] Add new namespaces options --- .../create-iceberg-catalog.adoc | 55 +++++++++++++++++++ .../pages/sql/sql-statements/describe.adoc | 2 +- 2 files changed, 56 insertions(+), 1 deletion(-) diff --git a/modules/reference/pages/sql/sql-statements/create-iceberg-catalog.adoc b/modules/reference/pages/sql/sql-statements/create-iceberg-catalog.adoc index f36bb5a2f..6e3eadbb9 100644 --- a/modules/reference/pages/sql/sql-statements/create-iceberg-catalog.adoc +++ b/modules/reference/pages/sql/sql-statements/create-iceberg-catalog.adoc @@ -110,6 +110,27 @@ NOTE: Catalogs are created in the current schema (`public` by default). To creat |STRING |No |Path to a certificate revocation list (CRL) file. + +|`flat_namespaces` +|STRING +|No +a|`'true'` or `'false'`. Declares whether the backing catalog is flat (that is, it does not support nested or multi-level namespaces). + +* When `'true'`, Redpanda SQL skips recursive child-namespace calls for any non-root namespace. +* If not set, Redpanda SQL automatically sets this to `true` for AWS Glue and S3 Tables backends, and `false` for all others. Set it explicitly only if the auto-derived value does not match your backend's actual behavior. + +|`allowed_namespaces` +|STRING +|No +a|Comma-separated list of dotted namespace paths (for example, `'analytics, logs.audit'`). Scopes catalog discovery to the listed namespaces, skipping the root-level namespace walk. SELECT and REFRESH are gated on the same list; tables outside it return a "namespace not allowed" error. When unset, Redpanda SQL discovers the entire catalog tree. + +Validation rules: + +* Surrounding whitespace is trimmed. +* Dots denote namespace levels (`logs.audit` = namespace `audit` under `logs`). +* Empty entries (trailing comma) are rejected at DDL time. +* Overlapping entries (where one entry is a prefix of another) are rejected at DDL time. +* On flat backends (`flat_namespaces = 'true'`), all entries must be single-segment. |=== == Examples @@ -177,6 +198,40 @@ CREATE ICEBERG CATALOG lakehouse_catalog STORAGE iceberg_storage To use the AWS default credential chain (for example, an EC2 instance-profile role), omit `aws_access_key_id` and `aws_secret_access_key`. They must be set together or omitted together. +=== Create an Iceberg catalog for AWS Glue or S3 Tables + +AWS Glue and S3 Tables are flat-by-specification backends, meaning they do not support nested namespaces. Use `allowed_namespaces` to scope discovery to specific databases and avoid requiring the `glue:GetDatabases` IAM permission. The `flat_namespaces` option is auto-derived as `true` when `auth_type = 'aws_sigv4'` and the service is Glue or S3 Tables. + +[source,sql] +---- +CREATE ICEBERG CATALOG glue_cat STORAGE iceberg_storage + WITH ( + uri = 'https://glue.us-east-1.amazonaws.com/iceberg', + warehouse = 's3://my-warehouse/', + auth_type = 'aws_sigv4', + aws_region = 'us-east-1', + allowed_namespaces = 'analytics, sales' + -- flat_namespaces is auto-derived as true for Glue/S3 Tables + ); +---- + +=== Create an Iceberg catalog scoped to specific namespaces (nested backend) + +For backends that support nested namespaces (such as Polaris), use multi-segment dotted paths in `allowed_namespaces`. + +[source,sql] +---- +CREATE ICEBERG CATALOG polaris_cat STORAGE iceberg_storage + WITH ( + uri = 'https://polaris.example.com/api/catalog', + warehouse = 'my_warehouse', + auth_type = 'oauth2', + oauth2_client_id = '', + oauth2_client_secret = '', + allowed_namespaces = 'analytics, logs.audit, raw.ingestion.kafka' + ); +---- + === Create an Iceberg catalog with custom TLS settings [source,sql] diff --git a/modules/reference/pages/sql/sql-statements/describe.adoc b/modules/reference/pages/sql/sql-statements/describe.adoc index 247359f34..8fb9b8468 100644 --- a/modules/reference/pages/sql/sql-statements/describe.adoc +++ b/modules/reference/pages/sql/sql-statements/describe.adoc @@ -138,4 +138,4 @@ To list connection details for an Iceberg catalog, run: DESCRIBE ICEBERG CATALOG lakehouse_catalog; ---- -The query returns the catalog's REST endpoint, warehouse, and authentication type. +The query returns the catalog's REST endpoint, warehouse, and authentication type. If `flat_namespaces` or `allowed_namespaces` were set, those values are also shown. From 3e54cbae6453c20123d13c48aedfdcfbcc28127d Mon Sep 17 00:00:00 2001 From: Kat Batuigas Date: Mon, 15 Jun 2026 10:23:10 -0700 Subject: [PATCH 2/2] Address PR review: tighten flat_namespaces auto-derivation wording Clarify that flat_namespaces is auto-derived based on auth_type and aws_service_name (not a vague "backend" check), fix tense in describe.adoc, and remove trailing whitespace. Co-Authored-By: Claude Opus 4.6 --- .../pages/sql/sql-statements/create-iceberg-catalog.adoc | 6 +++--- modules/reference/pages/sql/sql-statements/describe.adoc | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/modules/reference/pages/sql/sql-statements/create-iceberg-catalog.adoc b/modules/reference/pages/sql/sql-statements/create-iceberg-catalog.adoc index 6e3eadbb9..749fd12ae 100644 --- a/modules/reference/pages/sql/sql-statements/create-iceberg-catalog.adoc +++ b/modules/reference/pages/sql/sql-statements/create-iceberg-catalog.adoc @@ -116,8 +116,8 @@ NOTE: Catalogs are created in the current schema (`public` by default). To creat |No a|`'true'` or `'false'`. Declares whether the backing catalog is flat (that is, it does not support nested or multi-level namespaces). -* When `'true'`, Redpanda SQL skips recursive child-namespace calls for any non-root namespace. -* If not set, Redpanda SQL automatically sets this to `true` for AWS Glue and S3 Tables backends, and `false` for all others. Set it explicitly only if the auto-derived value does not match your backend's actual behavior. +* When `'true'`, Redpanda SQL skips recursive child-namespace calls for any non-root namespace. +* If not set, Redpanda SQL auto-derives this as `true` when `auth_type = 'aws_sigv4'` and `aws_service_name` is `glue` (default) or `s3tables`, and `false` for all other auth types. Set it explicitly only if the auto-derived value does not match your backend's actual behavior. |`allowed_namespaces` |STRING @@ -200,7 +200,7 @@ To use the AWS default credential chain (for example, an EC2 instance-profile ro === Create an Iceberg catalog for AWS Glue or S3 Tables -AWS Glue and S3 Tables are flat-by-specification backends, meaning they do not support nested namespaces. Use `allowed_namespaces` to scope discovery to specific databases and avoid requiring the `glue:GetDatabases` IAM permission. The `flat_namespaces` option is auto-derived as `true` when `auth_type = 'aws_sigv4'` and the service is Glue or S3 Tables. +AWS Glue and S3 Tables are flat-by-specification backends, meaning they do not support nested namespaces. Use `allowed_namespaces` to scope discovery to specific databases and avoid requiring the `glue:GetDatabases` IAM permission. The `flat_namespaces` option is auto-derived as `true` when `auth_type = 'aws_sigv4'` and `aws_service_name` is `glue` (default) or `s3tables`. [source,sql] ---- diff --git a/modules/reference/pages/sql/sql-statements/describe.adoc b/modules/reference/pages/sql/sql-statements/describe.adoc index 8fb9b8468..cb746747a 100644 --- a/modules/reference/pages/sql/sql-statements/describe.adoc +++ b/modules/reference/pages/sql/sql-statements/describe.adoc @@ -138,4 +138,4 @@ To list connection details for an Iceberg catalog, run: DESCRIBE ICEBERG CATALOG lakehouse_catalog; ---- -The query returns the catalog's REST endpoint, warehouse, and authentication type. If `flat_namespaces` or `allowed_namespaces` were set, those values are also shown. +The query returns the catalog's REST endpoint, warehouse, and authentication type. If `flat_namespaces` or `allowed_namespaces` are set on the catalog, those values are also shown.