Cloud

Redpanda SQL Quickstart

Connect to Redpanda SQL on a Bring Your Own Cloud (BYOC) cluster and run your first query against streaming data, with no ETL pipelines required. For querying topics with Iceberg history, see Query Iceberg-enabled Topics.

After reading this page, you will be able to:

  • Connect to Redpanda SQL using psql and a bearer token

  • Query a Redpanda topic with SQL

Prerequisites

  • A Redpanda BYOC cluster on AWS with Redpanda SQL enabled. See Enable Redpanda SQL on a BYOC Cluster.

  • Admin access to your cluster in the Redpanda Cloud Console, or a role with the SQL: Manage permission. You need one of these to view SQL connection details and to create catalogs, tables, and grants in the SQL engine. For more information on authorization in Redpanda Cloud, see Role-Based Access Control (RBAC).

  • A Redpanda topic with a schema registered in Schema Registry. If you don’t have one, follow the optional Produce sample data section below to create a sample orders topic.

  • rpk v26.1.6 or later installed on your local machine to generate an authentication token.

  • psql v16 or later (PostgreSQL client) installed on your local machine.

Produce sample data

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 topic with a corresponding schema in Schema Registry yet, follow these steps to create an orders topic with a small set of sample records.

You also need permissions to create topics, register schemas, and produce records.

  1. Log in to Redpanda Cloud and select your cluster.

  2. On the Topics page, click Create Topic. Name the topic orders and create it with default settings.

  3. Open the orders topic you just created. Click Produce record.

  4. Produce each sample record one at a time. For each record, set:

    • Key: Null type

    • Value: JSON type, then paste the JSON object into the Data field.

    {"order_id": 1, "customer": "alice", "product": "keyboard", "amount": 7500, "status": "completed"}
    {"order_id": 2, "customer": "bob", "product": "monitor", "amount": 32000, "status": "shipped"}
    {"order_id": 3, "customer": "carol", "product": "mouse", "amount": 4500, "status": "pending"}
    {"order_id": 4, "customer": "alice", "product": "monitor", "amount": 32000, "status": "completed"}
    {"order_id": 5, "customer": "dave", "product": "keyboard", "amount": 7500, "status": "pending"}

  5. On the Schema Registry page, click Create new schema.

  6. Create a new schema with the following:

    • Strategy: Topic

    • Topic name: orders

    • Schema applies to: Value

    • Schema definition: Select JSON format and paste the following schema definition:

      {
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Order",
  "type": "object",
  "properties": {
    "order_id": { "type": "integer" },
    "customer": { "type": "string" },
    "product":  { "type": "string" },
    "amount":   { "type": "integer", "description": "Amount in cents" },
    "status":   { "type": "string", "enum": ["pending", "shipped", "completed"] }
  },
  "required": ["order_id", "customer", "product", "amount", "status"]
}

      Click Save to register the schema.

Connect to Redpanda SQL

SQL connection details are available on your cluster’s SQL tab in the Cloud Console. To connect using psql:

  1. Log in to Redpanda Cloud with rpk. This opens a browser window for SSO sign-in:

    rpk cloud login

  2. Retrieve a temporary authentication token for the SQL engine:

    rpsql_token=$(rpk cloud auth token)

  3. Copy and run the psql connection string from the SQL tab:

    psql "host=<sql-external-endpoint> port=5432 dbname=oxla user=ignored password=$rpsql_token options='-c auth_method=bearer' sslmode=require"

Upon a successful connection, you see output similar to:

psql (17.8 (Homebrew), server 16.0 (oxla version: 1.0.0, build: af2dffb-Release-x86_64-GNU, asio))
SSL connection (protocol: TLSv1.2, cipher: ECDHE-RSA-AES256-GCM-SHA384, compression: off, ALPN: none)
Type "help" for help.

=>

Query topic data

When you enable Redpanda SQL, a Redpanda catalog named default_redpanda_catalog is created automatically and points at your cluster. To query a Redpanda topic, define a SQL table against the topic, then run standard SQL queries against the table.

  1. Define a SQL table from the topic with CREATE TABLE. The following example uses the orders topic from the optional sample data section. To use your own topic, replace orders with your topic name. Your topic must have a schema registered in Schema Registry under the topic-name strategy default (schema subject <topic>-value).

    CREATE TABLE default_redpanda_catalog=>orders WITH (
  topic = 'orders',
  confluent_wire_protocol = 'false'
);

    Redpanda SQL reads the registered schema and maps each top-level field to a SQL column.

    Records produced through the Cloud Console don’t carry the Schema Registry wire format prefix, so the example sets confluent_wire_protocol = 'false'. If your producer client adds the wire format, set this option to 'true' or omit it. For details on this and other CREATE TABLE options, see CREATE TABLE.

  2. Run SQL queries against the table. These examples use the orders schema from the optional sample data section.

    View a sample of records:

    SELECT * FROM default_redpanda_catalog=>orders LIMIT 10;

    Count orders by status:

    SELECT status, COUNT(*) AS total_orders
FROM default_redpanda_catalog=>orders
GROUP BY status;

    Find the largest orders:

    SELECT order_id, customer, product, amount
FROM default_redpanda_catalog=>orders
WHERE amount > 10000
ORDER BY amount DESC
LIMIT 20;

Grant access to a non-admin user

To share SQL access with a teammate or service account:

  1. In Redpanda Cloud, assign the user a role with the SQL: Access permission (see Configure RBAC in the Data Plane). Redpanda Cloud provisions a corresponding user in the SQL engine.

  2. As a SQL: Manage user, grant SELECT on the topics they need. The user identifier is the email on the user’s Redpanda Cloud account:

    GRANT SELECT ON EXTERNAL SOURCE default_redpanda_catalog => 'orders' TO "alice@example.com";

For the full access model (privilege levels, wildcards, schema-level permissions, and grant inspection), see Manage access to Redpanda SQL.

The user can now connect to Redpanda SQL and run SELECT against the tables they’ve been granted.

Next steps