Cloud

Redpanda Catalogs

A Redpanda catalog is a named collection of source data, typically the data in your Redpanda cluster, that Redpanda SQL exposes as queryable SQL tables.

When Redpanda SQL is enabled on your cluster, a default Redpanda catalog named default_redpanda_catalog is created automatically. Use this catalog to map your Redpanda topics as SQL tables and query them.

After reading this page, you will be able to:

  • Explain the components of the Redpanda catalog model

  • Recognize when the default Redpanda catalog is auto-created

Redpanda SQL operates in read-only mode. Data Manipulation Language (DML) operations such as INSERT, UPDATE, and DELETE are not available. Data is ingested into Redpanda topics and made queryable through catalog mappings.

Catalog model

The Redpanda catalog model has three components:

  • Storage connection: A named connection to an object storage bucket or container that backs the catalog. The default Redpanda catalog’s storage connection is automatically defined using your cluster’s object storage.

  • Catalog: A named collection of source data, typically containing your Redpanda cluster’s topics.

  • Tables: Redpanda topics mapped as queryable SQL tables using the catalog_name⇒table_name syntax.

Layered catalogs for Iceberg-enabled topics

To query an Iceberg-enabled topic alongside its history in Apache Iceberg, a Redpanda catalog is layered over an Iceberg catalog using the USING CATALOG clause of CREATE REDPANDA CATALOG. The layered Redpanda catalog reads live records from the topic and historical records from the linked Iceberg catalog, returning both in a single query.

In Redpanda BYOC, both catalogs are created and linked for you when Redpanda SQL is enabled, so you can query an Iceberg-enabled topic with a simple CREATE TABLE against default_redpanda_catalog. No manual CREATE ICEBERG CATALOG or CREATE REDPANDA CATALOG …​ USING CATALOG is required. To inspect the layered relationship, run DESCRIBE REDPANDA CATALOG default_redpanda_catalog.

Example

Map a Redpanda topic as a SQL table through default_redpanda_catalog:

CREATE TABLE default_redpanda_catalog=>user_events
WITH (topic = 'user-events');

Query the table:

SELECT * FROM default_redpanda_catalog=>user_events LIMIT 10;
Statement Description

CREATE REDPANDA CATALOG

Create a catalog connection to a Redpanda cluster.

ALTER REDPANDA CATALOG

Modify connection properties of an existing catalog.

CREATE TABLE

Map a Redpanda topic to a SQL table through a catalog.

ALTER TABLE

Modify options of an existing catalog table.

DROP TABLE

Remove a catalog table mapping.

DROP REDPANDA CATALOG

Remove a Redpanda catalog connection.

DROP STORAGE

Remove a named storage definition.

SHOW TABLES

List tables within a catalog.

DESCRIBE

Show details about a catalog or catalog table.

CREATE STORAGE

Create a connection to external object storage.

ALTER STORAGE

Modify an existing storage connection.