Databricks catalogs and schemas, explained.

Three levels, not two

Most relational databases give you two levels of grouping: a database, and schemas inside it. Databricks, under Unity Catalog, adds a level on top: a catalog. The full hierarchy is catalog, then schema, then table, and a fully qualified name looks like retail.gold.sales_by_product, catalog first. If you've worked mostly in Postgres or MySQL, this extra layer is the main adjustment.

What a catalog actually is

A catalog is the broadest container, often used to separate environments (dev, staging, prod) or major business domains (marketing, finance, product). Permissions can be granted at the catalog level, so a catalog is also a natural access boundary: a team might have full access to one catalog and none to another, regardless of what schemas exist inside either.

What a schema is

Inside a catalog, a schema (sometimes still called a database, the two terms are used interchangeably in Databricks) groups related tables. A common pattern is bronze, silver, gold schemas within one catalog, representing raw, cleaned, and business-ready layers of the same data. That's a convention, not a Databricks requirement, but it's common enough that you'll see it in most Unity Catalog setups.

A worked example

Say your company has a retail catalog with bronze, silver and gold schemas. A query against the business-ready layer looks like:

SELECT product_category, sum(revenue) AS total_revenue
FROM retail.gold.sales_by_product
WHERE sale_date >= current_date() - interval 30 days
GROUP BY product_category;

Swap gold for silver or bronze and you're querying an earlier stage of the same pipeline, in the same catalog, assuming your access allows it.

How this shows up in QueryFlow

The explorer in a Databricks connection follows this exact structure: catalogs at the top level, schemas inside each one, tables inside each schema. Set a default Catalog and Schema when you connect if you work mostly in one place, or leave them blank and browse the full structure. Autocomplete in the SQL editor understands the three-level naming too, so typing a catalog name narrows suggestions to its schemas, and a schema name narrows to its tables.

Where it matters beyond querying

When you set up a Databricks connection as a Data Sync target, the target table you pick still follows catalog.schema.table, and permissions are still checked at whichever level your service principal or token has been granted. If a sync fails with an access error, the catalog or schema level, not just the table, is usually where to look first.

A quick way to check what you can see

Running a metadata query against the information schema is often faster than clicking through the explorer level by level when you're not sure what you have access to:

SELECT table_catalog, table_schema, count(*) AS tables
FROM system.information_schema.tables
GROUP BY table_catalog, table_schema
ORDER BY table_catalog, table_schema;

That one query gives you the whole shape of what your token or service principal can see, catalog and schema together, without browsing the tree manually.

A note on naming conventions

Bronze, silver, gold is common but not universal, some teams use raw, staging, curated instead, or something specific to their own domain. There's no Databricks enforcement of any particular scheme, so when you join a new team, a quick look at the schema names in a catalog usually tells you which convention, if any, they've settled on.