Create catalogs

This article shows how to create catalogs in Unity Catalog. A catalog contains schemas (databases), and a schema contains tables, views, volumes, models, and functions.

To learn more about catalogs, see What are catalogs in Databricks?.

Note

To learn how to create a foreign catalog, a Unity Catalog object that mirrors a database in an external data system, see Create a foreign catalog. See also Manage and work with foreign catalogs.

Requirements

To create a catalog, regardless of catalog type:

You must be a Databricks metastore admin or have the CREATE CATALOG privilege on the metastore.
The compute resource that you use to run a notebook to create a catalog must be on Databricks Runtime 11.3 or above and must use a Unity Catalog-compliant access mode. See Access modes. SQL warehouses always support Unity Catalog.

To create a shared catalog:

The Delta Sharing share must already exist in your workspace. See How do I make shared data available to my team?.
You must be a metastore admin, have the USE PROVIDER privilege on the metastore, or own the provider object that includes the share.

To create a standard catalog:

If you specify a managed storage location for the catalog, you must have the CREATE MANAGED STORAGE privilege on the target external location.
If no metastore-level managed storage exists, then you must specify a managed storage location for the catalog.

To create a foreign catalog:

You must be either the owner of the connection that you use to create the foreign catalog or have the CREATE FOREIGN CATALOG privilege on the connection.
You must use compute on Databricks Runtime 13.1 or above. SQL warehouses must be Pro or Serverless.

Create a catalog

To create a catalog, you can use Catalog Explorer, a SQL command, the REST API, the Databricks CLI, or Terraform. When you create a catalog, two schemas (databases) are automatically created: default and information_schema.

You can use Catalog Explorer to update the owner, tags, comments, workspace bindings, and permissions any time after you have created the catalog.

To create a standard catalog, run the following SQL command in a notebook or SQL query editor. Items in brackets are optional. Replace the placeholder values:

<catalog-name>: A name for the catalog.
<location-path>: Optional but strongly recommended. Provide a storage location path if you want managed tables in this catalog to be stored in a location that is different than the default root storage configured for the metastore.

Important

If your workspace does not have a metastore-level storage location, you must specify a managed storage location when you create a catalog.

This path must be defined in an external location configuration, and you must have the CREATE MANAGED STORAGE privilege on the external location configuration. You can use the path that is defined in the external location configuration or a subpath (in other words, 's3://depts/finance' or 's3://depts/finance/product').
<comment>: Optional description or other comment.

CREATE CATALOG [ IF NOT EXISTS ] <catalog-name>
   [ MANAGED LOCATION '<location-path>' ]
   [ COMMENT <comment> ];

For example, to create a catalog named example:

CREATE CATALOG IF NOT EXISTS example;

To create a shared catalog, run the following command in a notebook or SQL query editor. Items in brackets are optional.

CREATE CATALOG [IF NOT EXISTS] <catalog-name>
USING SHARE <provider-name>.<share-name>;
[ COMMENT <comment> ];

To create a foreign catalog, run the following command in a notebook or SQL query editor. Items in brackets are optional. Replace the placeholder values:

<catalog-name>: Name for the catalog in Databricks.
<connection-name>: The connection object that specifies the data source, path, and access credentials.
<database-name>: Name of the database you want to mirror as a catalog in Databricks. Not required for MySQL, which uses a two-layer namespace. For Databricks-to-Databricks Lakehouse Federation, use catalog '<external-catalog-name>' instead.
<external-catalog-name>: Databricks-to-Databricks only: Name of the catalog in the external Databricks workspace that you are mirroring. See Run federated queries on another Databricks workspace.

CREATE FOREIGN CATALOG [IF NOT EXISTS] <catalog-name> USING CONNECTION <connection-name>
OPTIONS [(database '<database-name>') | (catalog '<external-catalog-name>')];

Create catalogs

Requirements

Create a catalog

More information