> ## Documentation Index
> Fetch the complete documentation index at: https://docs.risingwave.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Built-in catalog

> Use RisingWave's built-in catalog to create and manage internal Iceberg tables with zero external dependencies.

RisingWave includes a built-in Iceberg catalog for internal Iceberg tables. It uses the same **metastore database** that RisingWave is configured with (via its metadata backend) as a JDBC-compliant Iceberg catalog, so you don’t need to deploy or manage a separate catalog service.

<Note>
  **Prerequisite:** The built-in catalog (`hosted_catalog = true`) requires RisingWave’s metastore backend to be **PostgreSQL or MySQL**. **SQLite is not supported** for internal Iceberg tables with the built-in catalog.

  If you use **Standalone mode**, RisingWave uses embedded SQLite for the metastore by default, so the built-in catalog is not supported by default. See [Standalone mode](/operate/rw-standalone-mode).
</Note>

## How it works (high level)

When you create an internal Iceberg table, there are two kinds of state involved:

* **Data files**: Stored in your object storage (S3 / GCS / Azure Blob / etc.).
* **Iceberg metadata**: Managed by an **Iceberg catalog** — a metadata service that tracks the table schema, snapshots, and data file locations. In this guide, the “catalog” is RisingWave’s **built-in catalog** (`hosted_catalog = true`), and the metadata is stored in RisingWave’s configured metastore database (PostgreSQL or MySQL).

With the **built-in catalog**, you set `hosted_catalog = true` in an Iceberg `CONNECTION`, and RisingWave manages the Iceberg metadata in its own metastore.

Because the built-in catalog is JDBC-compliant, external engines like Spark or Trino can connect to it and query the same Iceberg tables (using the same catalog endpoint and the same object storage).

## Create and test an internal Iceberg table

### Step 1: Create an Iceberg connection (built-in catalog)

<Note>
  A `CONNECTION` is simply a **saved config profile** in RisingWave.

  You create it once with `CREATE CONNECTION ...`, and then reuse it by name — either for the current session (`SET iceberg_engine_connection = 'schema.connection_name'`) or globally for all sessions (`ALTER SYSTEM SET iceberg_engine_connection = 'schema.connection_name'`).
</Note>

An Iceberg `CONNECTION` stores two things in one place:

* Object storage settings (for the data files), such as `warehouse.path` and `s3.*`.
* Catalog settings (for metadata). For the built-in catalog, this is `hosted_catalog = true`.

Example (AWS S3):

```sql theme={null}
CREATE CONNECTION built_in_catalog_conn WITH (
    type = 'iceberg',
    warehouse.path = 's3://my-bucket/warehouse/',
    s3.region = 'us-west-2',
    s3.access.key = 'your-key',
    s3.secret.key = 'your-secret',
    hosted_catalog = true
);
```

For details on configuring other storage backends, see [Object storage configuration](/iceberg/object-storage).

### Step 2: Set the connection and create a table

When you create `ENGINE = iceberg` tables, RisingWave needs to know **which Iceberg `CONNECTION` to use**. Set the connection before creating the table — either for the current session or globally for all sessions.

The connection name format is `schema_name.connection_name` (for example, `public.built_in_catalog_conn`).

```sql theme={null}
-- Set the connection for the current session only
SET iceberg_engine_connection = 'public.built_in_catalog_conn';

-- Or set it globally for all sessions
ALTER SYSTEM SET iceberg_engine_connection = 'public.built_in_catalog_conn';
```

Then create the table:

```sql theme={null}
-- Create an internal Iceberg table
CREATE TABLE my_iceberg_table (
    id INT PRIMARY KEY,
    name VARCHAR
) ENGINE = iceberg;

-- Insert data.
-- Note: For `ENGINE = iceberg`, data becomes visible only after an Iceberg commit.
-- By default, Iceberg commits about every 60 seconds.
INSERT INTO my_iceberg_table VALUES (1, 'alice'), (2, 'bob');
-- Wait about 60 seconds, then query:
SELECT * FROM my_iceberg_table;
```

<Card title="Complete Guide: Create and manage internal Iceberg tables" href="/iceberg/internal-iceberg-tables#create-an-internal-iceberg-table">
  For more details (partitioning, maintenance, external access, limitations), see this topic.
</Card>