From 563a59af4457fbdea7a986825d740a9c7346901e Mon Sep 17 00:00:00 2001 From: Kat Batuigas Date: Fri, 1 May 2026 17:21:12 -0700 Subject: [PATCH 1/6] Add quickstart draft --- .../sql/pages/get-started/sql-quickstart.adoc | 167 ++++++++++++++++++ 1 file changed, 167 insertions(+) create mode 100644 modules/sql/pages/get-started/sql-quickstart.adoc diff --git a/modules/sql/pages/get-started/sql-quickstart.adoc b/modules/sql/pages/get-started/sql-quickstart.adoc new file mode 100644 index 00000000..20c706da --- /dev/null +++ b/modules/sql/pages/get-started/sql-quickstart.adoc @@ -0,0 +1,167 @@ += Redpanda SQL quickstart +:description: Connect to Redpanda SQL on a BYOC cluster and run your first query on streaming data. +:page-topic-type: guide + +Redpanda SQL is a PostgreSQL-compatible SQL engine built into Redpanda BYOC. It lets you query streaming data in your Redpanda topics with standard SQL, without building ETL pipelines or deploying a separate analytics system. In this quickstart, you connect with `psql` and run your first query against a Redpanda topic. + +== Prerequisites + +* A Redpanda BYOC cluster on AWS with Redpanda SQL enabled. See xref:sql:get-started/deploy-sql-cluster.adoc[]. +* A Redpanda topic with a schema registered in Schema Registry. If you don't have one, follow the optional <> section below to create a sample `orders` topic. +* https://www.postgresql.org/download/[`psql`^] (PostgreSQL client) installed on your local machine. + +// TODO: Verify the exact connection string format and where users get credentials. +// From PRD: SCRAM auth preserved, connection string available in Cloud Console and API response. +// Confirm with engineering what SCRAM credentials does the user use - superuser auto-created by Control Plane? + +== Get connection details + +After Redpanda SQL is provisioned on your cluster: + +. In the Redpanda Cloud Console, go to your cluster and open the *SQL* tab. +. Copy the connection string. + +== Connect to Redpanda SQL + +Use `psql` to connect to the SQL engine. Paste the connection string you copied from the Console: + +// TODO: Replace with actual connection string format once confirmed with engineering. +[,bash] +---- +psql "" +---- + +On a successful connection, you should see output similar to: + +// TODO: Verify current psql banner text. +[.no-copy] +---- +psql (14.x, server 16.0) +SSL connection (protocol: TLSv1.3) +Type "help" for help. + +=> +---- + +[#optional-produce-sample-data] +== (Optional) Produce sample data + +[TIP] +==== +Skip this section if you already have a Redpanda topic with a schema registered in Schema Registry that you want to query. +==== + +If you don't have a schema-registered topic to query yet, follow these steps to create an `orders` topic with a small set of sample records. Redpanda SQL reads the topic's schema from Schema Registry to map fields to SQL columns, so the topic must have a registered schema before you can query it. + +This section uses xref:reference:rpk/index.adoc[`rpk`], which you can install by following xref:get-started:rpk-install.adoc[]. You also need a user with permissions to create topics, register schemas, and produce records. + +. Create a topic: ++ +[,bash] +---- +rpk topic create orders +---- + +. Save the following Protobuf schema as `order.proto`: ++ +// TODO: Confirm the GA-supported schema format(s) with engineering. If JSON Schema is supported at GA, consider switching this example to JSON for simpler UX. +[,proto] +---- +syntax = "proto3"; + +message Order { + int64 order_id = 1; + string customer = 2; + string product = 3; + int64 amount = 4; // amount in cents + string status = 5; // "pending", "shipped", "completed" +} +---- + +. Register the schema against the topic's value subject: ++ +[,bash] +---- +rpk registry schema create orders-value --schema order.proto +---- + +. Produce a few sample records. The `--schema-id=topic` flag tells `rpk` to use the topic name strategy to look up the schema you just registered: ++ +[,bash] +---- +rpk topic produce orders --schema-id=topic < 10000 +ORDER BY amount DESC +LIMIT 20; +---- + +== Inspect your SQL cluster + +Redpanda SQL provides built-in commands to inspect the state of your SQL cluster: + +[,sql] +---- +SHOW NODES; -- List SQL compute nodes and their status +SHOW QUERIES; -- List currently running queries +---- + +== Next steps + +* xref:reference:sql/index.adoc[Redpanda SQL reference]: Explore the full SQL syntax, data types, functions, and clauses. +* xref:sql:connect-to-sql/language-clients/psycopg2.adoc[Connect with Python (psycopg2)]: Query Redpanda SQL programmatically. +* xref:sql:connect-to-sql/language-clients/java-jdbc.adoc[Connect with Java (JDBC)]: Integrate with Java applications. From b1e537eaf5422deb3482b863333691fbdc86b369 Mon Sep 17 00:00:00 2001 From: Kat Batuigas Date: Fri, 1 May 2026 17:21:48 -0700 Subject: [PATCH 2/6] Add deploy doc (use case 1) --- .../pages/get-started/deploy-sql-cluster.adoc | 162 ++++++++++++++++++ 1 file changed, 162 insertions(+) create mode 100644 modules/sql/pages/get-started/deploy-sql-cluster.adoc diff --git a/modules/sql/pages/get-started/deploy-sql-cluster.adoc b/modules/sql/pages/get-started/deploy-sql-cluster.adoc new file mode 100644 index 00000000..76f5494b --- /dev/null +++ b/modules/sql/pages/get-started/deploy-sql-cluster.adoc @@ -0,0 +1,162 @@ += Enable Redpanda SQL on a BYOC cluster +:description: Enable the Redpanda SQL engine on a BYOC cluster so that users can query streaming data with standard PostgreSQL syntax. +:page-topic-type: how-to + +Enable Redpanda SQL on a BYOC cluster to give your team the ability to query streaming data in Redpanda topics using standard PostgreSQL syntax. + +== Prerequisites + +To enable Redpanda SQL, you need: + +* Admin permissions in your Redpanda Cloud organization. +* For the Cloud API path, a valid bearer token for the link:/api/doc/cloud-controlplane/topic/topic-cloud-api-overview[Cloud API]. See link:/api/doc/cloud-controlplane/authentication[Authenticate to the API]. + +== Enable Redpanda SQL + +You can enable Redpanda SQL when you create a new BYOC cluster or on an existing cluster. + +=== On a new cluster + +[tabs] +===== +Cloud Console:: ++ +-- +. Log in to https://cloud.redpanda.com[Redpanda Cloud^]. +. Start creating a new BYOC cluster on AWS. For details and prerequisites, see xref:get-started:cluster-types/byoc/aws/create-byoc-cluster-aws.adoc[]. +. In the cluster creation form, select the option to enable SQL. +. Complete the remaining cluster configuration and deploy. +-- + +Cloud API:: ++ +-- +. Authenticate to the link:/api/doc/cloud-controlplane/topic/topic-cloud-api-overview[Cloud API]. For details, see link:/api/doc/cloud-controlplane/authentication[Authenticate to the API]. +. Make a link:/api/doc/cloud-controlplane/operation/operation-clusterservice_createcluster[`POST /v1/clusters`] request with `oxla.enabled` set to `true` in the cluster spec: ++ +[,bash] +---- +curl -X POST "https://api.redpanda.com/v1/clusters" \ + -H "Authorization: Bearer $AUTH_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ + "cluster": { + "name": "", + "cloud_provider": "CLOUD_PROVIDER_AWS", + "type": "TYPE_BYOC", + "region": "", + "zones": [ ], + "throughput_tier": "", + "resource_group_id": "", + "oxla": { + "enabled": true + } + } + }' +---- ++ +For the full request body and field reference, see the link:/api/doc/cloud-controlplane/operation/operation-clusterservice_createcluster[Create cluster API]. +. The request returns the ID of a long-running operation. Poll the link:/api/doc/cloud-controlplane/operation/operation-operationservice_getoperation[`GET /v1/operations/{operation.id}`] endpoint until the operation completes. +-- +===== + +=== On an existing cluster + +To enable, scale, or disable SQL on an existing cluster, you also need the cluster ID, which you can find in the *Details* section of the cluster overview in the Cloud Console. + +. Authenticate to the link:/api/doc/cloud-controlplane/topic/topic-cloud-api-overview[Cloud API]. For details, see link:/api/doc/cloud-controlplane/authentication[Authenticate to the API]. +. Make a link:/api/doc/cloud-controlplane/operation/operation-clusterservice_updatecluster[`PATCH /v1/clusters/{cluster.id}`] request, replacing `{cluster.id}` with your cluster ID: ++ +[,bash] +---- +curl -X PATCH "https://api.redpanda.com/v1/clusters/{cluster.id}" \ + -H "Authorization: Bearer $AUTH_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"oxla":{"enabled":true}}' +---- ++ +The request returns the ID of a long-running operation. Poll the link:/api/doc/cloud-controlplane/operation/operation-operationservice_getoperation[`GET /v1/operations/{operation.id}`] endpoint until the operation completes: ++ +[,bash] +---- +curl -X GET "https://api.redpanda.com/v1/operations/{operation.id}" \ + -H "Authorization: Bearer $AUTH_TOKEN" \ + -H "Content-Type: application/json" +---- ++ +When the operation is complete, the response shows `"state": "STATE_COMPLETED"`. + +== Scale Redpanda SQL + +Redpanda SQL supports horizontal scaling from 1 to 12 nodes per cluster. Scaling to 0 is not supported. To remove Redpanda SQL from a cluster, disable the SQL engine instead. + +[tabs] +===== +Cloud Console:: ++ +-- +. Log in to https://cloud.redpanda.com[Redpanda Cloud^]. +. Go to your BYOC cluster and open the *SQL* tab. +. Set the node count to a value between 1 and 12, then save. +-- + +Cloud API:: ++ +-- +Make a link:/api/doc/cloud-controlplane/operation/operation-clusterservice_updatecluster[`PATCH /v1/clusters/{cluster.id}`] request with the new replica count. Replace `{cluster.id}` with your cluster ID and `` with a value between 1 and 12: + +[,bash] +---- +curl -X PATCH "https://api.redpanda.com/v1/clusters/{cluster.id}" \ + -H "Authorization: Bearer $AUTH_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"oxla":{"replicas":}}' +---- + +The request returns the ID of a long-running operation. Poll link:/api/doc/cloud-controlplane/operation/operation-operationservice_getoperation[`GET /v1/operations/{operation.id}`] until the operation completes. +-- +===== + +== Verify the SQL engine is running + +After you enable Redpanda SQL, provisioning may take several minutes. To verify the SQL engine is running: + +// TODO: Confirm with engineering if there are any other specific status indicators that users can see in the Console when SQL is running. Is the SQL tab only visible when SQL is enabled? + +== Disable Redpanda SQL + +[WARNING] +==== +Disabling Redpanda SQL purges the stored catalog state for the SQL engine and deletes its data from object storage. In-flight queries fail when SQL is disabled. To temporarily stop SQL compute without losing state, <> instead. +==== + +[tabs] +===== +Cloud Console:: ++ +-- +. Log in to https://cloud.redpanda.com[Redpanda Cloud^]. +. Go to your BYOC cluster and open the *SQL* tab. +. Click *Remove* and confirm. +-- + +Cloud API:: ++ +-- +Make a link:/api/doc/cloud-controlplane/operation/operation-clusterservice_updatecluster[`PATCH /v1/clusters/{cluster.id}`] request with `oxla.enabled` set to `false`. Replace `{cluster.id}` with your cluster ID: + +[,bash] +---- +curl -X PATCH "https://api.redpanda.com/v1/clusters/{cluster.id}" \ + -H "Authorization: Bearer $AUTH_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"oxla":{"enabled":false}}' +---- + +The request returns the ID of a long-running operation. Poll link:/api/doc/cloud-controlplane/operation/operation-operationservice_getoperation[`GET /v1/operations/{operation.id}`] until the operation completes. +-- +===== + +== Next steps + +* xref:sql:get-started/sql-quickstart.adoc[Quickstart]: Connect to Redpanda SQL with `psql` and run your first query. From 74b96526a6ff07a60296b088c3df87d18d28ef14 Mon Sep 17 00:00:00 2001 From: Kat Batuigas Date: Fri, 1 May 2026 17:21:56 -0700 Subject: [PATCH 3/6] Add to nav --- modules/ROOT/nav.adoc | 4 +++- modules/sql/pages/get-started/index.adoc | 3 +++ 2 files changed, 6 insertions(+), 1 deletion(-) create mode 100644 modules/sql/pages/get-started/index.adoc diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index fc68a8f5..6a7a4aa3 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -335,7 +335,9 @@ *** xref:develop:connect/cookbooks/jira.adoc[] * xref:sql:index.adoc[Redpanda SQL] -// ** quickstart.adoc +** xref:sql:get-started/index.adoc[Get Started] +** xref:sql:get-started/sql-quickstart.adoc[Quickstart] +** xref:sql:get-started/deploy-sql-cluster.adoc[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[] diff --git a/modules/sql/pages/get-started/index.adoc b/modules/sql/pages/get-started/index.adoc new file mode 100644 index 00000000..1a7ab897 --- /dev/null +++ b/modules/sql/pages/get-started/index.adoc @@ -0,0 +1,3 @@ += Get Started with Redpanda SQL +:description: Get started with Redpanda SQL, a column-oriented OLAP query engine built into Redpanda Cloud that lets you query streaming topics using standard SQL. +:page-layout: index From 7d8aba0be4d249fecb3474f1c844f51ed736b2a9 Mon Sep 17 00:00:00 2001 From: Kat Batuigas Date: Fri, 1 May 2026 17:30:23 -0700 Subject: [PATCH 4/6] Info architecture for Get Started --- modules/ROOT/nav.adoc | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index 6a7a4aa3..49b23b90 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -336,11 +336,11 @@ * xref:sql:index.adoc[Redpanda SQL] ** xref:sql:get-started/index.adoc[Get Started] -** xref:sql:get-started/sql-quickstart.adoc[Quickstart] -** xref:sql:get-started/deploy-sql-cluster.adoc[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:get-started/sql-quickstart.adoc[Quickstart] +*** xref:sql:get-started/deploy-sql-cluster.adoc[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[] From 6bb2acb0cab7906be050a505f9eefd646c5822a8 Mon Sep 17 00:00:00 2001 From: Kat Batuigas Date: Tue, 5 May 2026 11:46:10 -0700 Subject: [PATCH 5/6] Remove create kafka source --- .../sql/pages/get-started/sql-quickstart.adoc | 96 ++++++++----------- 1 file changed, 41 insertions(+), 55 deletions(-) diff --git a/modules/sql/pages/get-started/sql-quickstart.adoc b/modules/sql/pages/get-started/sql-quickstart.adoc index 20c706da..5e05726e 100644 --- a/modules/sql/pages/get-started/sql-quickstart.adoc +++ b/modules/sql/pages/get-started/sql-quickstart.adoc @@ -14,35 +14,6 @@ Redpanda SQL is a PostgreSQL-compatible SQL engine built into Redpanda BYOC. It // From PRD: SCRAM auth preserved, connection string available in Cloud Console and API response. // Confirm with engineering what SCRAM credentials does the user use - superuser auto-created by Control Plane? -== Get connection details - -After Redpanda SQL is provisioned on your cluster: - -. In the Redpanda Cloud Console, go to your cluster and open the *SQL* tab. -. Copy the connection string. - -== Connect to Redpanda SQL - -Use `psql` to connect to the SQL engine. Paste the connection string you copied from the Console: - -// TODO: Replace with actual connection string format once confirmed with engineering. -[,bash] ----- -psql "" ----- - -On a successful connection, you should see output similar to: - -// TODO: Verify current psql banner text. -[.no-copy] ----- -psql (14.x, server 16.0) -SSL connection (protocol: TLSv1.3) -Type "help" for help. - -=> ----- - [#optional-produce-sample-data] == (Optional) Produce sample data @@ -64,7 +35,6 @@ rpk topic create orders . Save the following Protobuf schema as `order.proto`: + -// TODO: Confirm the GA-supported schema format(s) with engineering. If JSON Schema is supported at GA, consider switching this example to JSON for simpler UX. [,proto] ---- syntax = "proto3"; @@ -98,36 +68,62 @@ rpk topic produce orders --schema-id=topic <" ---- -The SQL engine fetches the topic's schema from Schema Registry automatically. +On a successful connection, you should see output similar to: -Redpanda SQL supports Protobuf, Avro, and JSON schemas registered in Schema Registry. The supported data types at GA are primitive scalar types (`INT`, `BIGINT`, `FLOAT`, `BOOLEAN`, `VARCHAR`, `TIMESTAMP`, and others) and `Struct`. +// TODO: Verify current psql banner text. +[.no-copy] +---- +psql (14.x, server 16.0) +SSL connection (protocol: TLSv1.3) +Type "help" for help. -NOTE: Nested JSON objects may be surfaced as `VARCHAR` containing the raw JSON string rather than as a navigable `Struct` column. The behavior depends on the serialization format: Avro and Protobuf schemas define field types explicitly and map to `Struct` where supported. JSON Schema fields typed as `object` may fall back to `VARCHAR`. +=> +---- + +== Query a Redpanda topic + +When you enable Redpanda SQL, the engine automatically creates a Redpanda catalog named `default_redpanda_connection` that connects to your cluster. + +To query a Redpanda topic as a SQL table, define a table against the topic with `CREATE TABLE`. The following example uses the `orders` topic from the previous section. Replace `orders` with the name of your topic, and `orders-value` with the Schema Registry subject that holds the topic's value schema: + +[,sql] +---- +CREATE TABLE default_redpanda_connection=>orders WITH ( + topic = 'orders', + schema_subject = 'orders-value' +); +---- + +Redpanda SQL reads the registered Protobuf schema from Schema Registry and maps each top-level field to a SQL column. == Run queries -After you create the source, query your topic data with standard SQL. The following examples use the `orders` schema from the optional sample data section. If you're using your own topic, substitute the topic name and column names below. +After you create the table, query your topic data with standard SQL. The following examples use the `orders` schema from the optional sample data section. If you're using your own topic, substitute the table name and column names. View a sample of records: [,sql] ---- -SELECT * FROM orders LIMIT 10; +SELECT * FROM default_redpanda_connection=>orders LIMIT 10; ---- Count orders by status: @@ -135,7 +131,7 @@ Count orders by status: [,sql] ---- SELECT status, COUNT(*) AS total_orders -FROM orders +FROM default_redpanda_connection=>orders GROUP BY status; ---- @@ -144,22 +140,12 @@ Find the largest orders: [,sql] ---- SELECT order_id, customer, product, amount -FROM orders +FROM default_redpanda_connection=>orders WHERE amount > 10000 ORDER BY amount DESC LIMIT 20; ---- -== Inspect your SQL cluster - -Redpanda SQL provides built-in commands to inspect the state of your SQL cluster: - -[,sql] ----- -SHOW NODES; -- List SQL compute nodes and their status -SHOW QUERIES; -- List currently running queries ----- - == Next steps * xref:reference:sql/index.adoc[Redpanda SQL reference]: Explore the full SQL syntax, data types, functions, and clauses. From 47d9205d563ffd6afa0155c64e05ae5c563aac64 Mon Sep 17 00:00:00 2001 From: Kat Batuigas Date: Tue, 5 May 2026 11:46:24 -0700 Subject: [PATCH 6/6] Move show/inspect statements to deploy doc --- modules/sql/pages/get-started/deploy-sql-cluster.adoc | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/modules/sql/pages/get-started/deploy-sql-cluster.adoc b/modules/sql/pages/get-started/deploy-sql-cluster.adoc index 76f5494b..74ccf340 100644 --- a/modules/sql/pages/get-started/deploy-sql-cluster.adoc +++ b/modules/sql/pages/get-started/deploy-sql-cluster.adoc @@ -123,6 +123,16 @@ After you enable Redpanda SQL, provisioning may take several minutes. To verify // TODO: Confirm with engineering if there are any other specific status indicators that users can see in the Console when SQL is running. Is the SQL tab only visible when SQL is enabled? +== Inspect your SQL cluster + +Redpanda SQL provides built-in commands to inspect the state of your SQL cluster: + +[,sql] +---- +SHOW NODES; -- List SQL compute nodes and their status +SHOW QUERIES; -- List currently running queries +---- + == Disable Redpanda SQL [WARNING]