Cloud

Tables and Views

Redpanda SQL gives you tables and views to query. A topic-backed table gets its schema and data from a Redpanda topic. A view is a named query over tables and other views. Redpanda SQL stores the view’s query, not its results. Knowing which kind of object you query tells you where its schema comes from, whether you can change it, and how to manage it.

After reading this page, you will be able to:

Describe the kinds of tables and views in Redpanda SQL
Explain where each kind gets its schema and data
Differentiate between a topic-backed table and a view

Topic-backed tables

A topic-backed table gets its schema and data from a Redpanda topic. You don’t define its columns with SQL. The table follows the schema of the topic. Redpanda SQL has two kinds of topic-backed tables.

Topic-backed tables in a Redpanda catalog

You create this table with CREATE TABLE in a Redpanda catalog, such as default_redpanda_catalog. The statement maps a topic to the table. Redpanda SQL then reads the topic’s records when you query the table.

The table is read-only. You can’t insert rows into it.
Redpanda SQL adds two columns: redpanda, with the record metadata, and redpanda_raw, with the raw payload of a record that fails to decode. See Auto-added columns.
If the topic is an Iceberg-enabled topic, the same table also reads the topic’s history from Iceberg. One query returns both live and historical records. See Query Iceberg-enabled Topics.
DROP TABLE removes only the mapping. The topic and its data don’t change.

Topic-backed Iceberg tables

When a topic has Iceberg enabled, Redpanda Streaming writes the topic’s records to an Iceberg table in the Iceberg catalog. Redpanda Streaming creates this table and changes its schema when the topic’s schema changes. By default, Redpanda Streaming deletes the table when you delete the topic. See Iceberg data retention.

In Redpanda Cloud, you read a topic-backed Iceberg table through the topic’s table in the Redpanda catalog.

Views

A view is a named SELECT query that you reference like a table. You create it with CREATE VIEW.

A view stores no data. Each time you query a view, Redpanda SQL runs its stored query, so the results reflect the current data.
A view can read topic-backed tables in a Redpanda catalog and other views.
You create a view in a Redpanda SQL schema, such as public, not in a catalog.
Redpanda SQL stores the view’s columns when you create it. If a table that the view reads gains a column, a view that uses SELECT * stops working until you drop it and create it again. List the columns in the query to avoid this.
Grant SELECT on a view only to users who can see the data that it returns.

When to use a view

A view lives in Redpanda SQL, so anyone who can query it can use it by name. Use a view when you want to:

Share a query. Users, applications, and business intelligence (BI) tools query the view by name from any PostgreSQL client. They don’t need a copy of the query, and everyone uses the same definition.
Build on a query. You can filter, join, or aggregate a view in another query. A view can also read other views, so you can build complex logic in steps.
Limit what a role can see. A view runs its query with the privileges of its owner. Grant SELECT on the view to a role that has no access to the tables that the view reads. The role then sees only the columns and rows that the view returns. See CREATE VIEW permissions.
Hide catalog details. Users write FROM recent_orders instead of naming the catalog, the topic-backed table, and the filter logic in every query.

Because Redpanda SQL runs the view’s query each time that someone queries the view, an expensive query costs the same every time.

Redpanda SQL does not support materialized views. Support is planned for a future release.

Where tables and views live

Redpanda SQL organizes objects in SQL schemas, such as public. A SQL schema contains catalogs and views:

public                         SQL schema
├── default_redpanda_catalog   Redpanda catalog
├── default_iceberg_catalog    Iceberg catalog
└── recent_orders              view

A catalog connects Redpanda SQL to a data source. A Redpanda catalog connects to the topics in your Redpanda cluster. An Iceberg catalog connects to the Iceberg REST catalog that holds your Iceberg tables. Redpanda SQL reads the data from the source when you query it, and doesn’t store a copy. The tables are behind the catalog, so you name a table through its catalog, such as default_redpanda_catalog=>orders for a topic-backed table in a Redpanda catalog.

A view is not part of a catalog connection. Redpanda SQL stores the view definition, which is its name, owner, and query, in its internal catalog in object storage. Other engines that read your Iceberg catalog can’t see the view. You name a view by its schema and view name, with no catalog name:

recent_orders, which Redpanda SQL finds through the search path
public.recent_orders, with the schema

Compare tables and views

Aspect Topic-backed table in a Redpanda catalog Topic-backed Iceberg table View

Aspect	Topic-backed table in a Redpanda catalog	Topic-backed Iceberg table	View
Where it lives	A Redpanda catalog, such as `default_redpanda_catalog`	The Iceberg catalog, in the namespace for Iceberg topics	A Redpanda SQL schema, such as `public`. Redpanda SQL stores the view definition in its internal catalog, in object storage.
Who creates it	You, with `CREATE TABLE`	Redpanda Streaming, when a topic has Iceberg enabled	You, with `CREATE VIEW`
Where its schema comes from	The topic	The topic	The view’s query
Where its data comes from	The topic’s records, and its Iceberg history if the topic has Iceberg enabled	The topic’s records that Redpanda Streaming writes to Iceberg	The tables and views that the query reads
Can you insert rows?	No	No	No
How to remove it	`DROP TABLE` removes the mapping only	Delete the topic. By default, Redpanda Streaming then deletes the table.	`DROP VIEW`

Where it lives

A Redpanda catalog, such as default_redpanda_catalog

The Iceberg catalog, in the namespace for Iceberg topics

A Redpanda SQL schema, such as public. Redpanda SQL stores the view definition in its internal catalog, in object storage.

Who creates it

You, with CREATE TABLE

Redpanda Streaming, when a topic has Iceberg enabled

You, with CREATE VIEW

Where its schema comes from

The topic

The view’s query

Where its data comes from

The topic’s records, and its Iceberg history if the topic has Iceberg enabled

The topic’s records that Redpanda Streaming writes to Iceberg

The tables and views that the query reads

Can you insert rows?

How to remove it

DROP TABLE removes the mapping only

Delete the topic. By default, Redpanda Streaming then deletes the table.

DROP VIEW

List tables and views

To list the tables in a Redpanda catalog, run SHOW REDPANDA TABLES.
To list the Iceberg tables that Redpanda SQL has registered, run SHOW ICEBERG TABLES.
To list views, query pg_views.

See SHOW TABLES.