Criar e gerenciar catálogos

Este artigo mostra como criar e gerenciar catálogos no Unity Catalog. Um catálogo contém esquemas (bancos de dados) e um esquema contém tabelas, view, volumes, modelos e funções.

Observação

Em alguns workspace que foram habilitados automaticamente para Unity Catalog , um catálogoworkspace foi criado para você por default. Se este catálogo existir, todos os usuários no seu workspace (e apenas o seu workspace) terão acesso a ele por default. Consulte a etapa 1: Confirme se seu workspace está habilitado para o Unity Catalog.

Observação

Para saber como criar um catálogo externo, um objeto Unity Catalog que espelha um banco de dados em um sistema de dados externo, consulte Criar um catálogo externo. Veja também gerenciar e trabalhar com catálogos estrangeiros.

Requisitos

Para criar um catálogo:

Você deve ser um administrador do metastore do Databricks ou ter o privilégio CREATE CATALOG no metastore.
Você deve ter um metastore do Unity Catalog vinculado ao workspace onde você executa a criação do catálogo.
Os clusters que você usa para executar um Notebook para criar um catálogo devem usar um modo de acesso compatível com o Unity Catalog. Consulte Modos de acesso.

SQL warehouse sempre oferece suporte ao Unity Catalog.

Criar um catálogo

Para criar um catálogo, você pode usar o Catalog Explorer ou um comando SQL.

Efetue login em um workspace vinculado ao metastore.
Clique Catálogo.
Clique no botão Criar Catálogo .
Selecione o tipo de catálogo que deseja criar:
- Catálogo padrão : um objeto segurável que organiza os dados ativos que são gerenciados pelo Unity Catalog. Para todos os casos de uso, exceto lakehouse Federation.
- Catálogo externo : um objeto protegível no Unity Catalog que espelha um banco de dados em um sistema de dados externo usando lakehouse Federation. Consulte Visão geral da configuração da Federação lakehouse .
(Opcional, mas altamente recomendado) Especifique um local de armazenamento para gerenciar. Requer o privilégio CREATE MANAGED STORAGE no local externo de destino. Consulte Especificar um local de armazenamento de gerenciamento no Catálogo do Unity.

Importante

Se o seu workspace não tiver um local de armazenamento em nível de metastore, você deverá especificar um local de armazenamento para gerenciar ao criar um catálogo.
Clique em Criar.
(Opcional) Especifique o workspace ao qual o catálogo está vinculado.

Por default, o catálogo é compartilhado com todos os workspace anexados ao metastore atual. Se o catálogo contiver dados que devem ser restritos a workspace específico, vá para atab workspace e adicione esses workspace.

Para obter mais informações, consulte (Opcional) Atribuir um catálogo a um workspaceespecífico.
Atribua permissões para seu catálogo. Consulte Privilégios do Unity Catalog e objetos protegíveis.

execução do seguinte comando SQL em um editor SQL Notebook ou Databricks SQL . Os itens entre colchetes são opcionais. Substitua os valores de espaço reservado:
- <catalog-name>: Um nome para o catálogo.
- <location-path>: Opcional, mas fortemente recomendado. Forneça um caminho de local de armazenamento se desejar que as tabelas de gerenciamento neste catálogo sejam armazenadas em um local diferente do armazenamento raiz default configurado para o metastore.
  
  Importante
  
  Se o seu workspace não tiver um local de armazenamento em nível de metastore, você deverá especificar um local de armazenamento para gerenciar ao criar um catálogo.
  
  Esse caminho deve ser definido em uma configuração de local externo e você deve ter o privilégio CREATE MANAGED STORAGE na configuração de local externo. Você pode usar o caminho definido na configuração do local externo ou um subcaminho (em outras palavras, 's3://depts/finance' ou 's3://depts/finance/product'). Requer Databricks Runtime 11.3 e acima.
- <comment>: Descrição opcional ou outro comentário.
Observação

Se você estiver criando um catálogo externo (um objeto protegível no Unity Catalog que espelha um banco de dados em um sistema de dados externo, usado para a Federação lakehouse ), o comando SQL será CREATE FOREIGN CATALOG e as opções serão diferentes. Consulte Criar um catálogo externo.
```
CREATE CATALOG [ IF NOT EXISTS ] <catalog-name>
   [ MANAGED LOCATION '<location-path>' ]
   [ COMMENT <comment> ];
```
Por exemplo, para criar um catálogo chamado example:
```
CREATE CATALOG IF NOT EXISTS example;
```
Se você quiser limitar o acesso ao catálogo a workspace específico em sua account, também conhecido como ligação workspace-catalog, consulte Vincular um catálogo a um ou mais workspace.

Para obter descrições de parâmetros, consulte CREATE CATALOG.
Atribua privilégios ao catálogo. Consulte Privilégios do Unity Catalog e objetos protegíveis.

Quando você cria um catálogo, dois esquemas (bancos de dados) são criados automaticamente: default e information_schema.

Você também pode criar um catálogo usando o provedor Databricks Terraform e databricks_catalog. Você pode recuperar informações sobre catálogos usando databricks_catalogs.

(Opcional) Atribua um catálogo a espaços de trabalho específicos

Se você usar workspace para isolar o acesso aos dados do usuário, convém limitar o acesso ao catálogo a workspace específico em sua account, também conhecido como associação de catálogo workspace . O default é compartilhar o catálogo com todos workspace anexados ao metastore atual.

A exceção a esse default é o catálogoworkspace criado por default no workspace habilitado automaticamente para Unity Catalog (consulte Ativação automática do Unity Catalog). Por default, esse catálogo workspace está vinculado apenas ao seu workspace, a menos que você opte por conceder acesso a ele a outro workspace . Para obter informações importantes sobre a atribuição de permissões se você desvincular este catálogo, consulte Desvincular um catálogo de um workspace.

Você pode permitir acesso de leitura e gravação ao catálogo a partir de um workspace (o default) ou pode especificar acesso somente leitura. Se você especificar somente leitura, todas as operações de gravação serão bloqueadas desse workspace para esse catálogo.

Os casos de uso típicos para vincular um catálogo a um workspace específico incluem:

Garantir que os usuários possam acessar apenas os dados de produção de um ambiente workspace de produção.
Garantir que os usuários só possam processar dados confidenciais de um workspace dedicado.
Fornecer aos usuários acesso somente leitura aos dados de produção de um workspace do desenvolvedor para permitir o desenvolvimento e os testes.

Exemplo de ligação de catálogo de espaço de trabalho

Tomemos o exemplo do isolamento de produção e desenvolvimento. Se você especificar que seu catálogo de dados de produção só pode ser acessado a partir workspace de produção, isso substitui quaisquer concessões individuais que são emitidas para os usuários.

Catálogo - diagrama de encadernaçãoworkspace

Neste diagrama, prod_catalog está vinculado a dois workspace de produção. Suponha que um usuário tenha acesso concedido a uma tabela em prod_catalog chamada my_table (usando GRANT SELECT ON my_table TO <user>). Se o usuário tentar acessar my_table no workspace Dev, receberá uma mensagem de erro. O usuário pode acessar my_table apenas a partir do workspace analítico Prod ETL e Prod.

workspace-catalog bindings são respeitados em todas as áreas da plataforma. Por exemplo, se você query o esquema de informações, verá apenas os catálogos acessíveis no workspace onde você emite a query. Da mesma forma, a linhagem de dados e as UIs de pesquisa mostram apenas os catálogos atribuídos ao workspace (seja usando associações ou por default).

Vincular um catálogo a um ou mais workspace

Para atribuir um catálogo a workspace específico, você pode usar o Catalog Explorer ou a API REST Unity Catalog :

Permissões necessárias: administrador do metastore ou proprietário do catálogo.

Observação

Os administradores do metastore podem ver todos os catálogos em um metastore usando o Catalog Explorer — e os proprietários de catálogos podem ver todos os catálogos que possuem em um metastore — independentemente de o catálogo estar atribuído ao workspace atual. Os catálogos que não estão atribuídos ao workspace aparecem esmaecidos e nenhum objeto filho fica visível ou consultável.

Efetue login em um workspace vinculado ao metastore.
Clique Catálogo.
No painel Catálogo , à esquerda, clique no nome do catálogo.

O painel principal do Catalog Explorer default para a lista Catálogos . Você também pode selecionar o catálogo lá.
Na tab Espaços de trabalho , desmarque a caixa de seleção Todos os espaços de trabalho têm acesso .

Se o seu catálogo já estiver vinculado a um ou mais workspace, esta caixa de seleção já estará desmarcada.
Clique em Atribuir ao workspace e insira ou encontre o workspace que deseja atribuir.
(Opcional) Limite o acesso workspace para somente leitura.

No menu de gerenciamento de nível de acesso , selecione Alterar acesso para somente leitura.

Você pode reverter essa seleção a qualquer momento editando o catálogo e selecionando Alterar acesso para leitura e gravação.

Para revogar o acesso, vá paraa tab workspace , selecione a workspace e clique em Revogar .

Existem duas APIs e dois passos necessários para atribuir um catálogo a um workspace. Nos exemplos a seguir, substitua <workspace-url> pelo nome da instância do seu workspace . Para saber como obter o nome da instância e o ID do espaço de trabalho, consulte Obter identificadores para objetos de espaço de trabalho. Para saber mais sobre como obter access token, consulte Visão geral da autenticação para automação do Databricks.

Use a API catalogs para definir o isolation mode do catálogo como ISOLATED:

curl -L -X PATCH 'https://<workspace-url>/api/2.1/unity-catalog/catalogs/<my-catalog> \
-H 'Authorization: Bearer <my-token> \
-H 'Content-Type: application/json' \
--data-raw '{
 "isolation_mode": "ISOLATED"
 }'

O isolation mode default é OPEN para todos os workspace anexados ao metastore.

Use a API de atualização bindings para atribuir o workspace ao catálogo:

curl -L -X PATCH 'https://<workspace-url>/api/2.1/unity-catalog/bindings/catalog/<my-catalog> \
-H 'Authorization: Bearer <my-token> \
-H 'Content-Type: application/json' \
--data-raw '{
  "add": [{"workspace_id": <workspace-id>, "binding_type": <binding-type>}...],
  "remove": [{"workspace_id": <workspace-id>, "binding_type": "<binding-type>}...]
}'

Use as propriedades "add" e "remove" para adicionar ou remover vinculações workspace . <binding-type> pode ser “BINDING_TYPE_READ_WRITE” (default) ou “BINDING_TYPE_READ_ONLY”.

Para listar todas as atribuições workspace de um catálogo, use a API list bindings:

   curl -L -X GET 'https://<workspace-url>/api/2.1/unity-catalog/bindings/catalog/<my-catalog> \
   -H 'Authorization: Bearer <my-token> \

Desvincular um catálogo de um espaço de trabalho

Para revogar o acesso de um workspacea um catálogo, você pode usar o Catalog Explorer ou a API workspace bindings.

Importante

Se o seu workspace tiver sido ativado automaticamente para Unity Catalog e você tiver um catálogoworkspace , os administradores workspace serão proprietários desse catálogo e terão todas as permissões nesse catálogo somente no workspace . Se você desvincular esse catálogo ou vinculá-lo a outros catálogos, deverá conceder quaisquer permissões necessárias manualmente aos membros do grupo de administradores do workspace como usuários individuais ou usando grupos no nível account , porque o grupo de administradores workspace é um grupo local workspace . Para obter mais informações sobre grupos de contas versus grupos locais de espaço de trabalho, consulte Diferença entre grupos de contas e grupos locais de espaço de trabalho.

Permissões necessárias: Proprietário do catálogo.

Efetue login em um workspace vinculado ao metastore.
Clique Catálogo.
No painel Catálogo , à esquerda, clique no nome do catálogo.
Na workspacetab,workspace selecione o e clique em Revogar .

Para conceder acesso ao catálogo de todo o workspace anexado ao metastore Unity Catalog , selecione Todos os workspace têm acesso.

Para usar a API workspace-bindings para desvincular um espaço de trabalho de um catálogo, execute o seguinte. Substitua <workspace-url> pelo nome da instância do seu workspace . Para saber como obter o nome da instância e o ID do espaço de trabalho, consulte Obter identificadores para objetos de espaço de trabalho. Para saber mais sobre como obter access token, consulte Visão geral da autenticação para automação do Databricks.

curl -L -X PATCH 'https://<workspace-url>/api/2.1/unity-catalog/workspace-bindings/catalogs/<my-catalog> \
-H 'Authorization: Bearer <my-token> \
-H 'Content-Type: application/json' \
--data-raw '{
  "unassign_workspaces": [<workspace-id>, <workspace-id2>]
}'

Adicione esquemas ao seu catálogo

Para saber como adicionar esquemas (bancos de dados) ao seu catálogo. consulte Criar e gerenciar esquemas (bancos de dados).

Ver detalhes do catálogo

Para view informações sobre um catálogo, você pode usar o Catalog Explorer ou um comando SQL.

Efetue login em um workspace vinculado ao metastore.
Clique Catálogo.
No painel Catálogo , encontre o catálogo e clique em seu nome.

Alguns detalhes estão listados no topo da página. Outros podem ser view nas guias Esquemas, Detalhes , Permissões etab workspace .

execução do seguinte comando SQL em um editor SQL Notebook ou Databricks SQL . Os itens entre colchetes são opcionais. Substitua o espaço reservado <catalog-name>.

Para obter detalhes, consulte DESCREVA O CATÁLOGO.

DESCRIBE CATALOG <catalog-name>;

Use CATALOG EXTENDED para obter detalhes completos.

Excluir um catálogo

Para excluir (ou descartar) um catálogo, você pode usar o Catalog Explorer ou um comando SQL. Para descartar um catálogo você deve ser seu proprietário.

Você deve excluir todos os esquemas no catálogo, exceto information_schema antes de poder excluir um catálogo. Isso inclui o esquema default criado automaticamente.

Efetue login em um workspace vinculado ao metastore.
Clique Catálogo.
No painel Catálogo , à esquerda, clique no catálogo que deseja excluir.
No painel de detalhes, clique no menu de três pontos à esquerda do botão Criar banco de dados e selecione Excluir.
Na caixa de diálogo Excluir catálogo , clique em Excluir.

execução do seguinte comando SQL em um editor SQL Notebook ou Databricks SQL . Os itens entre colchetes são opcionais. Substitua o espaço reservado <catalog-name>.

Para obter descrições de parâmetros, consulte DROP CATALOG.

Se você usar DROP CATALOG sem a opção CASCADE , deverá excluir todos os esquemas do catálogo, exceto information_schema antes de poder excluir o catálogo. Isso inclui o esquema default criado automaticamente.

DROP CATALOG [ IF EXISTS ] <catalog-name> [ RESTRICT | CASCADE ]

Por exemplo, para excluir um catálogo chamado vaccine e seus esquemas:

DROP CATALOG vaccine CASCADE

gerenciando o catálogo padrão

Um catálogo default é configurado para cada workspace habilitado para o Unity Catalog. O catálogo default permite executar operações de dados sem especificar um catálogo. Se você omitir o nome do catálogo de nível superior ao executar operações de dados, o catálogo default será assumido.

Um administrador workspace pode view ou alternar o catálogo default usando a IU de configurações de administrador. Você também pode definir o catálogo default para clusters usando uma configuração do Spark.

comandos que não especificam o catálogo (por exemplo GRANT CREATE TABLE ON SCHEMA myschema TO mygroup) são avaliados para o catálogo na seguinte ordem:

O catálogo está definido para a sessão usando uma instrução USE CATALOG ou uma configuração JDBC?
A configuração do Spark spark.databricks.sql.initial.catalog.namespace está definida nos clusters?
Existe um workspace default catálogo definido para os clusters?

A configuração de catálogo padrão quando o Unity Catalog está habilitado

O catálogo default que foi inicialmente configurado para seu workspace depende de como seu workspace foi habilitado para o Unity Catalog:

Para alguns workspace que foram habilitados automaticamente para Unity Catalog , o catálogoworkspace foi definido como o catálogo default . Consulte Ativação automática do Unity Catalog.
Para todos os outros workspace, o catálogo hive_metastore foi definido como catálogo default .

Se você estiver fazendo a transição do Hive metastore para Unity Catalog em um workspace existente, normalmente faz sentido usar hive_metastore como o catálogo default para evitar impactar o código existente que faz referência ao Hive metastore.

Alterar o catálogo padrão

Um administrador workspace pode alterar o catálogo default do workspace. Qualquer pessoa com permissão para criar ou editar clusters pode definir um catálogo default diferente para os clusters.

Aviso

Alterar o catálogo padrão pode causar problemas nas operações de dados existentes que dependem dele.

Para configurar um catálogo default diferente para um workspace:

log in em seu workspace como administrador workspace .
Clique no seu nome de usuário na barra superior do site workspace e selecione Settings (Configurações ) no site dropdown.
Clique na Avançado tab.
No catálogodefault da linha workspace , insira o nome do catálogo e clique em Salvar.

Reinicie seu SQL warehouse e clusters para que a mudança entre em vigor. Todos os clusters e SQL warehouse novos e reiniciados usarão este catálogo como o workspace default.

Você também pode substituir o catálogo default para clusters específicos definindo a seguinte configuração do Spark nos clusters. Esta abordagem não está disponível para SQL warehouse:

spark.databricks.sql.initial.catalog.name

Para obter instruções, consulte Configuração do Spark.

Veja o catálogo padrão atual

Para obter o default catálogo atual para seu workspace, você pode usar uma instrução SQL em uma Notebook ou do Editor query SQL. Um administrador do workspace pode obter o catálogo default usando a UI de configurações de administrador.

log in em seu workspace como administrador workspace .
Clique no seu nome de usuário na barra superior do site workspace e selecione Settings (Configurações ) no site dropdown.
Clique na Avançado tab.
No catálogodefault da linha do workspace , view o nome do catálogo.

Execute o comando a seguir em uma Notebook do ou do Editor SQL query que está em execução em um SQL warehouse ou compatíveis com o Unity clusters Catalog. O workspace default catálogo é retornado desde que nenhuma USE CATALOG instrução ou configuração JDBC tenha sido definida na sessão e desde que nenhuma spark.databricks.sql.initial.catalog.namespace configuração esteja definida para os clusters.

SELECT current_catalog();