Criar e gerenciar compartilhamentos para o Compartilhamento Delta

Artigo
04/23/2024

Este artigo explica como criar e gerenciar compartilhamentos para o Compartilhamento Delta.

Um compartilhamento é um objeto protegível no Catálogo Unity que você pode usar para compartilhar os seguintes ativos de dados com um ou mais destinatários:

Tabelas e partições de tabelas
Exibições, incluindo exibições dinâmicas que restringem o acesso em nível de linha e coluna
Volumes
Notebooks
Modelos de IA

Se você compartilhar um esquema (banco de dados) inteiro, o destinatário poderá acessar todas as tabelas, exibições, modelos e volumes do esquema na mesma hora em que o esquema for compartilhado, juntamente com todos os ativos de dados e de IA que forem adicionados a ele no futuro.

Um compartilhamento pode conter ativos de dados e de IA de apenas um metastore do Catálogo do Unity. Você pode adicionar ou remover ativos de dados e de IA de um compartilhamento a qualquer momento.

Para saber mais, confira Compartilhamentos, provedores e destinatários.

Requisitos

Para criar um compartilhamento, você deve:

Ser um administrador do metastore ou ter o privilégio CREATE SHARE do metastore do Catálogo do Unity em que os dados que você deseja compartilhar estão registrados.
Criar o compartilhamento usando um workspace do Azure Databricks que tenha o metastore do Catálogo do Unity anexado.

Para adicionar tabelas ou exibições a um compartilhamento, você deve:

Ser o proprietário da ação.
Ter o privilégio USE CATALOG e USE SCHEMA no catálogo e esquema que contêm a tabela ou exibição, ou a propriedade do catálogo ou esquema.
Ter o privilégio SELECT na tabela ou exibição. Você deve manter esse privilégio para que a tabela ou exibição continue a ser compartilhada. Se você perdê-lo, o destinatário não poderá acessar a tabela ou exibir por meio do compartilhamento. O Databricks, portanto, recomenda usar um grupo como proprietário do compartilhamento.

Para adicionar volumes a um compartilhamento, você deve:

Ser o proprietário da ação.
Ter o privilégio USE CATALOG e USE SCHEMA no catálogo e no esquema que contêm o volume ou a propriedade do catálogo ou esquema.
Ter o privilégio READ VOLUME no volume. Você deve manter esse privilégio para que o volume continue a ser compartilhado. Se você perdê-lo, o destinatário não poderá acessar o volume por meio do compartilhamento. O Databricks, portanto, recomenda usar um grupo como proprietário do compartilhamento.

Para adicionar modelos a um compartilhamento, você precisa:

Ser o proprietário da ação.
Ter os privilégios USE CATALOG e USE SCHEMA no catálogo e no esquema que contêm o modelo, ou ser proprietário do catálogo ou esquema.
Ter o privilégio EXECUTE no modelo. Você precisa manter esse privilégio para que o modelo continue a ser compartilhado. Se você o perder, o destinatário não poderá acessar o modelo por meio do compartilhamento. O Databricks, portanto, recomenda usar um grupo como proprietário do compartilhamento.

Para compartilhar um esquema inteiro, você deve:

Ser o proprietário do compartilhamento e o proprietário do esquema, ou ter USE SCHEMA.
Ter SELECT no esquema para compartilhar tabelas.
Ter READ VOLUME no esquema para compartilhar volumes.

Para adicionar arquivos de notebook a um compartilhamento, você deve ser:

O proprietário do compartilhamento tem permissão CAN READ no notebook.

Para conceder acesso de destinatário a um compartilhamento, você deve ser um destes:

Administrador do metastore.
Usuário com permissões delegadas ou propriedade no compartilhamento e nos objetos de destinatário ((USE SHARE + SET SHARE PERMISSION) ou proprietário do compartilhamento) E (USE RECIPIENT ou proprietário do destinatário).

Para exibir compartilhamentos, você deve ser um destes:

Um administrador de metastore (pode exibir todos)
Um usuário com o privilégio USE SHARE (pode exibir todos)
O proprietário do objeto de compartilhamento

Requisitos de computação:

Se você usar um notebook do Databricks para criar o compartilhamento, o cluster deverá usar o Databricks Runtime 11.3 LTS ou superior e o modo de acesso de cluster compartilhado ou de usuário único.
Se você usar instruções SQL para adicionar um esquema a um compartilhamento (ou atualizar ou remover um esquema), deverá usar um SQL Warehouse ou computação executando o Databricks Runtime 13.3 LTS ou superior. Para fazer o mesmo usando o Explorador de catálogos, você não precisa de computação.

Para criar um compartilhamento, você pode usar o Explorador de catálogos, a CLI do Catálogo do Unity do Databricks ou o comando CREATE SHARE SQL em um Notebook do Azure Databricks ou o editor de consultas SQL do Databricks.

Permissões necessárias: administrador ou usuário do metastore com o privilégio CREATE SHARE do metastore.

Explorador do Catálogo

No espaço de trabalho do Azure Databricks, clique em Catálogo.
No painel esquerdo, expanda o menu Compartilhamento Delta e selecione Compartilhado por mim.
Clique em Compartilhar dados.
Insira o Nome do compartilhamento e um comentário opcional.

Sql

Execute o seguinte comando em um notebook ou no editor de consultas do Databricks SQL:

CREATE SHARE [IF NOT EXISTS] <share-name>
[COMMENT "<comment>"];

Cli

Execute o comando a seguir usando a CLI do Databricks.

databricks shares create <share-name>

Você pode usar --comment para adicionar um comentário ou --json para adicionar ativos ao compartilhamento. Para obter detalhes, confira as seções a seguir.

Para adicionar tabelas a um compartilhamento, você pode usar o Explorador de catálogos, a CLI do Catálogo do Unity do Databricks ou comandos SQL em um notebook do Azure Databricks ou o editor de consultas SQL do Databricks.

Permissões necessárias: proprietário do objeto USE CATALOG de compartilhamento e USE SCHEMA no catálogo e esquema que contêm a tabela e o privilégio SELECT na tabela. Você deve manter o privilégio SELECT enquanto quiser compartilhar a tabela. Para saber mais, confira Requisitos.

Observação

Se você for um administrador de workspace e herdou as permissões USE SCHEMA e USE CATALOG no esquema e no catálogo que contêm a tabela do grupo de administradores de workspace, não poderá adicionar a tabela a um compartilhamento. Você deve primeiro conceder a si mesmo as permissões USE SCHEMA e USE CATALOG no esquema e no catálogo.

Explorador do Catálogo

No espaço de trabalho do Azure Databricks, clique em Catálogo.
No painel esquerdo, expanda o menu Compartilhamento Delta e selecione Compartilhado por mim.
Na guia Compartilhamentos, localize o compartilhamento ao qual você deseja adicionar uma tabela e clique no nome dele.
Clique em Gerenciar ativos > Adicionar ativos de dados.
Na página Adicionar tabelas selecione um esquema inteiro (banco de dados) ou tabelas e exibições individuais.
- Para selecionar uma tabela ou modo de exibição, primeiro selecione o catálogo, depois o esquema que contém a tabela ou exibição e, em seguida, a própria tabela ou exibição.
  
  Você pode pesquisar tabelas por nome, nome de coluna ou comentário usando a pesquisa de espaço de trabalho. Consulte Pesquisar objetos do espaço de trabalho.
- Para selecionar um esquema, primeiro selecione o catálogo e, em seguida, o esquema.
  
  Para obter informações detalhadas sobre como compartilhar esquemas, consulte Adicionar esquemas a um compartilhamento.
(Opcional) Clique em Opções avançadas de tabela para especificar as seguintes opções. Alias e partições não estarão disponíveis se você selecionar um esquema inteiro. O histórico de tabelas será incluído por padrão se você selecionar um esquema inteiro.
- Alias: um nome de tabela alternativo para tornar o nome da tabela mais legível. O alias é o nome da tabela que o destinatário vê e deve usar nas consultas. Os destinatários não podem usar o nome da tabela real quando um alias foi especificado.
- Partição: compartilhe apenas parte da tabela. Por exemplo, (column = 'value'). Consulte Especificar partições de tabela para compartilhar e Usar propriedades de destinatário para fazer a filtragem de partição.
- Compartilhamento de Histórico: compartilhe o histórico da tabela para permitir que os destinatários executem consultas de viagem no tempo ou leiam a tabela com o Streaming Estruturado do Spark. Requer o Databricks Runtime 12.2 LTS ou superior.
  
  Observação
  
  Se, além de fazer consultas de viagem no tempo e leituras de streaming, você desejar que os clientes possam consultar o CDF (feed de dados de alterações) de uma tabela usando a função table_changes(), habilite o CDF na tabela antes de compartilhá-lo WITH HISTORY.
Clique em Save (Salvar).

Sql

Execute o seguinte comando em um bloco de anotações ou no editor de consultas SQL do Databricks para adicionar uma tabela:

ALTER SHARE <share-name> ADD TABLE <catalog-name>.<schema-name>.<table-name>  [COMMENT "<comment>"]
   [PARTITION(<clause>)] [AS <alias>]
   [WITH HISTORY | WITHOUT HISTORY];

Execute o seguinte para adicionar um esquema inteiro. O comando ADD SCHEMA requer um SQL warehouse ou computação executando o Databricks Runtime 13.3 LTS ou superior. Para obter informações detalhadas sobre como compartilhar esquemas, consulte Adicionar esquemas a um compartilhamento.

ALTER SHARE <share-name> ADD SCHEMA <catalog-name>.<schema-name>
[COMMENT "<comment>"];

As opções incluem o seguinte. PARTITION e AS <alias> não estarão disponíveis se você selecionar um esquema inteiro. WITH HISTORY é selecionado por padrão para todas as tabelas se você selecionar um esquema inteiro.

PARTITION(<clause>): para compartilhar somente parte da tabela, é possível especificar uma partição. Por exemplo, (column = 'value') Consulte Especificar partições de tabela para compartilhar e Usar propriedades de destinatário para fazer a filtragem de partição.
AS <alias>: um nome de tabela alternativo ou um Alias para tornar o nome da tabela mais legível. O alias é o nome da tabela que o destinatário vê e deve usar nas consultas. Os destinatários não podem usar o nome da tabela real quando um alias foi especificado. Use o formato <schema-name>.<table-name>.
WITH HISTORY ou WITHOUT HISTORY: quando WITH HISTORY for especificado, compartilhe a tabela com o histórico completo, permitindo que os destinatários realizem consultas de viagem no tempo e leituras de streaming. O comportamento padrão para compartilhamento de tabela é WITHOUT HISTORY e para compartilhamento de esquema é WITH HISTORY. Requer o Databricks Runtime 12.2 LTS ou superior.

Observação

Se, além de fazer consultas de viagem no tempo e leituras de streaming, você desejar que os clientes possam consultar o CDF (feed de dados de alterações) de uma tabela usando a função table_changes(), habilite o CDF na tabela antes de compartilhá-lo WITH HISTORY.

Para obter mais informações sobre ALTER SHARE opções, consulte ALTER SHARE.

CLI

Para adicionar uma tabela, execute o seguinte comando usando a CLI Databricks.

databricks shares update <share-name> \
  --json '{
    "updates": [
      {
        "action": "ADD",
        "data_object": {
          "name": "<table-full-name>",
          "data_object_type": "TABLE",
          "shared_as": "<table-alias>"
        }
      }
    ]
  }'

Para adicionar um esquema, execute o seguinte comando da CLI do Databricks:

databricks shares update <share-name> \
  --json '{
    "updates": [
      {
        "action": "ADD",
        "data_object": {
          "name": "<schema-full-name>",
          "data_object_type": "SCHEMA"
        }
      }
    ]
  }'

Observação

Para tabelas e apenas tabelas, você pode omitir "data_object_type".

Para saber mais sobre as opções listadas neste exemplo, exiba as instruções na guia SQL.

Para saber mais sobre parâmetros adicionais, execute databricks shares update --help, ou confira PATCH /api/2.1/unity-catalog/shares/ na referência da API REST.

Para saber como remover tabelas de um compartilhamento, confira Atualizar compartilhamentos.

Para compartilhar somente parte de uma tabela ao adicioná-la a um compartilhamento, forneça uma especificação de partição. Você pode especificar partições ao adicionar uma tabela a um compartilhamento ou atualizar um compartilhamento, usando o Explorador de catálogos, a CLI do Catálogo do Unity do Databricks ou comandos SQL em um Notebooks do Azure Databricks ou o editor de consultas SQL do Databricks. Confira Adicionar tabelas a um compartilhamento e Atualizar compartilhamentos.

Exemplo básico

O exemplo de SQL a seguir compartilha parte dos dados da tabela inventory, particionados pelas colunas year, month e date:

Dados do ano de 2021.
Dados de dezembro de 2020.
Dados de 25 de dezembro de 2019.

ALTER SHARE share_name
ADD TABLE inventory
PARTITION (year = "2021"),
          (year = "2020", month = "Dec"),
          (year = "2019", month = "Dec", date = "2019-12-25");

Use as propriedades do destinatário para fazer filtragem de partição

Você pode compartilhar uma partição de tabela que corresponda às propriedades do destinatário de dados, também conhecida como compartilhamento de partição parametrizada.

As propriedades padrão incluem:

databricks.accountId: A conta do Azure Databricks à qual um destinatário de dados pertence (somente compartilhamento do Databricks para Databricks).
databricks.metastoreId: O metastore do Catálogo do Unity ao qual um destinatário de dados pertence (somente compartilhamento do Databricks para Databricks).
databricks.name: O nome do destinatário dos dados.

Você pode criar qualquer propriedade personalizada desejada ao criar ou atualizar um destinatário.

A filtragem por propriedade de destinatário permite que você compartilhe as mesmas tabelas, usando o mesmo compartilhamento, em várias contas, workspaces e usuários do Databricks, mantendo os limites de dados entre elas.

Por exemplo, se suas tabelas incluírem uma coluna de ID de conta do Azure Databricks, você poderá criar um único compartilhamento com partições de tabela definidas pela ID da conta do Azure Databricks. Quando você compartilha, o Compartilhamento Delta entrega dinamicamente a cada destinatário apenas os dados associados à conta do Azure Databricks.

Diagrama de compartilhamento de partição dinâmica baseada em parâmetros no Compartilhamento Delta

Sem a capacidade de particionar dinamicamente por propriedade, você teria que criar um compartilhamento separado para cada destinatário.

Para especificar uma partição que filtra por propriedades do destinatário ao criar ou atualizar um compartilhamento, você pode usar o Explorador de catálogos ou a função CURRENT_RECIPIENT SQL em um Notebook do Azure Databricks ou o editor de consultas SQL do Databricks:

Observação

As propriedades do destinatário estão disponíveis no Databricks Runtime 12.2 e superior.

Explorador do Catálogo

No espaço de trabalho do Azure Databricks, clique em Catálogo.
No painel esquerdo, expanda o menu Compartilhamento Delta e selecione Compartilhado por mim.
Na guia Compartilhamentos, localize o compartilhamento que você deseja atualizar e clique no nome dele.
Clique em Gerenciar ativos > Adicionar ativos de dados.
Na página Adicionar tabelas, selecione o catálogo e o banco de dados que contêm a tabela e selecione a tabela.

Se não souber qual catálogo e banco de dados contêm a tabela, pesquise-a pelo nome, pelo nome da coluna ou pelo comentário usando a pesquisa do workspace. Consulte Pesquisar objetos do espaço de trabalho.
(Opcional) Clique em Opções de tabela avançadas para adicionar especificações de Partição.

Na caixa de diálogo Adicionar partição a uma tabela, adicione a especificação de partição baseada em propriedade usando a seguinte sintaxe:
```
(<column-name> = CURRENT_RECIPIENT(<property-key>))
```
Por exemplo,
```
(country = CURRENT_RECIPIENT('country'))
```
Clique em Save (Salvar).

Sql

Execute o seguinte comando em um notebook ou no editor de consultas do Databricks SQL:

ALTER SHARE <share-name> ADD TABLE <catalog-name>.<schema-name>.<table-name>
   PARTITION (<column-name> = CURRENT_RECIPIENT(<property-key>);

Por exemplo,

ALTER SHARE acme ADD TABLE acme.default.some_table
  PARTITION (country = CURRENT_RECIPIENT('country'))

Importante

Esse recurso está em uma versão prévia.

Os vetores de exclusão são um recurso de otimização de armazenamento que você pode habilitar nas tabelas Delta. Confira O que são vetores de exclusão?

O Azure Databricks também dá suporte ao mapeamento de colunas para tabelas Delta. Confira Renomear e remover colunas usando o mapeamento de colunas do Delta Lake.

Para compartilhar uma tabela com vetores de exclusão ou mapeamento de coluna, você deve compartilhá-la com o histórico. Confira Adicionar tabelas a um compartilhamento.

Quando você compartilha uma tabela com vetores de exclusão ou mapeamento de coluna, os destinatários podem consultar a tabela usando um armazém SQL, um cluster executando o Databricks Runtime 14.1 ou superior ou computação que esteja executando o código aberto delta-sharing-spark 3.1 ou superior. Consulte tabelas de leitura com vetores de exclusão ou mapeamento de coluna habilitado e tabelas de leitura com vetores de exclusão ou mapeamento de coluna habilitado.

Importante

Esse recurso está em uma versão prévia.

Os modos de exibição são objetos somente leitura criados a partir de uma ou mais tabelas ou outros modos de exibição. Uma exibição pode ser criada a partir de tabelas e outras exibições contidas em vários esquemas e catálogos em um metastore do Catálogo Unity. Consulte Criar modos de exibição.

Esta seção descreve como adicionar exibições a um compartilhamento usando o Gerenciador de Catálogos, a CLI do Databricks ou comandos SQL em um notebook do Azure Databricks ou o editor de consultas SQL do Databricks. Se você preferir usar a API REST do Catálogo do Unity, confira PATCH /api/2.1/unity-catalog/shares/ na referência da API REST.

Permissões necessárias: proprietário do objeto de compartilhamento USE CATALOG e USE SCHEMA no catálogo e esquema que contêm a exibição, e SELECT na exibição. Você deve manter o privilégio SELECT pelo tempo que quiser compartilhar a exibição. Para saber mais, confira Requisitos.

Requisitos adicionais:

O compartilhamento de exibição é suportado apenas no compartilhamento Databricks-to-Databricks.
As visualizações compartilháveis devem ser definidas em tabelas Delta ou outras visualizações compartilháveis.
Não é possível compartilhar exibições que façam referência a tabelas ou exibições compartilhadas.
Você deve usar um SQL warehouse ou um cluster no Databricks Runtime 13.3 LTS ou superior ao adicionar uma exibição a um compartilhamento.
Para obter requisitos e limitações sobre o uso de modos de exibição pelo destinatário, consulte Ler modos de exibição compartilhados.

Para adicionar modos de exibição a um compartilhamento:

Explorador do Catálogo

No espaço de trabalho do Azure Databricks, clique em Catálogo.
No painel esquerdo, expanda o menu Compartilhamento Delta e selecione Compartilhado por mim.
Na guia Compartilhamentos localize o compartilhamento ao qual você deseja adicionar um modo de exibição e clique em seu nome.
Clique em Gerenciar ativos > Adicionar ativos de dados.
Na página Adicionar tabelas pesquise ou procure o modo de exibição que você deseja compartilhar e selecione-o.
(Opcional) Clique em Opções avançadas de tabela para especificar um Alias ou nome de exibição alternativo, para tornar o nome do modo de exibição mais legível. O alias é o nome que o destinatário vê e deve usar em consultas. Os destinatários não poderão usar o nome de exibição real se um alias for especificado.
Clique em Save (Salvar).

Sql

Execute o seguinte comando em um notebook ou no editor de consultas do Databricks SQL:

ALTER SHARE <share-name> ADD VIEW <catalog-name>.<schema-name>.<view-name>
   [COMMENT "<comment>"]
   [AS <alias>];

As opções incluem:

AS <alias>: um nome de exibição alternativo, ou alias, para tornar o nome do modo de exibição mais legível. O alias é o nome de exibição que o destinatário vê e deve usar em consultas. Os destinatários não poderão usar o nome de exibição real se um alias for especificado. Use o formato <schema-name>.<view-name>.
COMMENT "<comment>": Os comentários aparecem na interface do usuário do Explorador de catálogos e quando você lista e exibe detalhes da visualização usando instruções SQL.

Para obter mais informações sobre ALTER SHARE opções, consulte ALTER SHARE.

CLI

Execute o seguinte comando da CLI do Databricks:

databricks shares update <share-name> \
  --json '{
    "updates": [
      {
        "action": "ADD",
        "data_object": {
          "name": "<view-full-name>",
          "data_object_type": "VIEW",
          "shared_as": "<view-alias>"
        }
      }
    ]
  }'

"shared_as": "<view-alias>" é opcional e fornece um nome de exibição alternativo, ou alias, para tornar o nome de exibição mais legível. O alias é o nome de exibição que o destinatário vê e deve usar em consultas. Os destinatários não poderão usar o nome de exibição real se um alias for especificado. Use o formato <schema-name>.<view-name>.

Para saber mais sobre parâmetros adicionais, execute databricks shares update --help, ou confira PATCH /api/2.1/unity-catalog/shares/ na referência da API REST.

Para obter informações sobre como remover exibições de um compartilhamento, confira Atualizar compartilhamentos.

Importante

Esse recurso está em uma versão prévia.

É possível usar exibições dinâmicas para configurar o controle de acesso refinado aos dados da tabela, inclusive:

Segurança de nível de colunas ou linhas.
Mascaramento de dados.

Quando você cria uma exibição dinâmica que usa a função CURRENT_RECIPIENT(), é possível limitar o acesso do destinatário de acordo com as propriedades especificadas na definição do destinatário.

Esta seção fornece exemplos de restrição do acesso do destinatário aos dados da tabela, tanto no nível da linha quanto da coluna, utilizando uma exibição dinâmica.

Requisitos

Versão do Databricks para o Databricks Runtime: a função CURRENT_RECIPIENT tem suporte para o Databricks Runtime 14.2 e versões posteriores.
Permissões:
- Para criar uma exibição, você deve ser o proprietário do objeto de compartilhamento, ter USE CATALOG e USE SCHEMA no catálogo e no esquema que contêm a visualização, além de SELECT na exibição. Você deve manter o privilégio SELECT pelo tempo que quiser compartilhar a exibição.
- Para definir propriedades em um destinatário, você deve ser o proprietário do objeto destinatário.
Limitações: todas as limitações para compartilhamento de exibição, incluindo a restrição ao compartilhamento do Databricks para Databricks, mais o seguinte:
- Quando um provedor compartilha uma exibição que usa a função CURRENT_RECIPIENT, o provedor não pode consultar a exibição diretamente devido ao contexto de compartilhamento. Para testar uma exibição dinâmica, o provedor deve compartilhar a exibição com ele mesmo e consultar a exibição como um destinatário.
- Os provedores não podem criar uma visualização que faça referência a uma exibição dinâmica.

Definir uma propriedade de destinatário

Nesses exemplos, a tabela a ser compartilhada tem uma coluna chamada country, e somente os destinatários com uma propriedade country correspondente podem visualizar determinadas linhas ou colunas.

Você pode definir as propriedades do destinatário utilizando o Gerenciador de Catálogos ou comandos SQL em um notebook do Azure Databricks ou o editor de consultas SQL.

Explorador do Catálogo

No espaço de trabalho do Azure Databricks, clique em Catálogo.
No painel esquerdo, expanda o menu Compartilhamento Delta e selecione Compartilhado por mim.
Na guia Recipientes, localize o destinatário ao qual deseja adicionar as propriedades e clique em seu nome.
Clique em Editar propriedades.
Na caixa de diálogo Editar propriedades do destinatário, digite o nome da coluna como chave (neste caso, country) e o valor pelo qual deseja filtrar como valor (por exemplo, CA).
Clique em Save (Salvar).

Sql

Para definir a propriedade no destinatário, use ALTER RECIPIENT. Neste exemplo, a propriedade country é definida como CA.

ALTER RECIPIENT recipient1 SET PROPERTIES ('country' = 'CA');

Criar uma exibição dinâmica com permissão em nível de linha para os destinatários

Neste exemplo, apenas os destinatários com uma propriedade country correspondente podem exibir determinadas linhas.

CREATE VIEW my_catalog.default.view1 AS
  SELECT * FROM my_catalog.default.my_table
  WHERE country = CURRENT_RECIPIENT('country');

Outra opção é que o provedor de dados mantenha uma tabela de mapeamento separada que mapeie os campos da tabela de fatos para as propriedades do destinatário, permitindo que as propriedades do destinatário e os campos da tabela de fatos sejam desacoplados para maior flexibilidade.

Criar uma exibição dinâmica com permissão em nível de coluna para os destinatários

Neste exemplo, somente os destinatários que correspondem à propriedade country podem exibir determinadas colunas. Outros veem os dados retornados como REDACTED:

CREATE VIEW my_catalog.default.view2 AS
  SELECT
  CASE
    WHEN CURRENT_RECIPIENT('country') = 'US' THEN pii
    ELSE 'REDACTED'
  END AS pii
  FROM my_catalog.default.my_table;

Para compartilhar a exibição dinâmica com um destinatário, use os mesmos comandos SQL ou procedimento de interface do usuário que você usaria para uma exibição padrão. Consulte Adicionar modos de exibição a um compartilhamento.

Importante

Esse recurso está em uma versão prévia.

Os volumes são objetos do Catálogo do Unity que representam um volume lógico de armazenamento em um local de armazenamento de objetos de nuvem. Eles se destinam principalmente a fornecer governança sobre ativos de dados não tabulares. Confira Criar e trabalhar com volumes.

Esta seção descreve como adicionar volumes a um compartilhamento usando o Gerenciador de Catálogos, a CLI do Databricks ou os comandos SQL em um notebook do Azure Databricks ou editor de consultas SQL. Se você preferir usar a API REST do Catálogo do Unity, confira PATCH /api/2.1/unity-catalog/shares/ na referência da API REST.

Permissões necessárias: proprietário do objeto de compartilhamento USE CATALOG e USE SCHEMA no catálogo e esquema que contêm o volume, e READ VOLUME no volume. Você deve manter o privilégio READ VOLUME enquanto quiser compartilhar o volume. Para saber mais, confira Requisitos.

Requisitos adicionais:

O compartilhamento de volume só tem suporte no compartilhamento do Databricks para o Databricks.
Você deve usar um SQL Warehouse na versão 2023.50 ou superior ou um cluster no Databricks Runtime 14.1 ou superior ao adicionar um volume a um compartilhamento.

Para adicionar volumes a um compartilhamento:

Explorador do Catálogo

No espaço de trabalho do Azure Databricks, clique em Catálogo.
No painel esquerdo, expanda o menu Compartilhamento Delta e selecione Compartilhado por mim.
Na guia Compartilhamentos, localize o compartilhamento ao qual você deseja adicionar um volume e clique em seu nome.
Clique em Gerenciar ativos > Editar ativos.
Na página Editar ativos, pesquise ou procure o volume que você deseja compartilhar e selecione-o.

Como alternativa, você pode selecionar todo o esquema que contém o volume. Consulte Adicionar esquemas a um compartilhamento.
(Opcional) Clique em Opções avançadas para especificar um nome de volume alternativo, ou Alias para tornar o nome do volume mais legível.

Os aliases não estarão disponíveis se você selecionar um esquema inteiro.

O alias é o nome que o destinatário vê e deve usar em consultas. Os destinatários não poderão usar o nome do volume real se um alias for especificado.
Clique em Save (Salvar).

Sql

Execute o seguinte comando em um notebook ou no editor de consultas do Databricks SQL:

ALTER SHARE <share-name> ADD VOLUME <catalog-name>.<schema-name>.<volume-name>
   [COMMENT "<comment>"]
   [AS <alias>];

As opções incluem:

AS <alias>: um nome de volume alternativo, ou alias, para tornar o nome do volume mais legível. O alias é o nome do volume que o destinatário vê e deve usar em consultas. Os destinatários não poderão usar o nome do volume real se um alias for especificado. Use o formato <schema-name>.<volume-name>.
COMMENT "<comment>": os comentários aparecem na interface do usuário do Gerenciador de Catálogos e quando você lista e exibe detalhes do volume usando instruções SQL.

Para obter mais informações sobre ALTER SHARE opções, consulte ALTER SHARE.

CLI

Execute o seguinte comando usando a CLI do Databricks 0.210 ou superior:

 databricks shares update <share-name> \
   --json '{
     "updates": [
       {
         "action": "ADD",
         "data_object": {
           "name": "<volume-full-name>",
           "data_object_type": "VOLUME",
           "string_shared_as": "<volume-alias>"
         }
       }
     ]
   }'

"string_shared_as": "<volume-alias>" é opcional e fornece um nome de volume alternativo, ou alias, para tornar o nome do volume mais legível. O alias é o nome do volume que o destinatário vê e deve usar em consultas. Os destinatários não poderão usar o nome do volume real se um alias for especificado. Use o formato <schema-name>.<volume-name>.

Para saber mais sobre parâmetros adicionais, execute databricks shares update --help, ou confira PATCH /api/2.1/unity-catalog/shares/ na referência da API REST.

Para obter informações sobre como remover volumes de um compartilhamento, confira Atualizar compartilhamentos.

Importante

Esse recurso está em uma versão prévia.

Esta seção descreve como adicionar modelos a um compartilhamento usando o Catalog Explorer, a CLI do Databricks ou os comandos SQL em um notebook do Azure Databricks ou editor de consultas SQL. Se você preferir usar a API REST do Catálogo do Unity, confira PATCH /api/2.1/unity-catalog/shares/ na referência da API REST.

Permissões necessárias: proprietário do objeto a ser compartilhado, USE CATALOG e USE SCHEMA no catálogo e no esquema que contêm o modelo e EXECUTE no modelo. Você precisa manter o privilégio EXECUTE enquanto quiser compartilhar o modelo. Para saber mais, confira Requisitos.

Requisitos adicionais:

O compartilhamento de modelos é suportado apenas no compartilhamento do Databricks para o Databricks.
Você precisa usar um SQL Warehouse na versão 2023.50 ou superior ou um cluster no Databricks Runtime 14.0 ou superior quando adicionar um modelo a um compartilhamento.

Para adicionar modelos a um compartilhamento:

Explorador do Catálogo

No espaço de trabalho do Azure Databricks, clique em Catálogo.
No painel esquerdo, expanda o menu Compartilhamento Delta e selecione Compartilhado por mim.
Na guia Compartilhamentos, localize o compartilhamento ao qual você quer adicionar um modelo e clique no respectivo nome.
Clique em Gerenciar ativos > Editar ativos.
Na página Editar ativos, pesquise ou procure o modelo que você quer compartilhar e selecione-o.

Alternativamente, você pode selecionar o esquema inteiro que contém o modelo. Consulte Adicionar esquemas a um compartilhamento.
(Opcional) Clique em Opções avançadas para especificar um nome de modelo alternativo ou Alias para tornar o nome do modelo mais legível.

Os aliases não estarão disponíveis se você selecionar um esquema inteiro.

O alias é o nome que o destinatário vê e deve usar em consultas. Os destinatários não poderão usar o nome real do modelo se um alias for especificado.
Clique em Save (Salvar).

Sql

Execute o seguinte comando em um notebook ou no editor de consultas do Databricks SQL:

ALTER SHARE <share-name> ADD MODEL <catalog-name>.<schema-name>.<model-name>
   [COMMENT "<comment>"]
   [AS <alias>];

As opções incluem:

AS <alias>: um nome de modelo alternativo, ou alias, para tornar o nome do modelo mais legível. O alias é o nome do modelo que o destinatário vê e precisa usar nas consultas. Os destinatários não poderão usar o nome real do modelo se um alias for especificado. Use o formato <schema-name>.<model-name>.
COMMENT "<comment>": os comentários aparecem na interface do usuário do Catalog Explorer e quando você lista e exibe detalhes do modelo usando instruções SQL.

Para obter mais informações sobre ALTER SHARE opções, consulte ALTER SHARE.

CLI

Execute o seguinte comando usando a CLI do Databricks 0.210 ou superior:

 databricks shares update <share-name> \
   --json '{
     "updates": [
       {
         "action": "ADD",
         "data_object": {
           "name": "<model-full-name>",
           "data_object_type": "MODEL",
           "string_shared_as": "<model-alias>"
         }
       }
     ]
   }'

"string_shared_as": "<model-alias>" é opcional e fornece um nome de modelo alternativo, ou alias, para tornar o nome do modelo mais legível. O alias é o nome do modelo que o destinatário vê e precisa usar nas consultas. Os destinatários não poderão usar o nome real do modelo se um alias for especificado. Use o formato <schema-name>.<model-name>.

Para saber mais sobre parâmetros adicionais, execute databricks shares update --help, ou confira PATCH /api/2.1/unity-catalog/shares/ na referência da API REST.

Para obter informações sobre como remover modelos de um compartilhamento, confira Atualizar compartilhamentos.

Importante

Esse recurso está em uma versão prévia.

Quando você adiciona um esquema inteiro a um compartilhamento, seus destinatários terão acesso não apenas a todos os ativos de dados no esquema no momento em que você criar o compartilhamento, mas a todos os ativos que forem adicionados ao esquema ao longo do tempo. Isso inclui todas as tabelas, exibições e volumes no esquema. As tabelas compartilhadas dessa forma sempre incluem o histórico completo.

Adicionar, atualizar ou remover um esquema usando SQL requer um SQL Warehouse ou computação executando o Databricks Runtime 13.3 LTS ou superior. Para fazer o mesmo usando o Explorador de catálogos, você não precisa de computação.

Permissões necessárias: proprietário do objeto de compartilhamento e proprietário do esquema (ou um usuário com privilégios USE SCHEMA e SELECT no esquema).

Para adicionar um esquema a um compartilhamento, siga as instruções em Adicionar tabelas a um compartilhamento, prestando atenção ao conteúdo que especifica como adicionar um esquema.

Aliases de tabela, partições e aliases de volume não estarão disponíveis se você selecionar um esquema inteiro. Se você tiver criado aliases ou partições para quaisquer ativos no esquema, eles serão removidos quando você adicionar todo o esquema ao compartilhamento.

Se você quiser especificar opções avançadas para uma tabela ou volume que está compartilhando usando o compartilhamento de esquemas, compartilhe a tabela ou o volume usando SQL e dê à tabela ou volume um alias com um nome de esquema diferente.

Use o Catálogo Explorer para adicionar um arquivo de notebook a um compartilhamento.

Observação

Para compartilhar notebooks, seu metastore deve ter um armazenamento no nível do metastore.

Permissões necessárias: ser proprietário do objeto de compartilhamento e ter a permissão CAN READ no notebook que você quer compartilhar.

No espaço de trabalho do Azure Databricks, clique em Catálogo.
No painel esquerdo, expanda o menu Compartilhamento Delta e selecione Compartilhado por mim.
Na guia Compartilhamentos, localize o compartilhamento ao qual você deseja adicionar um notebook e clique no nome dele.
Clique em Gerenciar ativos e selecione Adicionar arquivo de notebook.
Na página Adicionar arquivo de notebook, clique no ícone de arquivo para procurar o notebook que você deseja compartilhar.

Clique no arquivo que você deseja compartilhar e clique em Selecionar.

(Opcionalmente) especifique um alias amigável para o arquivo no campo Compartilhar como. Esse é o identificador que os destinatários verão.
Clique em Save (Salvar).

O arquivo de notebook compartilhado agora aparece na lista Arquivos de notebook na guia Ativos.

Remover arquivos de notebook de compartilhamentos

Para remover um arquivo de notebook de um compartilhamento:

No espaço de trabalho do Azure Databricks, clique em Catálogo.
No painel esquerdo, expanda o menu Compartilhamento Delta e selecione Compartilhado por mim.
Na guia Compartilhamentos, localize o compartilhamento que inclui o notebook e clique no nome do compartilhamento.
Na guia Ativos, localize o arquivo de notebook que você deseja remover do compartilhamento.
Clique no menu kebab (também conhecido como menu de três pontos) à direita da linha e selecione Excluir arquivo de notebook.
Na caixa de diálogo de confirmação, clique em Excluir.

Atualizar arquivos de notebook em compartilhamentos

Para atualizar um notebook que você já compartilhou, você deve adicioná-lo novamente, dando-lhe um novo alias no campo Compartilhar como. O Databricks recomenda que você use um nome que indique o status revisado do notebook, como <old-name>-update-1. Talvez seja necessário notificar o destinatário sobre a alteração. O destinatário deve selecionar e clonar o novo notebook para aproveitar sua atualização.

Para conceder acesso de compartilhamento aos destinatários, você pode usar o Explorador de catálogos, a CLI do Catálogo do Unity do Databricks ou o comando GRANT ON SHARE SQL em um Notebook do Azure Databricks ou no editor de consultas SQL do Databricks.

Permissões necessárias: uma das seguintes:

Administrador de metastore.
permissões delegadas ou propriedade no compartilhamento e nos objetos de destinatário ((USE SHARE + SET SHARE PERMISSION) ou proprietário do compartilhamento) E (USE RECIPIENT ou proprietário do destinatário).

Para obter instruções, consulte Conceder e gerenciar o acesso aos compartilhamentos de dados do Compartilhamento Delta (para provedores). Este artigo também explica como revogar o acesso de um destinatário a um compartilhamento.

Para exibir uma lista de compartilhamentos ou detalhes sobre um compartilhamento, você pode usar o Explorador de catálogos, a CLI do Catálogo do Unity do Databricks ou comandos SQL em um Notebook do Azure Databricks ou o editor de consultas SQL do Databricks.

Permissões necessárias: a lista de compartilhamentos retornada depende de sua função e de suas permissões. Administradores e usuários do Metastore com o privilégio USE SHARE veem todos os compartilhamentos. Caso contrário, será possível exibir apenas os compartilhamentos para os quais você é o proprietário do objeto de compartilhamento.

Os detalhes incluem:

O proprietário do compartilhamento, o criador, o registro de data e hora de criação, o atualizador, o registro de data e hora atualizado e os comentários.
Ativos de dados no compartilhamento.
Destinatários com acesso ao compartilhamento.

Explorador do Catálogo

No espaço de trabalho do Azure Databricks, clique em Catálogo.
No painel esquerdo, expanda o menu Compartilhamento Delta e selecione Compartilhado por mim.
Abra a guia Compartilhamentos para exibir uma lista de compartilhamentos.
Veja os detalhes do compartilhamento na guia Detalhes.

Sql

Para exibir uma lista de compartilhamentos, execute o comando a seguir em um notebook ou no editor de consultas do Databricks SQL. Opcionalmente, substitua <pattern> por um predicado LIKE.

SHOW SHARES [LIKE <pattern>];

Para exibir detalhes sobre um compartilhamento específico, execute o comando a seguir.

DESCRIBE SHARE <share-name>;

Para exibir detalhes sobre todas as tabelas, exibições e volumes em um compartilhamento, execute o comando a seguir.

SHOW ALL IN SHARE <share-name>;

CLI

Para exibir uma lista de compartilhamentos, execute o comando a seguir usando a CLI do Databricks.

databricks shares list

Para exibir detalhes sobre um compartilhamento específico, execute o comando a seguir.

databricks shares get <share-name>

Para exibir a lista de compartilhamentos aos quais um destinatário recebeu acesso, você pode usar o Explorador de catálogos, a CLI do Catálogo do Unity do Databricks ou o comando SHOW GRANTS TO RECIPIENT SQL em um Notebook do Azure Databricks ou no editor de consultas SQL do Databricks.

Permissões necessárias: Administrador do Metastore, privilégio USE SHARE ou proprietário do objeto de compartilhamento.

Explorador do Catálogo

No espaço de trabalho do Azure Databricks, clique em Catálogo.
No painel esquerdo, expanda o menu Compartilhamento Delta e selecione Compartilhado por mim.
Na guia Compartilhamentos, localize e selecione o destinatário.
Acesse a guia Destinatários para exibir a lista de destinatários que podem acessar o compartilhamento.

Sql

Execute o comando a seguir em um notebook ou no editor de SQL do Databricks.

SHOW GRANTS ON SHARE <share-name>;

Cli

Execute o comando a seguir usando a CLI do Databricks.

databricks shares share-permissions <share-name>

Atualizar compartilhamentos

Além de adicionar tabelas, exibições, volumes e notebooks a um compartilhamento, você pode:

Renomear um compartilhamento.
Remover tabelas, exibições, volumes e esquemas de um compartilhamento.
Adicionar ou atualizar um comentário em um compartilhamento.
Habilite ou desabilite o acesso aos dados de histórico de uma tabela, permitindo que os destinatários executem consultas de viagem no tempo ou leituras de streaming da tabela.
Adicionar, atualizar ou remover definições de partição.
Alterar o proprietário do compartilhamento.

Para fazer essas atualizações nos compartilhamentos, você pode usar o Explorador de Catálogos, a CLI do Catálogo do Unity do Databricks ou comandos SQL em um Notebooks do Azure Databricks ou o editor de consultas SQL do Databricks. Você não pode usar o Explorador de catálogos para renomear o compartilhamento.

Permissões necessárias: Para atualizar o proprietário do compartilhamento, você deve ser um dos seguintes: um administrador de metastore, o proprietário do objeto de compartilhamento ou um usuário com os privilégios USE SHARE e SET SHARE PERMISSION. Para atualizar o nome do compartilhamento, você deve ser um administrador de metastore (ou usuário com o privilégio CREATE_SHARE) e proprietário do compartilhamento. Para atualizar quaisquer outras propriedades de compartilhamento, você deve ser o proprietário.

Explorador do Catálogo

No espaço de trabalho do Azure Databricks, clique em Catálogo.
No painel esquerdo, expanda o menu Compartilhamento Delta e selecione Compartilhado por mim.
Na guia Compartilhamentos, localize o compartilhamento que você deseja atualizar e clique no nome dele.

Na página de detalhes do compartilhamento, é possível fazer o seguinte:

Clique no ícone editar ao lado do campo do proprietário ou do comentário para atualizar esses valores.
Clique no botão de reticências verticais em uma linha de ativo para removê-los.
Clique em Gerenciar ativos > Editar ativos para atualizar todas as outras propriedades:
- Para remover um ativo, desmarque a caixa de seleção ao lado do ativo.
- Para adicionar, atualizar ou remover definições de partição, clique em Opções avançadas.

Sql

Execute os comandos a seguir em um notebook ou no editor do Databricks SQL.

Renomear um compartilhamento:

ALTER SHARE <share-name> RENAME TO <new-share-name>;

Remover tabelas de um compartilhamento:

ALTER SHARE share_name REMOVE TABLE <table-name>;

Remover volumes de um compartilhamento:

ALTER SHARE share_name REMOVE VOLUME <volume-name>;

Adicionar ou atualizar um comentário em um compartilhamento:

COMMENT ON SHARE <share-name> IS '<comment>';

Adicionar ou modificar partições para uma tabela em um compartilhamento:

ALTER SHARE <share-name> ADD TABLE <table-name> PARTITION(<clause>);

Alterar o proprietário do compartilhamento:

ALTER SHARE <share-name> OWNER TO  '<principal>'

-- Principal must be an account-level user email address or group name.

Habilite o compartilhamento de histórico para uma tabela:

ALTER SHARE <share-name> ADD TABLE <table-name> WITH HISTORY;

Para obter detalhes sobre parâmetros ALTER SHARE, consulte ALTER SHARE.

Cli

Execute os comandos a seguir usando a CLI do Databricks.

Renomear um compartilhamento:

databricks shares update <share-name> --name <new-share-name>

Remover tabelas de um compartilhamento:

databricks shares update <share-name> \
  --json '{
    "updates": [
      {
        "action": "REMOVE",
        "data_object": {
          "name": "<table-full-name>",
          "data_object_type": "TABLE",
          "shared_as": "<table-alias>"
        }
      }
    ]
  }'

Remover volumes de um compartilhamento (usando a CLI do Databricks 0.210 ou superior):

databricks shares update <share-name> \
  --json '{
    "updates": [
      {
        "action": "REMOVE",
        "data_object": {
          "name": "<volume-full-name>",
          "data_object_type": "VOLUME",
          "string_shared_as": "<volume-alias>"
        }
      }
    ]
  }'

Observação

Use a propriedade name se não houver um alias para o volume. Use string_shared_as se houver um alias.

Adicionar ou atualizar um comentário em um compartilhamento:

databricks shares update <share-name> --comment '<comment>'

Alterar o proprietário do compartilhamento:

databricks  shares update <share-name> --owner '<principal>'

A entidade de segurança deve ser um endereço de email de usuário no nível da conta ou um nome de grupo.

Para excluir um compartilhamento, você pode usar o Explorador de catálogos, a CLI do Catálogo do Unity do Databricks ou o comando DELETE SHARE SQL em um Notebook do Azure Databricks ou o editor de consultas SQL do Databricks. É necessário ser o proprietário do compartilhamento.

Ao excluir um compartilhamento, os destinatários não podem mais acessar os dados compartilhados.

Permissões necessárias: proprietário do objeto de compartilhamento.

Explorador do Catálogo

No espaço de trabalho do Azure Databricks, clique em Catálogo.
No painel esquerdo, expanda o menu Compartilhamento Delta e selecione Compartilhado por mim.
Na guia Compartilhamentos, localize o compartilhamento que você deseja excluir e clique no nome dele.
Clique no menu kebab (também conhecido como menu de três pontos) e selecione Excluir.
Na caixa de diálogo de confirmação, clique em Excluir.

Sql

Execute o comando a seguir em um notebook ou no editor de SQL do Databricks.

DROP SHARE [IF EXISTS] <share-name>;

Cli

Execute o comando a seguir usando a CLI do Databricks.

databricks shares delete <share-name>

Requisitos

Criar um objeto de compartilhamento

Explorador do Catálogo

Sql

Cli

Adicionar tabelas a um compartilhamento

Explorador do Catálogo

Sql

CLI

Especificar partições de tabela para compartilhamento

Exemplo básico

Use as propriedades do destinatário para fazer filtragem de partição

Explorador do Catálogo

Sql

Adicionar tabelas com vetores de exclusão ou mapeamento de coluna a um compartilhamento

Adicionar vistas a uma partilha

Explorador do Catálogo

Sql

CLI

Adicionar exibições dinâmicas a um compartilhamento para filtrar linhas e colunas

Requisitos

Definir uma propriedade de destinatário

Explorador do Catálogo

Sql

Criar uma exibição dinâmica com permissão em nível de linha para os destinatários

Criar uma exibição dinâmica com permissão em nível de coluna para os destinatários

Compartilhar a exibição dinâmica com um destinatário

Adicionar volumes a um compartilhamento

Explorador do Catálogo

Sql

CLI

Adicionar modelos a um compartilhamento

Explorador do Catálogo

Sql

CLI

Adicionar esquemas a um compartilhamento

Adicionar um arquivo de notebook a um compartilhamento

Remover arquivos de notebook de compartilhamentos

Atualizar arquivos de notebook em compartilhamentos

Conceder aos destinatários acesso a um compartilhamento

Exibir compartilhamentos e detalhes de compartilhamento

Explorador do Catálogo

Sql

CLI

Exibir os destinatários com permissões em um compartilhamento

Explorador do Catálogo

Sql

Cli

Atualizar compartilhamentos

Explorador do Catálogo

Sql

Cli

Excluir um compartilhamento

Explorador do Catálogo

Sql

Cli

Recursos adicionais