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

[kbatuigas]

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_schema and system virtual tables, and improve clarity around privileges and filtering. The most important changes are grouped below:

New SQL Statements and Catalog Management:

• Added documentation for the SHOW CATALOGS, SHOW REDPANDA CATALOGS, SHOW KAFKA CATALOGS, and SHOW ICEBERG CATALOGS statements, including syntax, filtering behavior, and privilege requirements. (modules/reference/pages/sql/sql-statements/show-catalogs.adoc, modules/ROOT/nav.adoc) [1] [2]
• Expanded ALTER REDPANDA CATALOG to cover linking and unlinking with Iceberg catalogs, including new syntax and detailed examples. (modules/reference/pages/sql/sql-statements/alter-redpanda-catalog.adoc)
• Enhanced DESCRIBE statement documentation to support DESCRIBE ICEBERG CATALOG, clarifying output and usage. (modules/reference/pages/sql/sql-statements/describe.adoc) [1] [2]

Tables and Metadata Visibility:

• Updated SHOW TABLES documentation 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]
• Added a new page documenting the information_schema namespace, including the role_external_relation_grants view 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:

• Greatly expanded documentation for system virtual tables, including new tables for catalogs, Iceberg catalogs, Iceberg tables, Redpanda connections, and topic mappings. Each table now has a detailed schema, description, and example queries. Privilege filtering is clarified for each table. (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

• Information Schema (new)
• SHOW CATALOGS (new)
• ALTER REDPANDA CATALOG (updated)
• DESCRIBE (updated)
• SHOW TABLES (updated)
• System Virtual Tables (updated)

Checks

• New feature
• Content gap
• Support Follow-up
• Small fix (typos, links, copyedits, etc)

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 2eeec36b-d1ee-40bd-95b4-99087fd08569

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch DOC-2134-document-feature-add-system-iceberg_tables-virtua

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[netlify]

✅ Deploy Preview for rp-cloud ready!

Name	Link
🔨 Latest commit	ba9f587
🔍 Latest deploy log	https://app.netlify.com/projects/rp-cloud/deploys/6a110ca09634ac00084a613c
😎 Deploy Preview	https://deploy-preview-590--rp-cloud.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[micheleRP]

docs-team-standards review

Critical issues

1. [information-schema.adoc:23, 48, 49, 50] Broken xrefs to pages that don't exist yet. Confirmed by searching this repo and the rp-sql base branch, and by inspecting the Netlify preview, which renders these as broken hash anchors (#reference:sql/sql-statements/revoke.adoc, etc.) rather than resolved links. Understood that these will resolve once the access-control pages land in separate PRs — flagging so they can be tracked together:

   • xref:reference:sql/sql-statements/revoke.adoc[revoke] (line 23, body)
   • xref:reference:sql/sql-statements/grant.adoc[GRANT] (line 48)
   • xref:reference:sql/sql-statements/revoke.adoc[REVOKE] (line 49)
   • xref:sql:manage/manage-access.adoc[Manage access to Redpanda SQL] (line 50)

2. [show-catalogs.adoc:51] Broken anchor #system-iceberg-catalogs. The Netlify preview shows the rendered anchor on the target page is id=\"system-iceberg_catalogs\" (underscore between iceberg and catalogs, because the section heading is == system.iceberg_catalogs). Antora replaces the . with - but preserves the _, so the link silently lands at the top of the page instead of the section.

   • Fix: Change to xref:reference:sql/system-virtual-tables.adoc#system-iceberg_catalogs[…]. The companion #system-catalogs (line 35) is fine because that section has no underscore.

Suggestions

1. "Suggested reading" heading. Consider renaming to Related topics. The team's reference-page template specifies See also, but "Related topics" reads better than "Suggested reading" for a reference page. Repo-wide there are 11 "Suggested reading" sections vs. 26 "Next steps" and 0 "Related topics", so this would set a new convention — fine if intentional, but worth picking one team-wide name.

2. [information-schema.adoc intro] Overstates scope. The intro says the namespace exposes "catalogs, tables, schemas, columns, and privilege grants," but the "Available views" table lists only one view (role_external_relation_grants). Either narrow the intro to match what's actually documented (this view is a Redpanda extension for per-relation EXTERNAL SOURCE grants) or add the other standard views.

3. [information-schema.adoc] "EXTERNAL SOURCE grants" and "stored relation pattern" need context. The page assumes the reader already knows what an EXTERNAL SOURCE is and what a "stored relation pattern" looks like. Greketrotny's first review comment provided the explanation (admin/owner grants follow pattern matching against ns1.ns2.my_table or ns1.public_tables*; REVOKE requires an exact match against an existing stored grant); only a partial form of this made it into the page. Consider a short "How EXTERNAL SOURCE grants work" paragraph above the column table.

4. [alter-redpanda-catalog.adoc] "Iceberg-translated history" used three times but never defined. Lines 5, 41, and the description attribute all reference it. A reader who hasn't read the Iceberg integration page won't know what this means. Either define it briefly on first use ("history of records translated into the linked Iceberg catalog") or link to an explainer.

5. [system-virtual-tables.adoc] system.iceberg_tables description: "schema has been refreshed into the local catalog". "Refreshed" is undefined — is this automatic, manual via a command, on-query? The same paragraph mentions stale entries from dropping at the REST catalog but doesn't say what triggers the refresh in the first place.

6. [system-virtual-tables.adoc] system.kafka_connections.options column lacks format. "Connection options, including broker addresses, Schema Registry endpoint, and librdkafka configuration" — what's the value format? JSON? KEY=value pairs? One value or a list?

7. [system-virtual-tables.adoc] Inconsistent depth across tables. The five new tables get full column schemas plus example queries; the three pre-existing tables (system.nodes, system.queries, system.execs) still only have an example query and no column schema. Worth either adding columns for those or noting up front that schemas are only documented for the new tables.

8. [system-virtual-tables.adoc:40] system.queries row uses inline code, not an xref like its neighbors. Other rows xref to a SHOW … page; this one is just \`SHOW QUERIES\` because no show-queries.adoc exists. Either add the page or replace the others' xrefs with plain code for consistency.

9. [show-tables.adoc] Plain SHOW TABLES removed from syntax but not from prose. Greketrotny's first comment ("SHOW TABLES currently errors") was addressed by removing the bare-form examples, but the intro still says "tables in the current schema" and the NOTE still says SHOW TABLES displays tables. The syntax block now opens with SHOW TABLES FROM catalog_name; — a reader will wonder where the unqualified form went. Consider explicitly noting that the bare SHOW TABLES is currently disabled in Redpanda SQL, so you must use one of the typed/qualified variants.

10. [system-virtual-tables.adoc] Schema vs. namespace terminology. The NOTE talks about grants "on the database, namespace, and metadata," but column descriptions throughout say "Schema containing the catalog" for namespace_name. Pick one and use it consistently, or note that namespace and schema are equivalent here.

[micheleRP]

docs-team-standards final review

Critical (must fix)

Broken xrefs to pages that don't exist on this branch or on rp-sql:

• xref:reference:sql/sql-statements/grant.adoc[GRANT] and xref:reference:sql/sql-statements/revoke.adoc[REVOKE] — used in information-schema.adoc (lines 47, 51, 76, 77). Neither grant.adoc nor revoke.adoc exists in modules/reference/pages/sql/sql-statements/.
• xref:sql:manage/manage-access.adoc[Manage access to Redpanda SQL] — information-schema.adoc lines 47, 78. There is no manage/ subdirectory under modules/sql/pages/ (only query-data/, troubleshoot/, connect-to-sql/, get-started/).
• xref:sql:query-data/query-iceberg-topics.adoc[] — alter-redpanda-catalog.adoc:5, system-virtual-tables.adoc:91. The page exists at modules/manage/pages/iceberg/query-iceberg-topics.adoc, so the correct xref is xref:manage:iceberg/query-iceberg-topics.adoc[].

If the grant/revoke/manage-access pages are coming in a follow-up PR to rp-sql, either land them first or drop the xrefs to plain bold text until they exist. Fix the iceberg-topics xref to the manage: module.

Suggestions

1. show-tables.adoc:5 vs :31 — the intro says the unqualified SHOW TABLES form is not supported, but the parameter list still describes catalog_name as simply "Optional", which is true only for the typed variants. Consider: "Required after SHOW TABLES FROM; optional after SHOW REDPANDA TABLES / SHOW ICEBERG TABLES."

2. information-schema.adoc:9 — the "Available views" lead-in is mostly redundant with the page intro and slightly overstates the match ("semantics match PostgreSQL's implementation" — PostgreSQL itself extends the standard). Consider: "Standard views follow the SQL specification. Redpanda SQL also adds one extension view for per-relation EXTERNAL SOURCE grants."

3. system-virtual-tables.adoc:7 — drop the "(also called schema)" parenthetical; "namespace" and "schema" are already used interchangeably throughout the page.

4. show-queries.adoc:8-10 — the case-insensitive NOTE is generic (every SQL statement is case-insensitive in Redpanda SQL) and isn't present on show-execs.adoc, show-nodes.adoc, etc. Drop it for consistency.

Impact on files not in this PR

• modules/reference/pages/sql/sql-statements/index.adoc — the SQL statements summary table doesn't list the new SHOW CATALOGS or SHOW QUERIES. Add rows so the index stays in sync with nav.
• modules/reference/pages/sql/index.adoc — the SQL Reference landing page should add an entry for the new information-schema.adoc. (system-virtual-tables.adoc is also missing here as a pre-existing gap — optional to address in this PR.)

What's New is not flagged because the PR targets the rp-sql feature branch.

What works well

• Uniformly structured column tables (Column | Type | Nullable | Description) with representative example queries.
• Reciprocal cross-links between SHOW statements and equivalent system.* tables.
• Privilege/visibility behavior consistently called out via NOTE blocks.
• Active voice, second person, no em dashes, sentence case for H2+.
• Recent commits already absorbed SME corrections (namespace→schema, anchor cleanup, suggested reading).

[micheleRP]

@kbatuigas should this intro just include one link to Postgres doc, instead of so many throughout the table?

[micheleRP]

this link isn't working + we don't use "below". Maybe just remove the sentence?

[micheleRP]

Reminder about this link not working

[micheleRP]

reminder about the links, and I left some style suggestions