Catalogs

A catalog is one connected source. Its name is the first part of every table reference, and the middle part depends on the type — that difference is the single most common cause of "does not exist" errors, so it is worth learning once.

Addressing by type

For PostgreSQL and MySQL, the optional Schema field limits which schemas get introspected into the Tables page. Leave it empty for every user schema, or give a comma-separated list (shop, analytics) when one database holds more than one dataset you care about — useful when the host keeps its own schemas alongside yours. Queries can still address any schema the connecting role can read; this only controls what is catalogued. | BigQuery | catalog.dataset.table | the dataset | | ClickHouse | clickhouse_query('catalog', '<sql>') | not a table reference at all | | Iceberg on Glue | catalog.default.table | always the literal default | | S3 / GCS / Azure | read_csv('catalog/path/file.csv') | not a table reference at all |

Iceberg catalogs use a virtual default: the catalog owns one Glue database named after itself, and default stands in for it. Writing the Glue database name instead is an error.

ClickHouse is the other exception, and for a different reason: it is read over its HTTP interface, where nothing can push a filter down, so you send it the SQL to run rather than naming a table. See ClickHouse for why, with the numbers.

Object-storage catalogs have no tables to address. You read files by path, and the catalog name resolves to its bucket:

SELECT * FROM read_parquet('raw_files/events/2026/*.parquet');
SELECT * FROM read_csv('raw_files/exports/customers.csv');
SELECT * FROM read_xlsx('raw_files/finance/budget.xlsx');

Shared catalogs

A catalog can be shared, meaning every company on the platform sees it. The demo catalogs are shared, and shared catalogs are read-only for tenants unless explicitly configured otherwise.

Treat anything in a shared catalog as visible to everyone it is shared with.

When a name does not resolve

Errors of the form Catalog with name X does not exist or Schema with name X does not exist are almost always addressing, not missing data:

1. Check the catalog list — the name must match exactly.
2. Check the middle part against the table above. For Iceberg, it is default.
3. Use all three parts. Two-part names sometimes resolve, but only when unambiguous across your catalogs; don't rely on it.

Credentials

Connection details are validated when you create the catalog, then split: the secret half goes to AWS Secrets Manager, the rest to our database. No API, console page or AI tool ever returns the secret half. Deleting a catalog deletes its secret with it.

There is no in-place edit for credentials — to rotate them, delete the catalog and create it again with the same name.