Skip to content

SQL: Expand virtual tables reference, add SHOW/DESCRIBE for new objects #590

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
kbatuigas wants to merge 3 commits into
base: rp-sql
Choose a base branch
from
Open

SQL: Expand virtual tables reference, add SHOW/DESCRIBE for new objects #590

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
b920e39
Expand virtual tables reference, add SHOW/DESCRIBE for new objects
kbatuigas May 19, 2026
ef2dc27
Title case
kbatuigas May 19, 2026
32b19b4
Review pass
kbatuigas May 19, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions modules/ROOT/nav.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -551,6 +551,7 @@
**** xref:reference:sql/sql-statements/copy-to.adoc[]
**** xref:reference:sql/sql-statements/describe.adoc[]
**** xref:reference:sql/sql-statements/set-show.adoc[]
**** xref:reference:sql/sql-statements/show-catalogs.adoc[]
**** xref:reference:sql/sql-statements/show-tables.adoc[]
**** xref:reference:sql/sql-statements/show-execs.adoc[]
**** xref:reference:sql/sql-statements/show-nodes.adoc[]
Expand Down Expand Up @@ -733,6 +734,7 @@
*** xref:reference:sql/comment-support.adoc[]
*** xref:reference:sql/transactions.adoc[]
*** xref:reference:sql/system-virtual-tables.adoc[]
*** xref:reference:sql/information-schema.adoc[Information Schema]
*** xref:reference:sql/system-catalogs/index.adoc[System Catalogs]
**** xref:reference:sql/system-catalogs/catalogs/pg_attrdef.adoc[]
**** xref:reference:sql/system-catalogs/catalogs/pg_attribute.adoc[]
Expand Down
42 changes: 42 additions & 0 deletions modules/reference/pages/sql/information-schema.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,42 @@
= Information Schema
:description: Information schema views in Redpanda SQL expose database object metadata and grants through SQL-standard views.
:page-topic-type: reference

The `information_schema` namespace provides SQL-standard views over database object metadata. Redpanda SQL implements the standard views needed for tool compatibility, plus extension views for Redpanda-specific concepts that don't fit the standard shape.
Copy link
Copy Markdown

@Greketrotny Greketrotny May 21, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we should write a bit about why it is present and how it works.

Admin or owner can grant other users access to table(s) in a redpanda/iceberg catalog. Grants follow a simple pattern matching: a table name with namespace names and an optional * at the end, like ns1.ns2.my_table or ns1.public_tables*. Revoking a grant is to find the granted entry string in the database and removing it. When a user revokes ns1.absent_grant, it cannot be found in the grant list, and an error is reported. If the user doesn't remember what grants are added, they can be listed by selecting from the role_external_relation_grants table.

Not sure whether the grant/revoke mechanism should be documented here in particular, but I can imagine someone desperately trying to revoke a grant and being constantly hit by this error.


== Available views

[cols="<40%,<60%",options="header"]
|===
|View |Description

|`information_schema.role_external_relation_grants`
|Per-relation EXTERNAL SOURCE grants. Redpanda SQL extension that captures grants whose stored relation pattern is anything other than `\*` (catalog-level grants surface in `information_schema.role_table_grants` instead).
|===

== information_schema.role_external_relation_grants

Per-relation EXTERNAL SOURCE grants. Rows whose stored relation pattern is anything other than `\*`. Catalog-level EXTERNAL SOURCE grants (stored pattern `\*`) surface in `information_schema.role_table_grants`, like foreign-table grants in PostgreSQL.

Visibility mirrors `information_schema.role_table_grants`. A regular role sees rows where it is the grantee. A superuser sees grants for every non-superuser.

[cols="<30%,<15%,<10%,<45%",options="header"]
|===
|Column |Type |Nullable |Description

|`grantor` |`text` |No |Role that granted the privilege.
|`grantee` |`text` |No |Role that holds the privilege.
|`database_name` |`text` |No |Database the grant applies to.
|`schema_name` |`text` |No |Schema the grant applies to.
|`source_name` |`text` |No |External source (catalog or storage) the grant applies to.
|`relation_pattern` |`text` |No |Relation-name pattern the grant matches. Wildcards (`\*`) are allowed in the pattern.
|`privilege_type` |`text` |No |Privilege granted, such as `SELECT`.
|`is_grantable` |`text` |No |`YES` if the grantee can grant this privilege to other roles; `NO` otherwise.
|===

[source,sql]
----
SELECT grantee, source_name, relation_pattern, privilege_type
FROM information_schema.role_external_relation_grants
WHERE grantee = 'analyst';
----
48 changes: 44 additions & 4 deletions modules/reference/pages/sql/sql-statements/alter-redpanda-catalog.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,27 +1,67 @@
= ALTER REDPANDA CATALOG
:description: The ALTER REDPANDA CATALOG statement modifies connection properties of an existing Redpanda catalog.
:description: The ALTER REDPANDA CATALOG statement modifies connection properties of an existing Redpanda catalog, including the link to an Iceberg catalog.
:page-topic-type: reference

The `ALTER REDPANDA CATALOG` statement modifies connection properties of an existing Redpanda catalog.
The `ALTER REDPANDA CATALOG` statement modifies connection properties of an existing Redpanda catalog. You can also use it to link the Redpanda catalog to an Iceberg catalog (or detach an existing link) so that queries against the Redpanda catalog return both live records and Iceberg-translated history.

== Syntax

[source,sql]
----
ALTER REDPANDA CATALOG [IF EXISTS] catalog_name
WITH (option = 'value' [, ...]);

ALTER REDPANDA CATALOG [IF EXISTS] catalog_name
USING CATALOG [schema.]iceberg_catalog_name
[WITH (option = 'value' [, ...])];

ALTER REDPANDA CATALOG [IF EXISTS] catalog_name
USING CATALOG NULL
[WITH (option = 'value' [, ...])];
----

* `catalog_name`: Name of the catalog to modify.
* `catalog_name`: Name of the Redpanda catalog to modify.
* `IF EXISTS`: Optional. Prevents an error if the catalog does not exist.
* `option = 'value'`: One or more connection options to update. See xref:reference:sql/sql-statements/create-redpanda-catalog.adoc[CREATE REDPANDA CATALOG] for the full list of options.
* `USING CATALOG iceberg_catalog_name`: Links the Redpanda catalog to an existing Iceberg catalog. The Iceberg catalog must already exist. You can qualify the Iceberg catalog name with a schema prefix.
* `USING CATALOG NULL`: Detaches the Redpanda catalog from any linked Iceberg catalog.

== Examples

Update the broker address for an existing catalog:
=== Update broker address

[source,sql]
----
ALTER REDPANDA CATALOG production_redpanda
WITH (initial_brokers = 'new-broker:9092');
----

=== Link to an Iceberg catalog

To link a Redpanda catalog to an existing Iceberg catalog so that queries against the Redpanda catalog return both live records and Iceberg-translated history:

[source,sql]
----
ALTER REDPANDA CATALOG production_redpanda
USING CATALOG lakehouse_catalog;
----

=== Retarget the linked Iceberg catalog

To change which Iceberg catalog a Redpanda catalog is linked to, run `ALTER REDPANDA CATALOG ... USING CATALOG <new-iceberg-cat>`:

[source,sql]
----
ALTER REDPANDA CATALOG production_redpanda
USING CATALOG new_lakehouse_catalog;
----

=== Detach from an Iceberg catalog

To remove an existing link to an Iceberg catalog so that queries against the Redpanda catalog return only live records:

[source,sql]
----
ALTER REDPANDA CATALOG production_redpanda
USING CATALOG NULL;
----
15 changes: 14 additions & 1 deletion modules/reference/pages/sql/sql-statements/describe.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,11 +12,13 @@ DESCRIBE DATABASE;
DESCRIBE TABLE table_name;
DESCRIBE TABLE catalog_name=>table_name;
DESCRIBE REDPANDA CATALOG catalog_name;
DESCRIBE ICEBERG CATALOG catalog_name;
----

* `table_name`: Name of the table to describe.
* `catalog_name=>table_name`: Describes a table that is mapped to a Redpanda topic through a catalog.
* `catalog_name`: Name of a Redpanda catalog. Lists the tables and topic mappings in that catalog.
* `catalog_name` (after `REDPANDA CATALOG`): Name of a Redpanda catalog. Lists the tables and topic mappings in that catalog.
* `catalog_name` (after `ICEBERG CATALOG`): Name of an Iceberg catalog. Lists the catalog's connection details, including its REST endpoint and warehouse.

[NOTE]
====
Expand Down Expand Up @@ -126,3 +128,14 @@ The query returns:
| user_events | user-events |
+----------------+--------------+
----

=== Describe an Iceberg catalog

To list connection details for an Iceberg catalog, run:

[source,sql]
----
DESCRIBE ICEBERG CATALOG lakehouse_catalog;
----

The query returns the catalog's REST endpoint, warehouse, and authentication type.
51 changes: 51 additions & 0 deletions modules/reference/pages/sql/sql-statements/show-catalogs.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
= SHOW CATALOGS
:description: The SHOW CATALOGS statement lists catalogs in the cluster. Variants list only Redpanda catalogs or only Iceberg catalogs.
:page-topic-type: reference

The `SHOW CATALOGS` statement lists catalogs in the cluster. Variants filter by catalog type: Redpanda catalogs or Iceberg catalogs.

[NOTE]
====
`SHOW CATALOGS` and its variants only display catalogs in schemas where the user has the `USAGE` grant. Catalogs created in schemas where the caller lacks `USAGE` are not returned.
====

== Syntax

[source,sql]
----
SHOW CATALOGS;
SHOW REDPANDA CATALOGS;
SHOW KAFKA CATALOGS;
SHOW ICEBERG CATALOGS;
----

`SHOW KAFKA CATALOGS` is a synonym for `SHOW REDPANDA CATALOGS`.

== Examples

=== List all catalogs

To list all catalogs (both Redpanda and Iceberg) visible to the caller:

[source,sql]
----
SHOW CATALOGS;
----

For SQL-queryable access to the same information (with `WHERE`, `ORDER BY`, and `LIMIT` support), see xref:reference:sql/system-virtual-tables.adoc#system-catalogs[`system.catalogs`].

=== List only Redpanda catalogs

[source,sql]
----
SHOW REDPANDA CATALOGS;
----

=== List only Iceberg catalogs

[source,sql]
----
SHOW ICEBERG CATALOGS;
----

For each Iceberg catalog's REST endpoint, warehouse, and authentication type, see xref:reference:sql/system-virtual-tables.adoc#system-iceberg-catalogs[`system.iceberg_catalogs`] or xref:reference:sql/sql-statements/describe.adoc[`DESCRIBE ICEBERG CATALOG`].
57 changes: 51 additions & 6 deletions modules/reference/pages/sql/sql-statements/show-tables.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
= SHOW TABLES
:description: The SHOW TABLES statement retrieves information about existing tables.
:description: The SHOW TABLES statement retrieves information about existing tables, including tables mapped from Redpanda topics and Iceberg tables registered in the local catalog.
:page-topic-type: reference

The `SHOW TABLES` statement retrieves information about existing tables.
The `SHOW TABLES` statement retrieves information about existing tables in the current schema. Variants filter by the table's source: Redpanda topics or Iceberg.

[NOTE]
====
`SHOW TABLES` only displays tables in schemas where the user has the `USAGE` grant.
`SHOW TABLES` and its variants only display tables in schemas where the user has the `USAGE` grant.
====

== Syntax
Expand All @@ -15,9 +15,24 @@ The `SHOW TABLES` statement retrieves information about existing tables.
----
SHOW TABLES;
SHOW TABLES FROM catalog_name;
Copy link
Copy Markdown

@Greketrotny Greketrotny May 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The simple SHOW TABLES statement will currently return an error saying they are disabled, as we, for now, ship Oxla forbidding users to create and use normal, non kafka/iceberg tables.


SHOW REDPANDA TABLES;
SHOW REDPANDA TABLES catalog_name;
SHOW REDPANDA TABLES schema.catalog_name;

SHOW KAFKA TABLES;
SHOW KAFKA TABLES catalog_name;
SHOW KAFKA TABLES schema.catalog_name;

SHOW ICEBERG TABLES;
SHOW ICEBERG TABLES catalog_name;
SHOW ICEBERG TABLES schema.catalog_name;
----

* `catalog_name`: Optional. The name of a Redpanda catalog. When specified, lists tables mapped to Redpanda topics through that catalog.
* `catalog_name`: Optional. Filter by a specific Redpanda or Iceberg catalog.
* `schema.catalog_name`: Optional. Filter by both schema and catalog. Useful when catalogs in different schemas share a name.

`SHOW KAFKA TABLES` is a synonym for `SHOW REDPANDA TABLES`.

== Examples

Expand All @@ -42,11 +57,41 @@ SHOW TABLES;
+------------+
----

=== List tables from a catalog
=== List tables from a Redpanda catalog

To list tables mapped through a specific Redpanda catalog:

[source,sql]
----
SHOW TABLES FROM default_redpanda_catalog;
SHOW REDPANDA TABLES default_redpanda_catalog;
----

To list all Redpanda-catalog tables across all connections:

[source,sql]
----
SHOW REDPANDA TABLES;
----

=== List Iceberg tables

To list all Iceberg tables registered in the local catalog:

[source,sql]
----
SHOW ICEBERG TABLES;
----

To list Iceberg tables in a specific catalog:

[source,sql]
----
SHOW ICEBERG TABLES lakehouse_catalog;
----

To list Iceberg tables in a specific schema and catalog (here, schema `analytics`, catalog `lakehouse_catalog`):

[source,sql]
----
SHOW ICEBERG TABLES analytics.lakehouse_catalog;
----
Loading