# Query Streaming Topics

> For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [cloud-data-platform-full.txt](https://docs.redpanda.com/cloud-data-platform-full.txt)

---
title: Query Streaming Topics
latest-operator-version: v26.1.4
latest-console-tag: v3.7.3
latest-connect-version: 4.93.0
latest-redpanda-tag: v26.1.9
docname: query-data/query-streaming-topics
page-component-name: cloud-data-platform
page-version: master
page-component-version: master
page-component-title: Cloud
page-relative-src-path: query-data/query-streaming-topics.adoc
page-edit-url: https://github.com/redpanda-data/cloud-docs/edit/main/modules/sql/pages/query-data/query-streaming-topics.adoc
description: Map a Redpanda topic to a SQL table and run analytical queries directly against live streaming data.
page-topic-type: how-to
personas: app_developer, data_engineer
learning-objective-1: Map a Redpanda topic to a SQL table using the default Redpanda catalog
learning-objective-2: Run analytical SQL queries against live topic data
page-git-created-date: "2026-05-26"
page-git-modified-date: "2026-05-26"
---

<!-- Source: https://docs.redpanda.com/cloud-data-platform/sql/query-data/query-streaming-topics.md -->

Map a Redpanda topic to a SQL table to run analytical queries directly against live streaming data without building ETL pipelines. Redpanda SQL reads each record’s fields from the topic’s registered schema.

To extend queries past your Redpanda retention window by reading the Iceberg history of Iceberg-enabled topics, see [Query Iceberg-enabled Topics](https://docs.redpanda.com/cloud-data-platform/sql/query-data/query-iceberg-topics/).

After reading this page, you will be able to:

-   Map a Redpanda topic to a SQL table using the default Redpanda catalog

-   Run analytical SQL queries against live topic data


## [](#prerequisites)Prerequisites

Before you query a topic with SQL:

-   Enable the Redpanda SQL engine on your Redpanda Bring Your Own Cloud (BYOC) cluster. See [Enable Redpanda SQL](https://docs.redpanda.com/cloud-data-platform/sql/get-started/deploy-sql-cluster/).

-   Have a Redpanda Cloud user with the **SQL: Access** (or **SQL: Manage**) data-plane RBAC permission. For a **SQL: Access** user to query a topic, a **SQL: Manage** user must first `GRANT SELECT` on the topic to that user. See [Manage access to Redpanda SQL](https://docs.redpanda.com/cloud-data-platform/sql/manage/manage-access/).

-   Connect to Redpanda SQL with `psql` or another PostgreSQL client. See [Redpanda SQL Quickstart](https://docs.redpanda.com/cloud-data-platform/sql/get-started/sql-quickstart/) for a `psql` example, or [Connect to Redpanda SQL](https://docs.redpanda.com/cloud-data-platform/sql/connect-to-sql/).

-   Confirm that the Redpanda topic you want to query has a schema registered in Schema Registry. Redpanda SQL supports Protobuf, JSON, and Avro schemas.


## [](#map-the-topic-to-a-sql-table)Map the topic to a SQL table

Each Redpanda topic appears as a SQL table inside a Redpanda catalog. When Redpanda SQL is enabled, a catalog named `default_redpanda_catalog` is created automatically and points at your cluster.

Define a table against the topic with `CREATE TABLE`:

```sql
CREATE TABLE default_redpanda_catalog=>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. `schema_subject` is optional. If omitted, Redpanda SQL uses the topic-name strategy default (`<topic>-value`).

If the topic uses a Protobuf schema that defines more than one message, also set `output_schema_message_full_name` to the fully-qualified name of the message to use:

```sql
CREATE TABLE default_redpanda_catalog=>orders WITH (
  topic = 'orders',
  schema_subject = 'orders-value',
  output_schema_message_full_name = 'com.example.orders.Order'
);
```

The table inherits its column definitions from the registered schema. Each top-level field in the schema becomes a SQL column. For querying nested fields in struct types, see [Query Topics with Nested Fields](https://docs.redpanda.com/cloud-data-platform/sql/query-data/query-nested-fields/).

In addition to the columns derived from your topic’s schema, Redpanda SQL adds two struct columns to every catalog-mapped table:

-   `redpanda`: Kafka record metadata such as partition, offset, and timestamp.

-   `redpanda_raw`: Populated only when `error_handling_policy = 'FILL_NULL'` and a record fails to decode.


For details, see [Auto-added columns](https://docs.redpanda.com/cloud-data-platform/reference/sql/sql-statements/create-table/#auto-added-columns).

## [](#run-queries)Run queries

Query the table with standard `SELECT` syntax. The following query returns the first 10 records:

```sql
SELECT * FROM default_redpanda_catalog=>orders LIMIT 10;
```

Aggregate and filter records using familiar PostgreSQL constructs:

```sql
SELECT customer_id, SUM(amount) AS total
FROM default_redpanda_catalog=>orders
WHERE status = 'completed'
GROUP BY customer_id
ORDER BY total DESC
LIMIT 10;
```

## [](#next-steps)Next steps

-   [Query Iceberg-enabled Topics](https://docs.redpanda.com/cloud-data-platform/sql/query-data/query-iceberg-topics/): run queries against historical data retained beyond your Redpanda retention window.

-   [CREATE TABLE](https://docs.redpanda.com/cloud-data-platform/reference/sql/sql-statements/create-table/): full reference for the table-against-topic syntax, including all options.

-   [Redpanda SQL Reference](https://docs.redpanda.com/cloud-data-platform/reference/sql/): supported SQL statements, clauses, data types, and functions.