`w.metastores`: Metastores¶

class databricks.sdk.service.catalog.MetastoresAPI¶

A metastore is the top-level container of objects in Unity Catalog. It stores data assets (tables and views) and the permissions that govern access to them. Databricks account admins can create metastores and assign them to Databricks workspaces to control which workloads use each metastore. For a workspace to use Unity Catalog, it must have a Unity Catalog metastore attached.

Each metastore is configured with a root storage location in a cloud storage account. This storage location is used for metadata and managed tables data.

NOTE: This metastore is distinct from the metastore included in Databricks workspaces created before Unity Catalog was released. If your workspace includes a legacy Hive metastore, the data in that metastore is available in a catalog named hive_metastore.

assign(workspace_id: int, metastore_id: str, default_catalog_name: str)¶

Usage:

import os
import time

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

workspace_id = os.environ["DUMMY_WORKSPACE_ID"]

created = w.metastores.create(
    name=f"sdk-{time.time_ns()}",
    storage_root="s3://%s/%s" % (os.environ["TEST_BUCKET"], f"sdk-{time.time_ns()}"),
)

w.metastores.assign(metastore_id=created.metastore_id, workspace_id=workspace_id)

# cleanup
w.metastores.delete(id=created.metastore_id, force=True)

Creates a new metastore assignment. If an assignment for the same __workspace_id__ exists, it will be overwritten by the new __metastore_id__ and __default_catalog_name__. The caller must be an account admin.

Parameters:

workspace_id – int A workspace ID.
metastore_id – str The unique ID of the metastore.
default_catalog_name – str The name of the default catalog in the metastore. This field is deprecated. Please use “Default Namespace API” to configure the default catalog for a Databricks workspace.

create(name: str [, external_access_enabled: Optional[bool], region: Optional[str], storage_root: Optional[str]]) → MetastoreInfo¶

Usage:

import os
import time

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

created = w.metastores.create(
    name=f"sdk-{time.time_ns()}",
    storage_root="s3://%s/%s" % (os.environ["TEST_BUCKET"], f"sdk-{time.time_ns()}"),
)

# cleanup
w.metastores.delete(id=created.metastore_id, force=True)

Creates a new metastore based on a provided name and optional storage root path. By default (if the __owner__ field is not set), the owner of the new metastore is the user calling the __createMetastore__ API. If the __owner__ field is set to the empty string (“”), the ownership is assigned to the System User instead.

Parameters:

name – str The user-specified name of the metastore.
external_access_enabled – bool (optional) Whether to allow non-DBR clients to directly access entities under the metastore.
region – str (optional) Cloud region which the metastore serves (e.g., us-west-2, westus).
storage_root – str (optional) The storage root URL for metastore

Returns:

MetastoreInfo

current() → MetastoreAssignment¶

Usage:

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

current_metastore = w.metastores.current()

Gets the metastore assignment for the workspace being accessed.

Returns:: MetastoreAssignment

delete(id: str [, force: Optional[bool]])¶

Deletes a metastore. The caller must be a metastore admin.

Parameters:

id – str Unique ID of the metastore.
force – bool (optional) Force deletion even if the metastore is not empty. Default is false.

get(id: str) → MetastoreInfo¶

Usage:

import os
import time

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

created = w.metastores.create(
    name=f"sdk-{time.time_ns()}",
    storage_root="s3://%s/%s" % (os.environ["TEST_BUCKET"], f"sdk-{time.time_ns()}"),
)

_ = w.metastores.get(id=created.metastore_id)

# cleanup
w.metastores.delete(id=created.metastore_id, force=True)

Gets a metastore that matches the supplied ID. The caller must be a metastore admin to retrieve this info.

Parameters:: id – str Unique ID of the metastore.
Returns:: MetastoreInfo

list([, max_results: Optional[int], page_token: Optional[str]]) → Iterator[MetastoreInfo]¶

Usage:

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

all = w.metastores.list()

Gets an array of the available metastores (as __MetastoreInfo__ objects). The caller must be an admin to retrieve this info. There is no guarantee of a specific ordering of the elements in the array.

NOTE: we recommend using max_results=0 to use the paginated version of this API. Unpaginated calls will be deprecated soon.

PAGINATION BEHAVIOR: When using pagination (max_results >= 0), a page may contain zero results while still providing a next_page_token. Clients must continue reading pages until next_page_token is absent, which is the only indication that the end of results has been reached.

Parameters:

max_results – int (optional) Maximum number of metastores to return. - 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 0, the page length is set to a server configured value (recommended); - when set to a value less than 0, an invalid parameter error is returned; - If not set, all the metastores are returned (not recommended). - Note: The number of returned metastores might be less than the specified max_results size, even zero. The only definitive indication that no further metastores can be fetched is when the next_page_token is unset from the response.
page_token – str (optional) Opaque pagination token to go to next page based on previous query.

Returns:

Iterator over MetastoreInfo

summary() → GetMetastoreSummaryResponse¶

Usage:

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

summary = w.metastores.summary()

Gets information about a metastore. This summary includes the storage credential, the cloud vendor, the cloud region, and the global metastore ID.

Returns:: GetMetastoreSummaryResponse

unassign(workspace_id: int, metastore_id: str)¶

Usage:

import os
import time

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

workspace_id = os.environ["DUMMY_WORKSPACE_ID"]

created = w.metastores.create(
    name=f"sdk-{time.time_ns()}",
    storage_root="s3://%s/%s" % (os.environ["TEST_BUCKET"], f"sdk-{time.time_ns()}"),
)

w.metastores.unassign(metastore_id=created.metastore_id, workspace_id=workspace_id)

# cleanup
w.metastores.delete(id=created.metastore_id, force=True)

Deletes a metastore assignment. The caller must be an account administrator.

Parameters:

workspace_id – int A workspace ID.
metastore_id – str Query for the ID of the metastore to delete.

update(id: str [, delta_sharing_organization_name: Optional[str], delta_sharing_recipient_token_lifetime_in_seconds: Optional[int], delta_sharing_scope: Optional[DeltaSharingScopeEnum], external_access_enabled: Optional[bool], new_name: Optional[str], owner: Optional[str], privilege_model_version: Optional[str], storage_root_credential_id: Optional[str]]) → MetastoreInfo¶

Usage:

import os
import time

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

created = w.metastores.create(
    name=f"sdk-{time.time_ns()}",
    storage_root="s3://%s/%s" % (os.environ["TEST_BUCKET"], f"sdk-{time.time_ns()}"),
)

_ = w.metastores.update(id=created.metastore_id, new_name=f"sdk-{time.time_ns()}")

# cleanup
w.metastores.delete(id=created.metastore_id, force=True)

Updates information for a specific metastore. The caller must be a metastore admin. If the __owner__ field is set to the empty string (“”), the ownership is updated to the System User.

Parameters:

id – str Unique ID of the metastore.
delta_sharing_organization_name – str (optional) The organization name of a Delta Sharing entity, to be used in Databricks-to-Databricks Delta Sharing as the official name.
delta_sharing_recipient_token_lifetime_in_seconds – int (optional) The lifetime of delta sharing recipient token in seconds.
delta_sharing_scope – DeltaSharingScopeEnum (optional) The scope of Delta Sharing enabled for the metastore.
external_access_enabled – bool (optional) Whether to allow non-DBR clients to directly access entities under the metastore.
new_name – str (optional) New name for the metastore.
owner – str (optional) The owner of the metastore.
privilege_model_version – str (optional) Privilege model version of the metastore, of the form major.minor (e.g., 1.0).
storage_root_credential_id – str (optional) UUID of storage credential to access the metastore storage_root.

Returns:

MetastoreInfo

update_assignment(workspace_id: int [, default_catalog_name: Optional[str], metastore_id: Optional[str]])¶

Updates a metastore assignment. This operation can be used to update __metastore_id__ or __default_catalog_name__ for a specified Workspace, if the Workspace is already assigned a metastore. The caller must be an account admin to update __metastore_id__; otherwise, the caller can be a Workspace admin.

Parameters:

workspace_id – int A workspace ID.
default_catalog_name – str (optional) The name of the default catalog in the metastore. This field is deprecated. Please use “Default Namespace API” to configure the default catalog for a Databricks workspace.
metastore_id – str (optional) The unique ID of the metastore.

Navigation

Related Topics

`w.metastores`: Metastores¶

w.metastores: Metastores¶

`w.metastores`: Metastores¶