Criar e gerenciar compartilhamentos para o Delta Sharing

Este artigo explica como criar e gerenciar ações para Delta Sharing.

Um compartilhamento é um objeto seguro em Unity Catalog que o senhor pode usar para compartilhar os seguintes dados ativos com um ou mais destinatários:

Tabelas e partições de tabelas
visualização, incluindo a visualização dinâmica que restringe o acesso no nível da linha e da coluna
Volumes
Notebooks
Modelos de IA

Se o senhor compartilhar um esquema inteiro (banco de dados), o destinatário poderá acessar todas as tabelas, visualizações, modelos e volumes do esquema no momento em que o senhor o compartilhar, juntamente com todos os dados e IA ativos que forem adicionados ao esquema no futuro.

Um compartilhamento pode conter dados e IA ativo de apenas um metastore Unity Catalog. O senhor pode adicionar ou remover dados e IA ativo de um compartilhamento a qualquer momento.

Para obter mais informações, consulte Compartilhamentos, provedores e destinatários.

Requisitos

Para criar um compartilhamento, o senhor deve:

Seja um administrador de metastore ou tenha o privilégio CREATE SHARE para o metastore do Unity Catalog onde os dados que o senhor deseja compartilhar estão registrados.
Crie o compartilhamento usando um Databricks workspace que tenha o metastore Unity Catalog anexado.

Para adicionar tabelas ou visualizações a um compartilhamento, o senhor deve:

Seja o proprietário das ações.
Ter os privilégios USE CATALOG e USE SCHEMA no catálogo e no esquema que contêm a tabela ou view, ou a propriedade do catálogo ou do esquema.
O senhor tem o privilégio SELECT na mesa ou em view. O senhor deve manter esse privilégio para que a tabela ou o site view continue a ser compartilhado. Se o senhor a perder, o destinatário não poderá acessar a tabela ou o site view por meio do compartilhamento. Portanto, a Databricks recomenda que o senhor use um grupo como proprietário do compartilhamento.

Para adicionar volumes a um compartilhamento, o senhor deve:

Seja o proprietário das ações.
Ter os privilégios USE CATALOG e USE SCHEMA no catálogo e no esquema que contêm o volume, ou a propriedade do catálogo ou do esquema.
Ter o privilégio READ VOLUME no volume. O senhor deve manter esse privilégio para que o volume continue a ser compartilhado. Se o senhor o perder, o destinatário não poderá acessar o volume por meio do compartilhamento. Portanto, a Databricks recomenda que o senhor use um grupo como proprietário do compartilhamento.

Para adicionar modelos a um compartilhamento, o senhor deve:

Seja o proprietário das ações.
Ter os privilégios USE CATALOG e USE SCHEMA no catálogo e no esquema que contêm o modelo, ou a propriedade do catálogo ou do esquema.
Ter o privilégio EXECUTE no modelo. O senhor deve manter esse privilégio para que o modelo continue a ser compartilhado. Se o senhor o perder, o destinatário não poderá acessar o modelo por meio do compartilhamento. Portanto, a Databricks recomenda que o senhor use um grupo como proprietário do compartilhamento.

Para compartilhar um esquema inteiro, o senhor deve:

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

Para adicionar arquivos do Notebook a um compartilhamento, o senhor deve estar:

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

Para conceder acesso de destinatário a um compartilhamento, o senhor deve ser um dos seguintes:

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

Para view ações, o senhor deve ser um dos seguintes:

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

Requisitos de computação:

Se o senhor usar um notebook Databricks para criar o compartilhamento, seu cluster deverá usar Databricks Runtime 11.3 LTS ou acima e o modo de acesso compartilhado ou de usuário único cluster.
Se o senhor usar as instruções SQL para adicionar um esquema a um compartilhamento (ou atualizar ou remover um esquema), deverá usar um SQL warehouse ou compute em execução Databricks Runtime 13.3 LTS ou acima. Fazer o mesmo usando o Catalog Explorer não tem requisitos do site compute.

Criar um objeto de compartilhamento

Para criar um compartilhamento, o senhor pode usar o Catalog Explorer, o Databricks Unity Catalog CLI, ou o comando CREATE SHARE SQL em um Databricks Notebook ou o editor de consultas Databricks SQL.

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

No seu workspace do Databricks, clique em Catálogo.
Na parte superior do painel Catálogo, clique no ícone de engrenagem e selecione Delta Sharing.

Como alternativa, na página de acesso rápido, clique no botão Delta Sharing >.
Em Shared by me (Compartilhado por mim ) tab, clique no botão Share data (Compartilhar dados ).
Na página Criar compartilhamento, digite o Nome do compartilhamento e um comentário opcional.
Clique em Save (Salvar) e continue.

O senhor pode continuar a adicionar dados ativos ou pode parar e voltar mais tarde.
Em Add data ativo tab, selecione as tabelas, volumes, visualizações e modelos que deseja compartilhar.

Para obter instruções detalhadas, consulte:
Clique em Save (Salvar) e continue.
Em Add Notebook tab, selecione o Notebook que deseja compartilhar.

Para obter instruções detalhadas, consulte Adicionar arquivos do Notebook a um compartilhamento.
Clique em Save (Salvar) e continue.
Em Add recipients (Adicionar destinatários ) tab, selecione os destinatários com os quais deseja compartilhar.

Para obter instruções detalhadas, consulte gerenciar o acesso aos compartilhamentos de dados do Delta Sharing (para provedores).
Clique em Share data (Compartilhar dados ) para compartilhar os dados com os destinatários.

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

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

Agora o senhor pode adicionar tabelas, volumes, visualizações e modelos ao compartilhamento.

Para obter instruções detalhadas, consulte:

Adicionar tabelas a um compartilhamento
Adicionar volumes a um compartilhamento
Adicionar visualização a um compartilhamento
Adicionar modelos a um compartilhamento

execute o seguinte comando usando o Databricks CLI.

databricks shares create <share-name>

O senhor pode usar --comment para adicionar um comentário ou --json para adicionar ativo ao compartilhamento. Para obter detalhes, consulte as seções a seguir.

Agora o senhor pode adicionar tabelas, volumes, visualizações e modelos ao compartilhamento.

Para obter instruções detalhadas, consulte:

Adicionar tabelas a um compartilhamento
Adicionar volumes a um compartilhamento
Adicionar visualização a um compartilhamento
Adicionar modelos a um compartilhamento

Adicionar tabelas a um compartilhamento

Para adicionar tabelas a um compartilhamento, o senhor pode usar o Catalog Explorer, o Databricks Unity Catalog CLI, ou SQL comando em um Databricks Notebook ou o editor de consultas Databricks SQL.

Observação

Comentários de tabela, comentários de coluna e restrições primárias de key são incluídos em compartilhamentos que são compartilhados com um destinatário usando Databricks-to-Databricks compartilhamento em ou após 25 de julho de 2024. Se o senhor quiser começar a compartilhar comentários e restrições por meio de um compartilhamento que foi compartilhado com um destinatário antes da data de liberação, deverá revogar e conceder novamente o acesso ao destinatário para acionar o compartilhamento de comentários e restrições.

Permissões necessárias: Proprietário do objeto de compartilhamento, USE CATALOG e USE SCHEMA no catálogo e no esquema que contêm a tabela, e o privilégio SELECT na tabela. O senhor deve manter o privilégio SELECT enquanto quiser compartilhar a mesa. Para obter mais informações, consulte Requisitos.

Observação

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

No seu workspace do Databricks, clique em Catálogo.
Na parte superior do painel Catálogo, clique no ícone de engrenagem e selecione Delta Sharing.

Como alternativa, na página de acesso rápido, clique no botão Delta Sharing >.
No Shared by me tab, localize o compartilhamento ao qual deseja adicionar uma tabela e clique em seu nome.
Clique em gerenciar ativo > Add data ativo.
Na página Add tables (Adicionar tabelas ), selecione um esquema inteiro (banco de dados) ou tabelas e visualizações individuais.
- Para selecionar uma tabela ou view, primeiro selecione o catálogo, depois o esquema que contém a tabela ou view e, em seguida, a própria tabela ou view.
  
  O senhor pode pesquisar tabelas por nome, nome da coluna ou comentário usando a pesquisa workspace. Consulte Search for workspace objects.
- Para selecionar um esquema, primeiro selecione o catálogo e depois o esquema.
  
  Para obter informações detalhadas sobre esquemas de compartilhamento, consulte Adicionar esquemas a um compartilhamento.
história: Compartilhe a história da tabela para permitir que os destinatários realizem consultas de viagem do tempo ou leiam a tabela com Spark transmissão estructurada. Para os compartilhamentos Databricks-to-Databricks, o Delta log da tabela também é compartilhado para melhorar o desempenho. Veja a tabela Improve ler desempenho com história compartilhamento. história compartilhamento requer Databricks Runtime 12.2 LTS ou superior.

Observação

Se, além de fazer consultas de viagem do tempo e leituras de transmissão, o senhor quiser que seus clientes possam consultar o feed de dados de alteração (CDF) de uma tabela usando a função table_changes(), deverá ativar o CDF na tabela antes de compartilhá-la WITH HISTORY.
(Opcional) Clique em Advanced table options para especificar as seguintes opções. O alias e as partições não estarão disponíveis se o senhor selecionar um esquema inteiro. O histórico da tabela é incluído pelo site default se o senhor 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 poderão usar o nome real da tabela se um alias for especificado.
- Partição: Compartilhar apenas parte da tabela. Por exemplo, (column = 'value'). Consulte Especificar partições de tabela para compartilhar e Usar propriedades do destinatário para fazer a filtragem de partições.
Clique em Salvar.

Execute o seguinte comando em um Notebook ou no editor de consultas Databricks SQL 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 compute em execução Databricks Runtime 13.3 LTS ou acima. Para obter informações detalhadas sobre esquemas de compartilhamento, 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 o senhor selecionar um esquema inteiro. WITH HISTORY é selecionado por default para todas as tabelas se o senhor selecionar um esquema inteiro.

PARTITION(<clause>): Se quiser compartilhar apenas parte da tabela, o senhor pode especificar uma partição. Por exemplo, (column = 'value') Consulte Especificar partições de tabela para compartilhar e Usar propriedades do destinatário para fazer a filtragem de partições.
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 poderão usar o nome real da tabela se um alias for 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 do tempo e leituras de transmissão. Para os compartilhamentos Databricks-to-Databricks, a história compartilhamento também compartilha o Delta log da tabela. Para melhorar o desempenho, consulte Melhorar o desempenho da leitura da tabela com a história compartilhamento. O comportamento do site default para o compartilhamento de tabelas é WITHOUT HISTORY e para o compartilhamento de esquemas é WITH HISTORY. É necessário o site Databricks Runtime 12.2 LTS ou acima.

Observação

Se, além de fazer consultas de viagem do tempo e leituras de transmissão, o senhor quiser que seus clientes possam consultar o feed de dados de alteração (CDF) de uma tabela usando a função table_changes(), deverá ativar o CDF na tabela antes de compartilhá-la WITH HISTORY.

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

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

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 Databricks CLI comando:

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

Observação

Para tabelas, e somente tabelas, o senhor pode omitir "data_object_type".

Para saber mais sobre as opções listadas neste exemplo, view as instruções no site SQL tab.

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

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

Especificar as partições de tabela a serem compartilhadas

Para compartilhar apenas parte de uma tabela ao adicioná-la a um compartilhamento, o senhor pode fornecer uma especificação de partição. O senhor pode especificar partições ao adicionar uma tabela a um compartilhamento ou atualizar um compartilhamento, usando o Catalog Explorer, o Databricks Unity Catalog CLI, ou SQL comando em um Databricks Notebook ou o editor de consultas Databricks SQL. Consulte Adicionar tabelas a um compartilhamento e Atualizar compartilhamentos.

Exemplo básico

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

Dados para o 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 a filtragem de partições

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

As propriedades padrão incluem:

databricks.accountId: O Databricks account ao qual um destinatário de dados pertence (somenteDatabricks-to-Databricks compartilhamento).
databricks.metastoreId: O Unity Catalog metastore ao qual um destinatário de dados pertence (somenteDatabricks-to-Databricks compartilhamento).
databricks.name: O nome do destinatário dos dados.

O senhor pode criar qualquer propriedade personalizada que desejar ao criar ou atualizar um destinatário.

A filtragem por propriedade do destinatário permite que o senhor compartilhe as mesmas tabelas, usando o mesmo compartilhamento, em várias contas, espaços de trabalho e usuários do site Databricks, mantendo os limites de dados entre eles.

Por exemplo, se suas tabelas incluírem uma coluna Databricks account ID, o senhor poderá criar um único compartilhamento com partições de tabela definidas por Databricks account ID. Quando o senhor compartilha, o Delta Sharing fornece dinamicamente a cada destinatário apenas os dados associados ao seu Databricks account.

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

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

Para especificar uma partição que filtre por propriedades do destinatário ao criar ou atualizar um compartilhamento, o senhor pode usar o Catalog Explorer ou a função CURRENT_RECIPIENT SQL em um Notebook Databricks ou o editor de consultas Databricks SQL:

Observação

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

No seu workspace do Databricks, clique em Catálogo.
Na parte superior do painel Catálogo, clique no ícone de engrenagem e selecione Delta Sharing.

Como alternativa, na página de acesso rápido, clique no botão Delta Sharing >.
Em Shared by me (Compartilhado por mim ) tab, localize o compartilhamento que deseja atualizar e clique em seu nome.
Clique em gerenciar ativo > Add data ativo.
Na página Add tables (Adicionar tabelas ), selecione o catálogo e o banco de dados que contêm a tabela e, em seguida, selecione a tabela.

Se não tiver certeza de qual catálogo e banco de dados contém a tabela, o senhor pode procurá-la por nome, nome da coluna ou comentário usando workspace search. Consulte Search for workspace objects.
(Opcional) Clique em Advanced table options (Opções avançadas de tabela ) 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 Salvar.

Execute o seguinte comando em um Notebook ou no editor de consultas 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');

Adicionar visualização a um compartilhamento

Prévia

Este recurso está em prévia pública.

são objetos somente leitura criados a partir de uma ou mais tabelas ou outra visualização. Um view pode ser criado a partir de tabelas e outras visualizações contidas em vários esquemas e catálogos em um metastore Unity Catalog. Consulte Criar e gerenciar a visualização.

Esta seção descreve como adicionar uma visualização a um compartilhamento usando o Catalog Explorer, Databricks CLI, ou SQL comando em um Databricks Notebook ou o editor de consultas Databricks SQL. Se o senhor preferir usar a API REST do Unity Catalog, consulte 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 no esquema que contêm o view, e SELECT no view. O senhor deve manter o privilégio SELECT enquanto quiser compartilhar o view. Para obter mais informações, consulte Requisitos.

Requisitos adicionais:

O senhor deve habilitar o serverless compute para fluxo de trabalho, Notebook e Delta Live Tables no account onde o view compartilhamento está configurado. Consulte Enable serverless compute .
A visualização compartilhável deve ser definida em Delta tables ou em outra visualização compartilhável.
O senhor não pode compartilhar visualizações que façam referência a tabelas compartilhadas ou visualizações compartilhadas.
O senhor deve usar um SQL warehouse ou um cluster em Databricks Runtime 13.3 LTS ou acima quando adicionar um view a um compartilhamento.
Para conhecer os requisitos e as limitações do uso da visualização pelo destinatário, consulte Ler visualização compartilhada.

Para adicionar a visualização a um compartilhamento:

No seu workspace do Databricks, clique em Catálogo.
Na parte superior do painel Catálogo, clique no ícone de engrenagem e selecione Delta Sharing.

Como alternativa, na página de acesso rápido, clique no botão Delta Sharing >.
No Shared by me tab, localize o compartilhamento ao qual deseja adicionar um view e clique em seu nome.
Clique em gerenciar ativo > Add data ativo.
Na página Add tables (Adicionar tabelas ), pesquise ou procure o site view que deseja compartilhar e selecione-o.
(Opcional) Clique em Advanced table options (Opções avançadas de tabela ) para especificar um Alias ou um nome alternativo view, para tornar o nome view mais legível. O alias é o nome que o destinatário vê e deve usar nas consultas. Os destinatários não poderão usar o nome real de view se um alias for especificado.
Clique em Salvar.

Execute o seguinte comando em um Notebook ou no editor de consultas 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 alternativo view, ou alias, para tornar o nome view mais legível. O alias é o nome view que o destinatário vê e deve usar nas consultas. Os destinatários não podem usar o nome real de view se um alias for especificado. Use o formato <schema-name>.<view-name>.
COMMENT "<comment>": Os comentários aparecem na interface do usuário do Catalog Explorer e quando o senhor lista e exibe os detalhes do site view usando as instruções SQL.

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

Execute o seguinte Databricks CLI comando:

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 alternativo view, ou alias, para tornar o nome view mais legível. O alias é o nome view que o destinatário vê e deve usar nas consultas. Os destinatários não podem usar o nome real de view 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 consulte PATCH /api/2.1/unity-catalog/shares/ na referência REST API .

Para obter informações sobre como remover a visualização de um compartilhamento, consulte Atualizar compartilhamentos.

Adicionar visualização dinâmica a um compartilhamento para filtrar linhas e colunas

Prévia

Este recurso está em prévia pública.

O senhor pode usar a exibição dinâmica para configurar o controle de acesso refinado aos dados da tabela, inclusive:

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

Ao criar um site view dinâmico que usa a função CURRENT_RECIPIENT(), o senhor pode 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 no nível da linha e da coluna usando um view dinâmico.

Requisitos

Databricks Runtime versão: A função CURRENT_RECIPIENT é compatível com Databricks Runtime 14.2 e acima.
Permissões:
- Para criar um view, o senhor deve ser o proprietário do objeto de compartilhamento, ter USE CATALOG e USE SCHEMA no catálogo e no esquema que contêm o view, juntamente com SELECT no view. O senhor deve manter o privilégio SELECT enquanto quiser compartilhar o view.
- Para definir propriedades em um destinatário, o senhor deve ser o proprietário do objeto destinatário.
Limitações: Todas as limitações para view compartilhamento, incluindo a restrição para Databricks-to-Databricks compartilhamento, mais o seguinte:
- Quando um provedor compartilha um view que usa a função CURRENT_RECIPIENT, o provedor não pode consultar o view diretamente devido ao contexto de compartilhamento. Para testar esse view dinâmico, o provedor deve compartilhar o view consigo mesmo e consultar o view como destinatário.
- Os provedores não podem criar um view que faça referência a um view dinâmico.

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 view determinadas linhas ou colunas.

O senhor pode definir as propriedades do destinatário usando o Catalog Explorer ou SQL comando em um Databricks Notebook ou no editor de consultas SQL.

No seu workspace do Databricks, clique em Catálogo.
Na parte superior do painel Catálogo, clique no ícone de engrenagem e selecione Delta Sharing.

Como alternativa, na página de acesso rápido, clique no botão Delta Sharing >.
Em Recipients (Destinatários ) tab, localize o destinatário ao qual deseja adicionar as propriedades e clique em seu nome.
Clique em Edit properties (Editar propriedades).
Na caixa de diálogo Edit recipient properties (Editar propriedades do destinatário ), digite o nome da coluna como key (nesse caso, country) e o valor pelo qual o senhor deseja filtrar como valor (por exemplo, CA).
Clique em Salvar.

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, somente os destinatários com uma propriedade country correspondente podem acessar view 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 view 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;

Adicionar volumes a um compartilhamento

Os volumes são objetos Unity Catalog que representam um volume lógico de armazenamento em um local de armazenamento de objetos cloud. Eles se destinam principalmente a fornecer governança sobre dados não tabulares ativos. Consulte O que são volumes do Unity Catalog?

Esta seção descreve como adicionar volumes a um compartilhamento usando o Catalog Explorer, o Databricks CLI, ou o SQL comando em um Databricks Notebook ou SQL editor de consultas. Se o senhor preferir usar a API REST do Unity Catalog, consulte PATCH /api/2.1/unity-catalog/shares/ na referência da API REST.

Observação

Os comentários de volume são incluídos em compartilhamentos que são compartilhados com um destinatário usando o compartilhamento Databricks-to-Databricks em ou após 25 de julho de 2024. Se o senhor quiser começar a compartilhar comentários por meio de um compartilhamento que foi compartilhado com um destinatário antes da data de liberação, deverá revogar e conceder novamente o acesso ao destinatário para acionar o compartilhamento de comentários.

Permissões necessárias: Proprietário do objeto de compartilhamento, USE CATALOG e USE SCHEMA no catálogo e no esquema que contêm o volume, e READ VOLUME no volume. O senhor deve manter o privilégio READ VOLUME enquanto quiser compartilhar o volume. Para obter mais informações, consulte Requisitos.

Requisitos adicionais:

O compartilhamento de volumes é suportado somente em Databricks-to-Databricks compartilhamento.
O senhor deve usar um SQL warehouse na versão 2023.50 ou acima ou um cluster na versão Databricks Runtime 14.1 ou acima quando adicionar um volume a um compartilhamento.
Se o armazenamento do volume no lado do provedor tiver configurações de rede personalizadas (como um firewall ou um link privado), o provedor deverá garantir que os endereços do plano de controle e do plano de dados do destinatário estejam na lista de permissões adequada para poder se conectar ao local de armazenamento do volume.

Para adicionar volumes a um compartilhamento:

No seu workspace do Databricks, clique em Catálogo.
Na parte superior do painel Catálogo, clique no ícone de engrenagem e selecione Delta Sharing.

Como alternativa, na página de acesso rápido, clique no botão Delta Sharing >.
Em Shared by me (Compartilhado por mim ) tab, localize o compartilhamento ao qual deseja adicionar um volume e clique em seu nome.
Clique em gerenciar ativo > Edit ativo.
Na página Edit ativo, pesquise ou procure o volume que deseja compartilhar e selecione-o.

Como alternativa, o senhor pode selecionar todo o esquema que contém o volume. Consulte Adicionar esquemas a um compartilhamento.
(Opcional) Clique em Advanced options (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 o senhor selecionar um esquema inteiro.

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

Execute o seguinte comando em um Notebook ou no editor de consultas 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 nas consultas. Os destinatários não poderão usar o nome real do volume se um alias for especificado. Use o formato <schema-name>.<volume-name>.
COMMENT "<comment>": Os comentários aparecem na interface do usuário do Catalog Explorer e quando o senhor lista e exibe detalhes do volume usando instruções SQL.

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

Execute o seguinte comando usando Databricks CLI 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 nas consultas. Os destinatários não poderão usar o nome real do volume 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 consulte PATCH /api/2.1/unity-catalog/shares/ na referência REST API .

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

Adicionar modelos a um compartilhamento

Esta seção descreve como adicionar modelos a um compartilhamento usando o Catalog Explorer, o Databricks CLI, ou SQL comando em um Databricks Notebook ou SQL editor de consultas. Se o senhor preferir usar a API REST do Unity Catalog, consulte PATCH /api/2.1/unity-catalog/shares/ na referência da API REST.

Observação

Os comentários do modelo e os comentários da versão do modelo são incluídos nos compartilhamentos que são compartilhados usando Databricks-to-Databricks compartilhamento.

Permissões necessárias: Proprietário do objeto de compartilhamento, USE CATALOG e USE SCHEMA no catálogo e no esquema que contêm o modelo, e EXECUTE no modelo. O senhor deve manter o privilégio EXECUTE enquanto quiser compartilhar o modelo. Para obter mais informações, consulte Requisitos.

Requisitos adicionais:

O compartilhamento de modelos é suportado somente em Databricks-to-Databricks compartilhamento.
O senhor deve usar um SQL warehouse na versão 2023.50 ou acima ou um cluster em Databricks Runtime 14.0 ou acima quando adicionar um modelo a um compartilhamento.

Para adicionar modelos a um compartilhamento:

No seu workspace do Databricks, clique em Catálogo.
Na parte superior do painel Catálogo, clique no ícone de engrenagem e selecione Delta Sharing.

Como alternativa, na página de acesso rápido, clique no botão Delta Sharing >.
Em Shared by me (Compartilhado por mim ) tab, localize o compartilhamento ao qual deseja adicionar um modelo e clique em seu nome.
Clique em gerenciar ativo > Edit ativo.
Na página Editar ativo, pesquise ou procure o modelo que deseja compartilhar e selecione-o.

Como alternativa, o senhor pode selecionar todo o esquema que contém o modelo. Consulte Adicionar esquemas a um compartilhamento.
(Opcional) Clique em Advanced options (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 o senhor selecionar um esquema inteiro.

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

Execute o seguinte comando em um Notebook ou no editor de consultas 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 deve usar nas consultas. Os destinatários não podem 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 o senhor lista e exibe detalhes do modelo usando instruções SQL.

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

Execute o seguinte comando usando Databricks CLI 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 deve usar nas consultas. Os destinatários não podem 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 consulte PATCH /api/2.1/unity-catalog/shares/ na referência REST API .

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

Adicionar arquivos do Notebook a um compartilhamento

Use o Catalog Explorer para adicionar um arquivo do Notebook a um compartilhamento.

Permissões necessárias: Proprietário do objeto de compartilhamento e permissão CAN READ no Notebook que o senhor deseja compartilhar.

No seu workspace do Databricks, clique em Catálogo.
Na página de acesso rápido, clique no botão Delta Sharing >.
Em Shared by me (Compartilhado por mim ) tab, localize o compartilhamento ao qual deseja adicionar um Notebook e clique em seu nome.
Clique em gerenciar ativo e selecione Add Notebook file.
Na página Add Notebook file (Adicionar arquivo do Notebook ), clique no ícone de arquivo para procurar o Notebook que deseja compartilhar.
- Clique no arquivo que deseja compartilhar e clique em Select (Selecionar).
- (Opcionalmente) especifique um alias de fácil utilização para o arquivo no campo Share as. Esse é o identificador que os destinatários verão.
- Em Local de armazenamento, insira o local externo no armazenamento em nuvem onde o senhor deseja armazenar o Notebook. Você pode especificar um subcaminho no local externo definido. Se o senhor não especificar um local externo, o Notebook será armazenado no local de armazenamento no nível do metastore (ou "local raiz do metastore"). Se nenhum local raiz for definido para o metastore, você deverá inserir um local externo aqui. Consulte Adicionar armazenamento gerenciar a um metastore existente.
Clique em Salvar.

O arquivo compartilhado do Notebook agora aparece na lista de arquivosNotebook no ativo tab.

Remover arquivos do Notebook dos compartilhamentos

Para remover um arquivo do Notebook de um compartilhamento:

No seu workspace do Databricks, clique em Catálogo.
Na parte superior do painel Catálogo, clique no ícone de engrenagem e selecione Delta Sharing.

Como alternativa, na página de acesso rápido, clique no botão Delta Sharing >.
Em Shared by me (Compartilhado por mim ) tab, localize o compartilhamento que inclui o Notebook e clique no nome do compartilhamento.
No ativo tab, localize o arquivo do Notebook que deseja remover do compartilhamento.
Clique no menu kebab à direita da linha e selecione Delete Notebook file (Excluir arquivo do Notebook).
Na caixa de diálogo de confirmação, clique em Excluir.

Atualizar arquivos do Notebook em compartilhamentos

Para atualizar um Notebook que já tenha sido compartilhado, o senhor deve adicioná-lo novamente, atribuindo-lhe um novo alias no campo Compartilhar como. Databricks recomenda que o senhor use um nome que indique o status revisado do Notebook, como <old-name>-update-1. Talvez o senhor precise notificar o destinatário sobre a alteração. O destinatário deve selecionar e clonar o novo Notebook para aproveitar a sua atualização.

Atualizar ações

Além de adicionar tabelas, visualizações, volumes e Notebook a um compartilhamento, o senhor pode:

Renomear um compartilhamento.
Remover tabelas, visualizações, volumes e esquemas de um compartilhamento.
Adicionar ou atualizar um comentário em um compartilhamento.
Ativar ou desativar o acesso aos dados históricos de uma tabela, permitindo que os destinatários realizem consultas de viagem do tempo ou leituras de transmissão da tabela.
Adicionar, atualizar ou remover definições de partição.
Alterar o proprietário da ação.

Para fazer essas atualizações nos compartilhamentos, o senhor pode usar o Catalog Explorer, o Databricks Unity Catalog CLI, ou SQL comando em um Databricks Notebook ou o editor de consultas Databricks SQL. O senhor não pode usar o Catalog Explorer para renomear o compartilhamento.

Permissões necessárias: Para atualizar o proprietário do compartilhamento, o senhor deve ser um dos seguintes: um administrador do 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, o senhor deve ser um administrador do metastore (ou usuário com o privilégio CREATE_SHARE) e proprietário do compartilhamento. Para atualizar qualquer outra propriedade compartilhada, o senhor deve ser o proprietário.

No seu workspace do Databricks, clique em Catálogo.
Na parte superior do painel Catálogo, clique no ícone de engrenagem e selecione Delta Sharing.

Como alternativa, na página de acesso rápido, clique no botão Delta Sharing >.
Em Shared by me (Compartilhado por mim ) tab, localize o compartilhamento que deseja atualizar e clique em seu nome.

Na página de detalhes do compartilhamento, faça o seguinte:

Clique no ícone de edição ao lado do campo Owner (Proprietário) ou Comment (Comentário) para atualizar esses valores.
Clique no botão do menu kebab em uma linha ativa para removê-lo.
Clique em gerenciar ativo > Edit ativo 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.

Execute o seguinte comando em um Notebook ou no editor 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 da ação:

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

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

Habilitar o compartilhamento de história para uma tabela:

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

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

execute o seguinte comando usando o Databricks CLI.

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 Databricks CLI 0.210 ou acima):

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 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 da ação:

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

O Principal deve ser um usuário de nível account email endereço ou nome de grupo.

Criar e gerenciar compartilhamentos para o Delta Sharing

Requisitos

Criar um objeto de compartilhamento

Adicionar tabelas a um compartilhamento

Especificar as partições de tabela a serem compartilhadas

Exemplo básico

Use as propriedades do destinatário para fazer a filtragem de partições

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

Adicionar visualização a um compartilhamento

Adicionar visualização dinâmica a um compartilhamento para filtrar linhas e colunas

Requisitos

Definir uma propriedade de destinatário

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

Adicionar modelos a um compartilhamento

Adicionar esquemas a um compartilhamento

Adicionar arquivos do Notebook a um compartilhamento

Remover arquivos do Notebook dos compartilhamentos

Atualizar arquivos do Notebook em compartilhamentos

Conceder aos destinatários acesso a um compartilhamento

Visualizar ações e detalhes das ações

Ver os destinatários que têm permissões em um compartilhamento

Atualizar ações

Excluir um compartilhamento