diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index fc68a8f5..44f084f4 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -335,17 +335,33 @@ *** xref:develop:connect/cookbooks/jira.adoc[] * xref:sql:index.adoc[Redpanda SQL] -// ** quickstart.adoc -** xref:sql:get-started/what-is-redpanda-sql.adoc[Overview] -*** xref:sql:get-started/oltp-vs-olap.adoc[] -*** xref:sql:get-started/redpanda-sql-vs-postgresql.adoc[] +// ============================================================================ +// DOC-1993 — Redpanda SQL IA (target BYOC AWS GA 2026-05-22) +// Most placeholders below do not have linked pages until pages land (except DOC-1856). +// Add xrefs per ticket as pages are created. +// ============================================================================ +// ** xref:sql:get-started/index.adoc[Get Started] +// *** xref:sql:get-started/sql-quickstart.adoc[Quickstart] // DOC-1856 (in review, draft on DOC-1856 branch) +// *** xref:sql:get-started/deploy-sql-cluster.adoc[Enable Redpanda SQL] // DOC-1856 +** Get Started +*** Quickstart +*** Enable Redpanda SQL +*** xref:sql:get-started/what-is-redpanda-sql.adoc[Overview] +**** xref:sql:get-started/oltp-vs-olap.adoc[] +**** xref:sql:get-started/redpanda-sql-vs-postgresql.adoc[] ** xref:sql:connect-to-sql/index.adoc[Connect to Redpanda SQL] *** xref:sql:connect-to-sql/language-clients/psycopg2.adoc[] *** xref:sql:connect-to-sql/language-clients/java-jdbc.adoc[] *** xref:sql:connect-to-sql/language-clients/php-pdo.adoc[] *** xref:sql:connect-to-sql/language-clients/dotnet-dapper.adoc[] +** xref:sql:query/index.adoc[Query data] +*** xref:sql:query/query-redpanda-topics.adoc[Query Redpanda topics] +*** Query Iceberg +** Manage Redpanda SQL +*** Configure OIDC ** xref:sql:troubleshoot/index.adoc[Troubleshoot] *** xref:sql:troubleshoot/degraded-state-handling.adoc[] +*** Memory management * xref:develop:index.adoc[Develop] ** xref:develop:kafka-clients.adoc[] diff --git a/modules/sql/pages/query/index.adoc b/modules/sql/pages/query/index.adoc new file mode 100644 index 00000000..a3ae5662 --- /dev/null +++ b/modules/sql/pages/query/index.adoc @@ -0,0 +1,3 @@ += Query data +:description: Query streaming data in Redpanda topics and lakehouse data in Iceberg tables using standard PostgreSQL syntax. +:page-layout: index diff --git a/modules/sql/pages/query/query-redpanda-topics.adoc b/modules/sql/pages/query/query-redpanda-topics.adoc new file mode 100644 index 00000000..5173f96d --- /dev/null +++ b/modules/sql/pages/query/query-redpanda-topics.adoc @@ -0,0 +1,66 @@ += Query Redpanda topics +:description: Map a Redpanda topic to a SQL table and run analytical queries directly against streaming data. +:page-topic-type: how-to +:personas: app_developer, data_engineer +:learning-objective-1: Map a Redpanda topic to a SQL table using a Redpanda catalog +:learning-objective-2: Run analytical SQL queries against Redpanda topic data + +Map a Redpanda topic to a SQL table to run analytical queries directly against streaming data without building ETL pipelines. Redpanda SQL reads each record's fields from the topic's Protobuf schema in Schema Registry. + +After completing these steps, you will be able to: + +* [ ] {learning-objective-1} +* [ ] {learning-objective-2} + +== Prerequisites + +Before you query a topic with SQL: + +* Enable the Redpanda SQL engine on your Redpanda Cloud Bring Your Own Cloud (BYOC) cluster. See xref:sql:get-started/sql-quickstart.adoc[Quickstart]. +* Connect to Redpanda SQL with `psql` or another PostgreSQL client. See xref:sql:connect-to-sql/index.adoc[Connect to Redpanda SQL]. +* Confirm that the Redpanda topic you want to query has a Protobuf schema registered in Schema Registry. + +== Map the topic to a SQL table + +Each Redpanda topic appears as a SQL table inside a Redpanda catalog. When you enable the SQL engine, Redpanda SQL automatically creates a catalog named `default_redpanda_connection` that points at your cluster. + +Define a table against the topic with `CREATE TABLE`: + +[source,sql] +---- +CREATE TABLE default_redpanda_connection=>orders WITH ( + topic = 'orders', + schema_subject = 'orders-value' +); +---- + +Replace `orders` with your topic name and `orders-value` with the Schema Registry subject that holds the topic's value schema. + +The table inherits its column definitions from the registered Protobuf schema. Each top-level Protobuf field becomes a SQL column. + +== Run queries + +Query the table with standard `SELECT` syntax. The following query returns the first 10 records: + +[source,sql] +---- +SELECT * FROM default_redpanda_connection=>orders LIMIT 10; +---- + +Aggregate and filter records using familiar PostgreSQL constructs: + +[source,sql] +---- +SELECT customer_id, SUM(amount) AS total +FROM default_redpanda_connection=>orders +WHERE status = 'completed' +GROUP BY customer_id +ORDER BY total DESC +LIMIT 10; +---- + +== Next steps + +* xref:reference:sql/sql-statements/create-table.adoc[CREATE TABLE]: full reference for the table-against-topic syntax, including all options. +* xref:reference:sql/sql-statements/create-redpanda-catalog.adoc[CREATE REDPANDA CATALOG]: define additional Redpanda catalogs with custom connection settings. +* xref:reference:sql/index.adoc[Redpanda SQL Reference]: supported SQL statements, clauses, data types, and functions.