SQL: Expand virtual tables reference, add SHOW/DESCRIBE for new objects#590
SQL: Expand virtual tables reference, add SHOW/DESCRIBE for new objects#590kbatuigas wants to merge 3 commits into
Conversation
|
Important Review skippedAuto reviews are disabled on base/target branches other than the default branch. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
✅ Deploy Preview for rp-cloud ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
| @@ -15,9 +15,24 @@ The `SHOW TABLES` statement retrieves information about existing tables. | |||
| ---- | |||
| SHOW TABLES; | |||
| SHOW TABLES FROM catalog_name; | |||
There was a problem hiding this comment.
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.
| :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. |
There was a problem hiding this comment.
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.
| |Iceberg tables registered in the local catalog. | ||
|
|
||
| |`system.kafka_connections` | ||
| |None |
There was a problem hiding this comment.
| |None | |
| |SHOW REDPANDA/KAFKA CATALOGS |
| |Redpanda catalog connections, including any linked Iceberg catalog. | ||
|
|
||
| |`system.kafka_sources` | ||
| |None |
There was a problem hiding this comment.
| |None | |
| |SHOW REDPANDA/KAFKA TABLES |
2 participants
Description
This pull request significantly expands and clarifies the Redpanda SQL documentation around catalogs, Iceberg integration, and system metadata access. The updates introduce new SQL statements for listing and describing catalogs, provide detailed documentation for the
information_schemaand system virtual tables, and improve clarity around privileges and filtering. The most important changes are grouped below:New SQL Statements and Catalog Management:
SHOW CATALOGS,SHOW REDPANDA CATALOGS,SHOW KAFKA CATALOGS, andSHOW ICEBERG CATALOGSstatements, including syntax, filtering behavior, and privilege requirements. (modules/reference/pages/sql/sql-statements/show-catalogs.adoc,modules/ROOT/nav.adoc) [1] [2]ALTER REDPANDA CATALOGto cover linking and unlinking with Iceberg catalogs, including new syntax and detailed examples. (modules/reference/pages/sql/sql-statements/alter-redpanda-catalog.adoc)DESCRIBEstatement documentation to supportDESCRIBE ICEBERG CATALOG, clarifying output and usage. (modules/reference/pages/sql/sql-statements/describe.adoc) [1] [2]Tables and Metadata Visibility:
SHOW TABLESdocumentation to distinguish between Redpanda and Iceberg tables, introduce new variants (SHOW REDPANDA TABLES,SHOW ICEBERG TABLES), and explain filtering by catalog and schema. (modules/reference/pages/sql/sql-statements/show-tables.adoc) [1] [2] [3]information_schemanamespace, including therole_external_relation_grantsview and its columns, visibility rules, and usage examples. (modules/reference/pages/sql/information-schema.adoc,modules/ROOT/nav.adoc) [1] [2]System Virtual Tables Enhancements:
modules/reference/pages/sql/system-virtual-tables.adoc)These changes provide users with clearer guidance and more powerful tools for managing and querying Redpanda and Iceberg catalogs, as well as understanding metadata and permissions across the system.
Resolves https://github.com/redpanda-data/documentation-private/issues/
Review deadline: 21 May
Page previews
Checks