catalogs

Creates, updates, deletes, gets or lists a catalogs resource.

Overview

Name	`catalogs`
Type	Resource
Id	`databricks_workspace.catalog.catalogs`

Fields

The following fields are returned by SELECT queries:

get
list

Name	Datatype	Description
`name`	`string`	Name of catalog.
`metastore_id`	`string`	Unique identifier of parent metastore.
`connection_name`	`string`	The name of the connection to an external data source.
`full_name`	`string`	The full name of the catalog. Corresponds with the name field.
`provider_name`	`string`	The name of delta sharing provider. A Delta Sharing catalog is a catalog that is based on a Delta share on a remote sharing server.
`share_name`	`string`	The name of the share under the share provider.
`browse_only`	`boolean`
▶`catalog_federation_config`	`object`	Federation-only configuration, present only for FOREIGN catalogs.
`catalog_type`	`string`	The type of the catalog. (DELTASHARING_CATALOG, FOREIGN_CATALOG, INTERNAL_CATALOG, MANAGED_CATALOG, MANAGED_ONLINE_CATALOG, SYSTEM_CATALOG)
`comment`	`string`	User-provided free-form text description.
▶`conversion_info`	`object`	Status of conversion of FOREIGN catalog to UC Native catalog.
`created_at`	`integer`	Time at which this catalog was created, in epoch milliseconds.
`created_by`	`string`	Username of catalog creator.
`custom_max_retention_hours`	`integer`	Custom maximum retention period in hours for the catalog
▶`dr_replication_info`	`object`	Disaster Recovery replication state snapshot.
▶`effective_predictive_optimization_flag`	`object`
`enable_predictive_optimization`	`string`	Create a collection of name/value pairs.<br /><br />Example enumeration:<br /><br />>>> class Color(Enum):<br />... RED = 1<br />... BLUE = 2<br />... GREEN = 3<br /><br />Access them by:<br /><br />- attribute access:<br /><br /> >>> Color.RED<br /> <Color.RED: 1><br /><br />- value lookup:<br /><br /> >>> Color(1)<br /> <Color.RED: 1><br /><br />- name lookup:<br /><br /> >>> Color['RED']<br /> <Color.RED: 1><br /><br />Enumerations can be iterated over, and know how many members they have:<br /><br />>>> len(Color)<br />3<br /><br />>>> list(Color)<br />[<Color.RED: 1>, <Color.BLUE: 2>, <Color.GREEN: 3>]<br /><br />Methods can be added to enumerations, and members can have their own<br />attributes -- see the documentation for details. (DISABLE, ENABLE, INHERIT)
`isolation_mode`	`string`	Whether the current securable is accessible from all workspaces or a specific set of workspaces. (ISOLATED, OPEN, OPEN_IN_ACCOUNT)
▶`managed_encryption_settings`	`object`	Control CMK encryption for managed catalog data
`options`	`object`	A map of key-value properties attached to the securable.
`owner`	`string`	Username of current owner of catalog.
`properties`	`object`	A map of key-value properties attached to the securable.
▶`provisioning_info`	`object`	Status of an asynchronously provisioned resource.
`securable_type`	`string`	The type of Unity Catalog securable. (CATALOG, CLEAN_ROOM, CONNECTION, CREDENTIAL, EXTERNAL_LOCATION, EXTERNAL_METADATA, FUNCTION, METASTORE, PIPELINE, PROVIDER, RECIPIENT, SCHEMA, SHARE, STAGING_TABLE, STORAGE_CREDENTIAL, TABLE, VOLUME)
`storage_location`	`string`	Storage Location URL (full path) for managed tables within catalog.
`storage_root`	`string`	Storage root URL for managed tables within catalog.
`updated_at`	`integer`	Time at which this catalog was last modified, in epoch milliseconds.
`updated_by`	`string`	Username of user who last modified catalog.

Name	Datatype	Description
`name`	`string`	Name of catalog.
`metastore_id`	`string`	Unique identifier of parent metastore.
`connection_name`	`string`	The name of the connection to an external data source.
`full_name`	`string`	The full name of the catalog. Corresponds with the name field.
`provider_name`	`string`	The name of delta sharing provider. A Delta Sharing catalog is a catalog that is based on a Delta share on a remote sharing server.
`share_name`	`string`	The name of the share under the share provider.
`browse_only`	`boolean`
▶`catalog_federation_config`	`object`	Federation-only configuration, present only for FOREIGN catalogs.
`catalog_type`	`string`	The type of the catalog. (DELTASHARING_CATALOG, FOREIGN_CATALOG, INTERNAL_CATALOG, MANAGED_CATALOG, MANAGED_ONLINE_CATALOG, SYSTEM_CATALOG)
`comment`	`string`	User-provided free-form text description.
▶`conversion_info`	`object`	Status of conversion of FOREIGN catalog to UC Native catalog.
`created_at`	`integer`	Time at which this catalog was created, in epoch milliseconds.
`created_by`	`string`	Username of catalog creator.
`custom_max_retention_hours`	`integer`	Custom maximum retention period in hours for the catalog
▶`dr_replication_info`	`object`	Disaster Recovery replication state snapshot.
▶`effective_predictive_optimization_flag`	`object`
`enable_predictive_optimization`	`string`	Create a collection of name/value pairs.<br /><br />Example enumeration:<br /><br />>>> class Color(Enum):<br />... RED = 1<br />... BLUE = 2<br />... GREEN = 3<br /><br />Access them by:<br /><br />- attribute access:<br /><br /> >>> Color.RED<br /> <Color.RED: 1><br /><br />- value lookup:<br /><br /> >>> Color(1)<br /> <Color.RED: 1><br /><br />- name lookup:<br /><br /> >>> Color['RED']<br /> <Color.RED: 1><br /><br />Enumerations can be iterated over, and know how many members they have:<br /><br />>>> len(Color)<br />3<br /><br />>>> list(Color)<br />[<Color.RED: 1>, <Color.BLUE: 2>, <Color.GREEN: 3>]<br /><br />Methods can be added to enumerations, and members can have their own<br />attributes -- see the documentation for details. (DISABLE, ENABLE, INHERIT)
`isolation_mode`	`string`	Whether the current securable is accessible from all workspaces or a specific set of workspaces. (ISOLATED, OPEN, OPEN_IN_ACCOUNT)
▶`managed_encryption_settings`	`object`	Control CMK encryption for managed catalog data
`options`	`object`	A map of key-value properties attached to the securable.
`owner`	`string`	Username of current owner of catalog.
`properties`	`object`	A map of key-value properties attached to the securable.
▶`provisioning_info`	`object`	Status of an asynchronously provisioned resource.
`securable_type`	`string`	The type of Unity Catalog securable. (CATALOG, CLEAN_ROOM, CONNECTION, CREDENTIAL, EXTERNAL_LOCATION, EXTERNAL_METADATA, FUNCTION, METASTORE, PIPELINE, PROVIDER, RECIPIENT, SCHEMA, SHARE, STAGING_TABLE, STORAGE_CREDENTIAL, TABLE, VOLUME)
`storage_location`	`string`	Storage Location URL (full path) for managed tables within catalog.
`storage_root`	`string`	Storage root URL for managed tables within catalog.
`updated_at`	`integer`	Time at which this catalog was last modified, in epoch milliseconds.
`updated_by`	`string`	Username of user who last modified catalog.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
`get`	`select`	`name`, `deployment_name`	`include_browse`	Gets the specified catalog in a metastore. The caller must be a metastore admin, the owner of the
`list`	`select`	`deployment_name`	`include_browse`, `include_unbound`, `max_results`, `page_token`	Gets an array of catalogs in the metastore. If the caller is the metastore admin, all catalogs will be
`create`	`insert`	`deployment_name`, `name`		Creates a new catalog instance in the parent metastore if the caller is a metastore admin or has the
`update`	`update`	`name`, `deployment_name`		Updates the catalog that matches the supplied name. The caller must be either the owner of the
`delete`	`delete`	`name`, `deployment_name`	`force`	Deletes the catalog that matches the supplied name. The caller must be a metastore admin or the owner

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
`deployment_name`	`string`	The Databricks Workspace Deployment Name (default: dbc-abcd0123-a1bc)
`name`	`string`	The name of the catalog.
`force`	`boolean`	Force deletion even if the catalog is not empty.
`include_browse`	`boolean`	Whether to include catalogs in the response for which the principal can only access selective metadata for
`include_unbound`	`boolean`	Whether to include catalogs not bound to the workspace. Effective only if the user has permission to update the catalog–workspace binding.
`max_results`	`integer`	Maximum number of catalogs to return. - when set to 0, the page length is set to a server configured value (recommended); - when set to a value greater than 0, the page length is the minimum of this value and a server configured value; - when set to a value less than 0, an invalid parameter error is returned; - If not set, all valid catalogs are returned (not recommended). - Note: The number of returned catalogs might be less than the specified max_results size, even zero. The only definitive indication that no further catalogs can be fetched is when the next_page_token is unset from the response.
`page_token`	`string`	Opaque pagination token to go to next page based on previous query.

`SELECT` examples

get
list

Gets the specified catalog in a metastore. The caller must be a metastore admin, the owner of the

SELECT
name,
metastore_id,
connection_name,
full_name,
provider_name,
share_name,
browse_only,
catalog_federation_config,
catalog_type,
comment,
conversion_info,
created_at,
created_by,
custom_max_retention_hours,
dr_replication_info,
effective_predictive_optimization_flag,
enable_predictive_optimization,
isolation_mode,
managed_encryption_settings,
options,
owner,
properties,
provisioning_info,
securable_type,
storage_location,
storage_root,
updated_at,
updated_by
FROM databricks_workspace.catalog.catalogs
WHERE name = '{{ name }}' -- required
AND deployment_name = '{{ deployment_name }}' -- required
AND include_browse = '{{ include_browse }}'
;

Gets an array of catalogs in the metastore. If the caller is the metastore admin, all catalogs will be

SELECT
name,
metastore_id,
connection_name,
full_name,
provider_name,
share_name,
browse_only,
catalog_federation_config,
catalog_type,
comment,
conversion_info,
created_at,
created_by,
custom_max_retention_hours,
dr_replication_info,
effective_predictive_optimization_flag,
enable_predictive_optimization,
isolation_mode,
managed_encryption_settings,
options,
owner,
properties,
provisioning_info,
securable_type,
storage_location,
storage_root,
updated_at,
updated_by
FROM databricks_workspace.catalog.catalogs
WHERE deployment_name = '{{ deployment_name }}' -- required
AND include_browse = '{{ include_browse }}'
AND include_unbound = '{{ include_unbound }}'
AND max_results = '{{ max_results }}'
AND page_token = '{{ page_token }}'
;

`INSERT` examples

create
Manifest

Creates a new catalog instance in the parent metastore if the caller is a metastore admin or has the

INSERT INTO databricks_workspace.catalog.catalogs (
name,
catalog_federation_config,
comment,
connection_name,
conversion_info,
custom_max_retention_hours,
dr_replication_info,
managed_encryption_settings,
options,
properties,
provider_name,
share_name,
storage_root,
deployment_name
)
SELECT 
'{{ name }}' /* required */,
'{{ catalog_federation_config }}',
'{{ comment }}',
'{{ connection_name }}',
'{{ conversion_info }}',
{{ custom_max_retention_hours }},
'{{ dr_replication_info }}',
'{{ managed_encryption_settings }}',
'{{ options }}',
'{{ properties }}',
'{{ provider_name }}',
'{{ share_name }}',
'{{ storage_root }}',
'{{ deployment_name }}'
RETURNING
name,
metastore_id,
connection_name,
full_name,
provider_name,
share_name,
browse_only,
catalog_federation_config,
catalog_type,
comment,
conversion_info,
created_at,
created_by,
custom_max_retention_hours,
dr_replication_info,
effective_predictive_optimization_flag,
enable_predictive_optimization,
isolation_mode,
managed_encryption_settings,
options,
owner,
properties,
provisioning_info,
securable_type,
storage_location,
storage_root,
updated_at,
updated_by
;

# Description fields are for documentation purposes
- name: catalogs
props:
  - name: deployment_name
    value: "{{ deployment_name }}"
    description: Required parameter for the catalogs resource.
  - name: name
    value: "{{ name }}"
    description: |
      Name of catalog.
  - name: catalog_federation_config
    description: |
      Federation-only configuration, present only for FOREIGN catalogs.
    value:
      schema_filter_type: "{{ schema_filter_type }}"
  - name: comment
    value: "{{ comment }}"
    description: |
      User-provided free-form text description.
  - name: connection_name
    value: "{{ connection_name }}"
    description: |
      The name of the connection to an external data source.
  - name: conversion_info
    description: |
      Status of conversion of FOREIGN catalog to UC Native catalog.
    value:
      state: "{{ state }}"
  - name: custom_max_retention_hours
    value: {{ custom_max_retention_hours }}
    description: |
      Custom maximum retention period in hours for the catalog
  - name: dr_replication_info
    description: |
      Disaster Recovery replication state snapshot.
    value:
      last_failover_time_ms: {{ last_failover_time_ms }}
      replicated_entities: "{{ replicated_entities }}"
      status: "{{ status }}"
  - name: managed_encryption_settings
    description: |
      Control CMK encryption for managed catalog data
    value:
      azure_encryption_settings:
        azure_tenant_id: "{{ azure_tenant_id }}"
        azure_cmk_access_connector_id: "{{ azure_cmk_access_connector_id }}"
        azure_cmk_managed_identity_id: "{{ azure_cmk_managed_identity_id }}"
      azure_key_vault_key_id: "{{ azure_key_vault_key_id }}"
      customer_managed_key_id: "{{ customer_managed_key_id }}"
  - name: options
    value: "{{ options }}"
    description: |
      A map of key-value properties attached to the securable.
  - name: properties
    value: "{{ properties }}"
    description: |
      A map of key-value properties attached to the securable.
  - name: provider_name
    value: "{{ provider_name }}"
    description: |
      The name of delta sharing provider. A Delta Sharing catalog is a catalog that is based on a Delta share on a remote sharing server.
  - name: share_name
    value: "{{ share_name }}"
    description: |
      The name of the share under the share provider.
  - name: storage_root
    value: "{{ storage_root }}"
    description: |
      Storage root URL for managed tables within catalog.

`UPDATE` examples

update

Updates the catalog that matches the supplied name. The caller must be either the owner of the

UPDATE databricks_workspace.catalog.catalogs
SET 
catalog_federation_config = '{{ catalog_federation_config }}',
comment = '{{ comment }}',
conversion_info = '{{ conversion_info }}',
custom_max_retention_hours = {{ custom_max_retention_hours }},
dr_replication_info = '{{ dr_replication_info }}',
enable_predictive_optimization = '{{ enable_predictive_optimization }}',
isolation_mode = '{{ isolation_mode }}',
managed_encryption_settings = '{{ managed_encryption_settings }}',
new_name = '{{ new_name }}',
options = '{{ options }}',
owner = '{{ owner }}',
properties = '{{ properties }}'
WHERE 
name = '{{ name }}' --required
AND deployment_name = '{{ deployment_name }}' --required
RETURNING
name,
metastore_id,
connection_name,
full_name,
provider_name,
share_name,
browse_only,
catalog_federation_config,
catalog_type,
comment,
conversion_info,
created_at,
created_by,
custom_max_retention_hours,
dr_replication_info,
effective_predictive_optimization_flag,
enable_predictive_optimization,
isolation_mode,
managed_encryption_settings,
options,
owner,
properties,
provisioning_info,
securable_type,
storage_location,
storage_root,
updated_at,
updated_by;

`DELETE` examples

delete

Deletes the catalog that matches the supplied name. The caller must be a metastore admin or the owner

DELETE FROM databricks_workspace.catalog.catalogs
WHERE name = '{{ name }}' --required
AND deployment_name = '{{ deployment_name }}' --required
AND force = '{{ force }}'
;

Overview​

Fields​

Methods​

Parameters​

SELECT examples​

INSERT examples​

UPDATE examples​

DELETE examples​