Cloud

REFRESH

Use the REFRESH statement after a table’s schema changes outside Redpanda SQL. The statement updates the schema that Redpanda SQL stores for the table in a catalog. Queries then use the current columns and types.

On this page, the schema of a table means its columns and their types. A schema_name is a SQL schema, which is a namespace.

Syntax

To refresh a table in a Redpanda catalog:

REFRESH [schema_name.]catalog_name=>table_name;

To refresh a table in an Iceberg catalog:

REFRESH [schema_name.]catalog_name=>namespace.table_name;

  • schema_name: Optional. Name of the Redpanda SQL schema that holds the catalog. If you omit it, Redpanda SQL finds the catalog through the search path.

  • catalog_name: Name of the Redpanda catalog or Iceberg catalog that holds the table, such as default_redpanda_catalog.

  • namespace: Name of the Iceberg namespace that holds the table. Use it only for a table in an Iceberg catalog. Iceberg tables always need a namespace.

  • table_name: Name of the table to refresh.

When to run REFRESH

  • After you register a new schema version for a topic in Schema Registry. For a table in a Redpanda catalog, REFRESH reads the latest schema for the topic’s subject. It then updates the table’s columns.

  • After the schema of a table in an Iceberg catalog changes, for example when another engine adds a column.

  • When a query fails with Schema not found for Iceberg table '<table_name>'.

The REFRESH statement changes only the schema that Redpanda SQL stores. It does not change the topic, the Schema Registry subject, or the Iceberg table.

Behavior

  • A Redpanda catalog can link to an Iceberg catalog. For a table in a linked Redpanda catalog, REFRESH also updates the stored schema of the topic’s Iceberg table.

  • For a table in an Iceberg catalog, Redpanda SQL accepts only the namespaces that the catalog allows. The allowed_namespaces option sets these namespaces. If the namespace is not allowed, the statement fails with namespace "<namespace>" is outside the allowed_namespaces scope of iceberg catalog "<catalog_name>".

  • If the table is not in the catalog, the statement fails. For a Redpanda catalog, the error is source "<table_name>" does not exist in catalog "<catalog_name>".

  • To see which Iceberg tables have a stored schema, query system.iceberg_tables.

  • The statement contacts Schema Registry or the Iceberg REST catalog. If the service cannot be reached, the statement fails with an error that names the service.

In Redpanda Cloud, you cannot query a table in an Iceberg catalog directly. To query the Iceberg history of a topic, query the topic’s table in the Redpanda catalog. See Query Iceberg-enabled topics.

Permissions

Only the owner of the catalog or a superuser can run REFRESH. In Redpanda Cloud, Redpanda creates the default catalogs. To refresh a table in a default catalog, you need the SQL: Manage permission, which makes you a superuser. See Manage access to Redpanda SQL.

Examples

After you register a new schema version for the orders topic, refresh its table in the default Redpanda catalog:

REFRESH default_redpanda_catalog=>orders;

Refresh the orders table in the redpanda namespace of the default Iceberg catalog. In Redpanda Cloud, you cannot query this table directly. See the note in Behavior.

REFRESH default_iceberg_catalog=>redpanda.orders;

Suggested reading