diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index 9d539820e..2d6ea940a 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -565,8 +565,10 @@ **** xref:reference:sql/sql-statements/revoke.adoc[] **** xref:reference:sql/sql-statements/select.adoc[] **** xref:reference:sql/sql-statements/set-show.adoc[] +**** xref:reference:sql/sql-statements/show-catalogs.adoc[] **** xref:reference:sql/sql-statements/show-execs.adoc[] **** xref:reference:sql/sql-statements/show-nodes.adoc[] +**** xref:reference:sql/sql-statements/show-queries.adoc[] **** xref:reference:sql/sql-statements/show-tables.adoc[] *** xref:reference:sql/sql-clauses/index.adoc[Clauses] **** xref:reference:sql/sql-clauses/set-operations/index.adoc[Set Operations] @@ -762,6 +764,7 @@ **** xref:reference:sql/system-catalogs/catalogs/pg_type.adoc[] **** xref:reference:sql/system-catalogs/catalogs/pg_user.adoc[] *** xref:reference:sql/comment-support.adoc[] +*** xref:reference:sql/information-schema.adoc[Information Schema] *** xref:reference:sql/schema.adoc[] *** xref:reference:sql/system-virtual-tables.adoc[] *** xref:reference:sql/transactions.adoc[] diff --git a/modules/reference/pages/sql/index.adoc b/modules/reference/pages/sql/index.adoc index 3084b6624..a0a7f7df0 100644 --- a/modules/reference/pages/sql/index.adoc +++ b/modules/reference/pages/sql/index.adoc @@ -7,6 +7,7 @@ This section provides information about the syntax and semantics of SQL queries, * xref:reference:sql/sql-clauses/index.adoc[SQL Clauses]: Learn how to write user-friendly queries and analyze data using different constraints and conditions. * xref:reference:sql/sql-data-types/index.adoc[SQL Data Types]: Learn how to implement supported data types to run your operations, such as text, timestamp, numeric, and many more. * xref:reference:sql/sql-functions/index.adoc[SQL Functions]: See how you can combine statements, data types, and other references into specific functions for particular tasks. +* xref:reference:sql/information-schema.adoc[Information Schema]: Inspect database object metadata and privilege grants through SQL-standard `information_schema` views. * xref:reference:sql/schema.adoc[Schema]: Learn about a logical container that holds database objects and relationships of data in a database. * xref:reference:sql/comment-support.adoc[Comment Support]: Add comments in your queries for better documentation and collaboration. * xref:reference:sql/transactions.adoc[Transactions]: Learn more about managing your transactions. diff --git a/modules/reference/pages/sql/information-schema.adoc b/modules/reference/pages/sql/information-schema.adoc new file mode 100644 index 000000000..4cdc35eeb --- /dev/null +++ b/modules/reference/pages/sql/information-schema.adoc @@ -0,0 +1,78 @@ += 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. Use these views to inspect catalogs, tables, schemas, columns, and privilege grants without querying the underlying PostgreSQL system catalogs directly. + +== Available views + +Standard views follow the SQL specification, with semantics consistent with https://www.postgresql.org/docs/current/information-schema.html[PostgreSQL's `information_schema`^]. Redpanda SQL also adds one extension view for per-relation EXTERNAL SOURCE grants. + +[cols="<40%,<60%",options="header"] +|=== +|View |Description + +|`information_schema.character_sets` +|Character sets available in the current database. + +|`information_schema.columns` +|Columns of tables and views visible to the current role. + +|`information_schema.key_column_usage` +|Columns constrained as keys (primary keys, unique constraints, foreign keys). + +|`information_schema.referential_constraints` +|Foreign-key constraints visible to the current role. + +|`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_table_grants` +|Privileges granted on tables and table-like objects to the current role. + +|`information_schema.role_usage_grants` +|USAGE privileges granted to the current role. + +|`information_schema.table_constraints` +|Table constraints (primary key, unique, foreign key, check) visible to the current role. + +|`information_schema.tables` +|Tables and views visible to the current role. +|=== + +== 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. + +When you `GRANT ... ON EXTERNAL SOURCE catalog_name => 'pattern'`, the pattern is stored verbatim. Redpanda SQL does not normalize or canonicalize it. Patterns are either a fully-qualified relation name like `ns1.ns2.my_table` or a name with a trailing wildcard like `ns1.public_tables*`. See xref:reference:sql/sql-statements/grant.adoc[GRANT] for the full grant syntax and xref:sql:manage/manage-access.adoc[Manage access to Redpanda SQL] for the access model. + +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. + +Use this view to find the exact stored relation pattern when you need to xref:reference:sql/sql-statements/revoke.adoc[revoke] a grant. `REVOKE` requires the pattern argument to match a stored grant exactly. Revoking a pattern that was never granted returns an error, so query this view first to see what's currently registered. + +[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'; +---- + +== Suggested reading + +* xref:reference:sql/sql-statements/grant.adoc[GRANT] +* xref:reference:sql/sql-statements/revoke.adoc[REVOKE] +* xref:sql:manage/manage-access.adoc[Manage access to Redpanda SQL] diff --git a/modules/reference/pages/sql/sql-statements/alter-redpanda-catalog.adoc b/modules/reference/pages/sql/sql-statements/alter-redpanda-catalog.adoc index b69e6674d..051dd1f15 100644 --- a/modules/reference/pages/sql/sql-statements/alter-redpanda-catalog.adoc +++ b/modules/reference/pages/sql/sql-statements/alter-redpanda-catalog.adoc @@ -1,8 +1,8 @@ = 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 (records previously written from the topic into the linked Iceberg catalog). See xref:sql:query-data/query-iceberg-topics.adoc[] for details. == Syntax @@ -10,18 +10,58 @@ The `ALTER REDPANDA CATALOG` statement modifies connection properties of an exis ---- 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; +---- + +=== Relink to a different Iceberg catalog + +To change which Iceberg catalog a Redpanda catalog is linked to, run `ALTER REDPANDA CATALOG ... USING CATALOG `: + +[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; +---- diff --git a/modules/reference/pages/sql/sql-statements/describe.adoc b/modules/reference/pages/sql/sql-statements/describe.adoc index 99dd23df0..247359f34 100644 --- a/modules/reference/pages/sql/sql-statements/describe.adoc +++ b/modules/reference/pages/sql/sql-statements/describe.adoc @@ -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] ==== @@ -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. diff --git a/modules/reference/pages/sql/sql-statements/index.adoc b/modules/reference/pages/sql/sql-statements/index.adoc index e7dd6068d..03cdd28ed 100644 --- a/modules/reference/pages/sql/sql-statements/index.adoc +++ b/modules/reference/pages/sql/sql-statements/index.adoc @@ -23,8 +23,10 @@ The following table summarizes the statements supported by Redpanda SQL: |xref:reference:sql/sql-statements/select.adoc[SELECT] |Retrieves data from a table. |xref:reference:sql/sql-statements/copy-to.adoc[COPY TO] |Exports query results or table data to CSV files. |xref:reference:sql/sql-statements/set-show.adoc[SET/SHOW] |Configures or displays session-level settings such as time zone and search path. +|xref:reference:sql/sql-statements/show-catalogs.adoc[SHOW CATALOGS] |Lists catalogs in the cluster. Variants list only Redpanda catalogs or only Iceberg catalogs. |xref:reference:sql/sql-statements/show-execs.adoc[SHOW EXECS] |Displays currently running execution tasks across the cluster. -|xref:reference:sql/sql-statements/show-tables.adoc[SHOW TABLES] |Lists all tables within the current schema, database, or catalog. |xref:reference:sql/sql-statements/show-nodes.adoc[SHOW NODES] |Displays the current state of nodes in a distributed cluster. +|xref:reference:sql/sql-statements/show-queries.adoc[SHOW QUERIES] |Displays currently running queries on the cluster. +|xref:reference:sql/sql-statements/show-tables.adoc[SHOW TABLES] |Lists tables mapped from Redpanda topics and Iceberg tables registered in the local catalog. |xref:reference:sql/sql-statements/describe.adoc[DESCRIBE] |Shows detailed information about columns in a table, tables within a database, or catalog contents. |=== diff --git a/modules/reference/pages/sql/sql-statements/show-catalogs.adoc b/modules/reference/pages/sql/sql-statements/show-catalogs.adoc new file mode 100644 index 000000000..20ae832f3 --- /dev/null +++ b/modules/reference/pages/sql/sql-statements/show-catalogs.adoc @@ -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. +==== + +== 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`]. diff --git a/modules/reference/pages/sql/sql-statements/show-queries.adoc b/modules/reference/pages/sql/sql-statements/show-queries.adoc new file mode 100644 index 000000000..7cb754cd2 --- /dev/null +++ b/modules/reference/pages/sql/sql-statements/show-queries.adoc @@ -0,0 +1,19 @@ += SHOW QUERIES +:description: The SHOW QUERIES statement displays currently running queries on the cluster. +:page-topic-type: reference + +The `SHOW QUERIES` statement displays currently running queries on the cluster. This statement is only available to the superuser. + +[NOTE] +==== +This statement is not case-sensitive. `show queries`, `Show Queries`, and `SHOW QUERIES` all produce the same result. +==== + +== Examples + +[source,sql] +---- +SHOW QUERIES; +---- + +NOTE: `SHOW QUERIES` is equivalent to `SELECT * FROM system.queries`. You can query the xref:reference:sql/system-virtual-tables.adoc#system-queries[`system.queries`] table directly to filter or sort results using `WHERE` and `ORDER BY` clauses. diff --git a/modules/reference/pages/sql/sql-statements/show-tables.adoc b/modules/reference/pages/sql/sql-statements/show-tables.adoc index fc8b2f598..7456cf025 100644 --- a/modules/reference/pages/sql/sql-statements/show-tables.adoc +++ b/modules/reference/pages/sql/sql-statements/show-tables.adoc @@ -1,52 +1,75 @@ = 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 a catalog. Use one of the typed variants (`SHOW REDPANDA TABLES`, `SHOW ICEBERG TABLES`) or qualify with a catalog name (`SHOW TABLES FROM catalog_name`). The unqualified `SHOW TABLES` form is not supported and returns an error. [NOTE] ==== -`SHOW TABLES` only displays tables in schemas where the user has the `USAGE` grant. +`SHOW TABLES` variants only display tables in schemas where the user has the `USAGE` grant. ==== == Syntax [source,sql] ---- -SHOW TABLES; SHOW TABLES FROM catalog_name; + +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`: Required after `SHOW TABLES FROM`; optional after `SHOW REDPANDA TABLES` and `SHOW ICEBERG TABLES`. 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 -=== List all tables +=== List tables from a Redpanda catalog -To list all available tables in the current schema: +To list tables mapped through a specific Redpanda catalog: [source,sql] ---- -SHOW TABLES; +SHOW REDPANDA TABLES default_redpanda_catalog; ---- +To list all Redpanda-catalog tables across all connections: + [source,sql] ---- -+------------+ -| name | -+------------+ -| lineorder | -| part | -| customer | -| supplier | -+------------+ +SHOW REDPANDA TABLES; ---- -=== List tables from a catalog +=== List Iceberg tables -To list tables mapped through a specific Redpanda catalog: +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 TABLES FROM default_redpanda_catalog; +SHOW ICEBERG TABLES analytics.lakehouse_catalog; ---- diff --git a/modules/reference/pages/sql/system-virtual-tables.adoc b/modules/reference/pages/sql/system-virtual-tables.adoc index 9ee5dee71..933780042 100644 --- a/modules/reference/pages/sql/system-virtual-tables.adoc +++ b/modules/reference/pages/sql/system-virtual-tables.adoc @@ -1,23 +1,43 @@ = System Virtual Tables -:description: System virtual tables in Redpanda SQL expose cluster runtime information and provide SQL-queryable alternatives to SHOW statements. +:description: System virtual tables in Redpanda SQL expose cluster runtime information and external-source metadata, providing SQL-queryable alternatives to SHOW statements. :page-topic-type: reference -System virtual tables in the `system` schema expose cluster runtime information. They provide SQL-queryable alternatives to `SHOW` statements, with support for `WHERE`, `ORDER BY`, and `LIMIT` clauses. +System virtual tables in the `system` schema expose cluster runtime information and external-source metadata. They provide SQL-queryable alternatives to `SHOW` statements, with support for `WHERE`, `ORDER BY`, and `LIMIT` clauses. -NOTE: System virtual tables are only available to the superuser. +NOTE: System virtual tables filter rows by the caller's privileges. Cluster runtime tables (`system.nodes`, `system.queries`, `system.execs`) are visible only to a superuser. Tables that expose catalog and connection metadata filter rows by the caller's grants on the database, namespace (also called schema), and metadata. == Available tables -[cols="<30%,<30%,<40%",options="header"] +[cols="<35%,<30%,<35%",options="header"] |=== |Table |Equivalent statement |Description +|`system.catalogs` +|xref:reference:sql/sql-statements/show-catalogs.adoc[SHOW CATALOGS] +|All catalogs (both Redpanda and Iceberg) visible to the caller. + +|`system.iceberg_catalogs` +|xref:reference:sql/sql-statements/show-catalogs.adoc[SHOW ICEBERG CATALOGS] +|Iceberg catalogs with their REST endpoint, warehouse, and authentication type. + +|`system.iceberg_tables` +|xref:reference:sql/sql-statements/show-tables.adoc[SHOW ICEBERG TABLES] +|Iceberg tables whose schema has been loaded into the local catalog. + +|`system.kafka_connections` +|xref:reference:sql/sql-statements/show-catalogs.adoc[SHOW REDPANDA/KAFKA CATALOGS] +|Redpanda catalog connections, including any linked Iceberg catalog. + +|`system.kafka_sources` +|xref:reference:sql/sql-statements/show-tables.adoc[SHOW REDPANDA/KAFKA TABLES] +|Tables mapped to Redpanda topics through a Redpanda catalog. + |`system.nodes` |xref:reference:sql/sql-statements/show-nodes.adoc[SHOW NODES] |Current state of all nodes in the cluster. |`system.queries` -|SHOW QUERIES +|xref:reference:sql/sql-statements/show-queries.adoc[SHOW QUERIES] |Currently running queries. |`system.execs` @@ -25,25 +45,169 @@ NOTE: System virtual tables are only available to the superuser. |Currently running execution tasks. |=== -== Examples +== system.catalogs + +All catalogs in the cluster (both Redpanda and Iceberg), across databases and schemas visible to the caller. + +[cols="<30%,<15%,<10%,<45%",options="header"] +|=== +|Column |Type |Nullable |Description + +|`name` |`text` |No |Catalog name. +|`namespace_name` |`text` |No |Schema containing the catalog. +|`type` |`text` |No |Catalog type: `REDPANDA` or `ICEBERG`. +|=== + +[source,sql] +---- +SELECT * FROM system.catalogs; +---- + +For per-catalog detail, query `system.iceberg_catalogs` or `system.kafka_connections`. + +== system.iceberg_catalogs + +Iceberg catalog connections, with their REST endpoint and authentication details. + +[cols="<30%,<15%,<10%,<45%",options="header"] +|=== +|Column |Type |Nullable |Description + +|`name` |`text` |No |Iceberg catalog name. +|`uri` |`text` |No |REST catalog endpoint URI. +|`warehouse` |`text` |No |Iceberg warehouse identifier or location. +|`auth_type` |`text` |No |Authentication type for the REST catalog. One of `oauth2`, `basic`, `aws_sigv4`, or empty if the catalog connects without authentication. +|`namespace_name` |`text` |No |Schema containing the catalog. +|`database_name` |`text` |No |Database containing the catalog. +|=== + +[source,sql] +---- +SELECT name, uri, auth_type FROM system.iceberg_catalogs; +---- + +== system.iceberg_tables -=== Query all nodes +Iceberg tables whose schema has been loaded into the local catalog. Schemas are loaded by an explicit `REFRESH` statement or auto-loaded when you `CREATE TABLE` against an Iceberg catalog. See xref:sql:query-data/query-iceberg-topics.adoc[] for details on when to refresh. Each row represents one root Iceberg table. + +[cols="<30%,<15%,<10%,<45%",options="header"] +|=== +|Column |Type |Nullable |Description + +|`database_name` |`text` |No |Database containing the registered table. +|`namespace_name` |`text` |No |Schema containing the registered table. +|`catalog_name` |`text` |No |Iceberg catalog the table belongs to. +|`name` |`text` |No |Qualified Iceberg table path (for example, `ns1.ns2.tbl`). +|`oid` |`int` |No |Object identifier of the table type. Joinable with `pg_type.oid`. +|=== + +[NOTE] +==== +Stale entries: dropping an Iceberg table from the REST catalog leaves its registration in Oxla's catalog until you drop it explicitly. The view continues to list it. This mirrors `system.kafka_sources` behavior. +==== + +[source,sql] +---- +SELECT * FROM system.iceberg_tables WHERE catalog_name = 'lakehouse_catalog'; +---- + +== system.kafka_connections + +Redpanda catalog connections, including any linked Iceberg catalog for queries that span live records and Iceberg-translated history. For details on linking and Iceberg-translated history, see xref:reference:sql/sql-statements/alter-redpanda-catalog.adoc[ALTER REDPANDA CATALOG]. + +[cols="<30%,<15%,<10%,<45%",options="header"] +|=== +|Column |Type |Nullable |Description + +|`database_name` |`text` |No |Database containing the connection. +|`namespace_name` |`text` |No |Schema containing the connection. +|`name` |`text` |No |Catalog (connection) name. +|`options` |`text` |No |Connection options as a comma-separated string of `key: value` pairs. Includes broker addresses, Kafka timeout, Schema Registry endpoint, Schema Registry timeout, and a nested librdkafka configuration list in `[key=value, ...]` form. Pandaproxy options are included when configured. +|`iceberg_catalog` |`text` |Yes |Linked Iceberg catalog as `schema.name`, or NULL if no link is configured. Returns NULL when the caller doesn't have `CONNECT` on the linked catalog's database and `USAGE` on its schema (or an `ANY` grant on the metadata). +|=== + +[source,sql] +---- +SELECT name, iceberg_catalog FROM system.kafka_connections; +---- + +== system.kafka_sources + +Tables mapped to Redpanda topics through a Redpanda catalog. One row per `CREATE TABLE catalog=>name WITH (...)` mapping. + +[cols="<30%,<15%,<10%,<45%",options="header"] +|=== +|Column |Type |Nullable |Description + +|`database_name` |`text` |No |Database containing the source table. +|`namespace_name` |`text` |No |Schema containing the source table. +|`name` |`text` |No |Table name. +|`connection_name` |`text` |No |Redpanda catalog (connection) the table belongs to. +|`topic_name` |`text` |No |Source topic name. +|`subject_name` |`text` |No |Schema Registry subject name. Empty if not configured. +|`lookup_policy` |`text` |No |Schema lookup policy. See xref:reference:sql/sql-statements/create-table.adoc[CREATE TABLE]. +|`error_handling_policy` |`text` |No |Deserialization error-handling policy. See xref:reference:sql/sql-statements/create-table.adoc[CREATE TABLE]. +|`struct_mapping_policy` |`text` |No |Nested-struct mapping policy. See xref:reference:sql/sql-statements/create-table.adoc[CREATE TABLE]. +|`output_schema_full_message_name` |`text` |No |Full Protobuf message name. Empty if not configured. +|=== + +[source,sql] +---- +SELECT name, topic_name, subject_name FROM system.kafka_sources +WHERE connection_name = 'production_redpanda'; +---- + +== system.nodes + +Current state of each node in the cluster. Visible only to a superuser. For the column reference, see xref:reference:sql/sql-statements/show-nodes.adoc[SHOW NODES]. [source,sql] ---- SELECT * FROM system.nodes; ---- -=== Query running queries +== system.queries + +Currently running queries on the cluster. Visible only to a superuser. + +[cols="<30%,<15%,<10%,<45%",options="header"] +|=== +|Column |Type |Nullable |Description + +|`qid` |`text` |No |Query identifier. +|`requester` |`text` |No |Identifier of the node that received the query from the client. +|`scheduler` |`text` |No |Identifier of the node scheduling the query's execution tasks. +|`workers` |`bigint` |No |Number of worker tasks assigned to the query. +|`state` |`text` |No |Current state of the query. +|`created` |`timestamp` |No |Time the query was received. +|`accepted` |`timestamp` |Yes |Time the query was accepted for execution. `NULL` until accepted. +|`scheduled` |`timestamp` |Yes |Time the query's execution tasks were scheduled. `NULL` until scheduled. +|`executed` |`timestamp` |Yes |Time execution started. `NULL` until execution starts. +|`finished` |`timestamp` |Yes |Time execution finished. `NULL` while the query is still running. +|=== [source,sql] ---- -SELECT * FROM system.queries; +SELECT qid, state, created FROM system.queries WHERE state <> 'FINISHED'; ---- -=== Query execution tasks +== system.execs + +Currently running execution tasks across the cluster. Visible only to a superuser. Each query in `system.queries` typically corresponds to one or more rows in this table. + +[cols="<30%,<15%,<10%,<45%",options="header"] +|=== +|Column |Type |Nullable |Description + +|`node` |`text` |No |Node executing the task. +|`qid` |`text` |No |Identifier of the parent query. Join with `system.queries.qid`. +|`data_task_id` |`bigint` |Yes |Identifier of the data task within the query. +|`state` |`text` |No |Current state of the execution task. +|`memory` |`bigint` |No |Memory consumed by the task, in bytes. +|`privileged` |`boolean` |No |`TRUE` if the task runs with privileged access. +|=== [source,sql] ---- -SELECT * FROM system.execs; +SELECT node, qid, state, memory FROM system.execs ORDER BY memory DESC; ----