Criar e gerenciar compartilhamentos para o Delta Sharing

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

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

• Tabelas e partições de tabelas
• Modos de exibição, incluindo modos de exibição dinâmicos que restringem o acesso no nível de linha e coluna
• Volumes
• Notebooks
• Modelos de IA

Se você compartilhar um esquema inteiro (banco de dados), o destinatário poderá acessar todas as tabelas, exibições, modelos e volumes no esquema no momento em que você compartilhá-lo, juntamente com quaisquer dados e ativos de IA que forem adicionados ao esquema no futuro.

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

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

Requisitos

Para criar um compartilhamento, você deve:

• Seja um administrador de metastore ou tenha o CREATE SHARE privilégio para o metastore do Unity Catalog onde os dados que você deseja compartilhar estão registrados.
• Crie o compartilhamento usando um espaço de trabalho do Azure Databricks que tenha esse metastore do Unity Catalog anexado.

Para adicionar tabelas ou vistas a uma partilha, tem de:

• Seja o proprietário da ação.
• Ter o USE CATALOG privilégio e USE SCHEMA no catálogo e esquema que contêm a tabela ou exibição, ou propriedade do catálogo ou esquema.
• Tenha o SELECT privilégio na tabela ou visualizaçã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. Portanto, o Databricks recomenda que você use um grupo como proprietário do compartilhamento.

Para adicionar volumes a um compartilhamento, você deve:

• Seja o proprietário da ação.
• Tenha o USE CATALOG privilégio e USE SCHEMA no catálogo e esquema que contêm o volume ou a propriedade do catálogo ou esquema.
• Tenha o READ VOLUME privilégio 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. Portanto, o Databricks recomenda que você use um grupo como proprietário do compartilhamento.

Para adicionar modelos a um compartilhamento, você deve:

• Seja o proprietário da ação.
• Ter o USE CATALOG privilégio e USE SCHEMA no catálogo e esquema que contêm o modelo ou a propriedade do catálogo ou esquema.
• Tenha o EXECUTE privilégio no modelo. Você deve manter esse privilégio para que o modelo continue a ser compartilhado. Se você perdê-lo, o destinatário não poderá acessar o modelo por meio do compartilhamento. Portanto, o Databricks recomenda que você use um grupo como proprietário do compartilhamento.

Para compartilhar um esquema inteiro, você deve:

• Seja o proprietário do compartilhamento e o proprietário do esquema, ou tenha USE SCHEMA.
• Tenha SELECT no esquema para compartilhar tabelas.
• Tenha READ VOLUME no esquema para compartilhar volumes.

Para adicionar arquivos de bloco de anotações a um compartilhamento, você deve ser:

• O proprietário do compartilhamento e ter permissão CAN READ no bloco de anotações.

Para conceder acesso ao destinatário a um compartilhamento, você deve ser um desses:

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

Para visualizar compartilhamentos, você deve ser um destes:

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

Requisitos de computação:

• Se você usar um bloco de anotações Databricks para criar o compartilhamento, seu cluster deverá usar o Databricks Runtime 11.3 LTS ou superior e o modo de acesso ao 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. Fazer o mesmo usando o Catalog Explorer não tem requisitos de computação.

Criar um objeto de compartilhamento

Para criar um compartilhamento, você pode usar o Gerenciador de Catálogos, a CLI do Catálogo Unity do Databricks ou o CREATE SHARE comando SQL em um bloco de anotações do Azure Databricks ou o editor de consultas do Databricks SQL.

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

Explorador de Catálogos

1. No seu espaço de trabalho do Azure Databricks, clique em Catálogo.

2. Na parte superior do painel Catálogo, clique no ícone de engrenagem e selecione Compartilhamento Delta.

   Como alternativa, na página Acesso rápido , clique no botão Compartilhamento Delta > .

3. Na guia Compartilhado por mim, clique no botão Compartilhar dados.

4. Na página Criar partilha, introduza o Nome da partilha e um comentário opcional.

5. Clique em Salvar e continuar.

   Você pode continuar a adicionar ativos de dados ou pode parar e voltar mais tarde.

6. Na guia Adicionar ativos de dados, selecione as tabelas, volumes, exibições e modelos que deseja compartilhar.

   Para obter instruções detalhadas, consulte:

   • Adicionar tabelas a uma partilha
   • Adicionar volumes a uma partilha
   • Adicionar vistas a uma partilha
   • Adicionar modelos a uma partilha

7. Clique em Salvar e continuar.

8. No separador Adicionar blocos de notas, selecione os blocos de notas que pretende partilhar.

   Para obter instruções detalhadas, consulte Adicionar arquivos de bloco de anotações a um compartilhamento.

9. Clique em Salvar e continuar.

10. No separador Adicionar destinatários, selecione os destinatários com quem pretende partilhar.

    Para obter instruções detalhadas, consulte Gerenciar o acesso a compartilhamentos de dados do Delta Sharing (para provedores).

11. Clique em Compartilhar dados para compartilhar os dados com os destinatários.

SQL

Execute o seguinte comando em um bloco de anotações ou no editor de consultas Databricks SQL:

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

Agora você pode adicionar tabelas, volumes, exibições e modelos ao compartilhamento.

Para obter instruções detalhadas, consulte:

• Adicionar tabelas a uma partilha
• Adicionar volumes a uma partilha
• Adicionar vistas a uma partilha
• Adicionar modelos a uma partilha

CLI

Execute o seguinte comando 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, consulte as seções a seguir.

Agora você pode adicionar tabelas, volumes, exibições e modelos ao compartilhamento.

Para obter instruções detalhadas, consulte:

• Adicionar tabelas a uma partilha
• Adicionar volumes a uma partilha
• Adicionar vistas a uma partilha
• Adicionar modelos a uma partilha

Adicionar tabelas a uma partilha

Para adicionar tabelas a um compartilhamento, você pode usar o Gerenciador de Catálogos, a CLI do Catálogo Databricks Unity ou comandos SQL em um bloco de anotações do Azure Databricks ou no editor de consultas Databricks SQL.

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 SELECT privilégio na tabela. Você deve manter o SELECT privilégio pelo tempo que quiser compartilhar a tabela. Para obter mais informações, consulte Requisitos.

Explorador de Catálogos

1. No seu espaço de trabalho do Azure Databricks, clique em Catálogo.

2. Na parte superior do painel Catálogo, clique no ícone de engrenagem e selecione Compartilhamento Delta.

   Como alternativa, na página Acesso rápido , clique no botão Compartilhamento Delta > .

3. No separador Partilhado por mim, localize a partilha à qual pretende adicionar uma tabela e clique no respetivo nome.

4. Clique em Gerenciar ativos > Adicionar ativos de dados.

5. Na página Adicionar tabelas, selecione um esquema inteiro (banco de dados) ou tabelas e exibições individuais.

   • Para selecionar uma tabela ou 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 da coluna ou comentário usando a pesquisa do espaço de trabalho. Consulte Pesquisar objetos de 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.

6. (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 da tabela é 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 real da tabela se um alias for especificado.

   • Partição: Partilhe apenas parte da tabela. Por exemplo, (column = 'value'). Consulte Especificar partições de tabela para compartilhar e Usar propriedades de destinatário para fazer filtragem de partições.

   • Compartilhamento de histórico: compartilhe o histórico da tabela para permitir que os destinatários realizem consultas de viagem no tempo ou leiam a tabela com o Spark Structured Streaming. Requer Databricks Runtime 12.2 LTS ou superior.

     Nota

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

7. Clique em Guardar.

SQL

Execute o seguinte comando em um bloco de anotações 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 ADD SCHEMA comando requer um armazém SQL 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 estã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>): Se você quiser compartilhar apenas parte da tabela, você pode especificar uma partição. Por exemplo, (column = 'value') consulte Especificar partições de tabela para compartilhar e Usar propriedades de destinatário para fazer filtragem de partição.

• AS <alias>: Um nome de tabela alternativo ou 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 real da tabela se um alias for especificado. Utilize 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 Databricks Runtime 12.2 LTS ou superior.

  Nota

  Se, além de fazer consultas de viagem no tempo e leituras de streaming, você quiser que seus clientes possam consultar o feed de dados de alteração (CDF) 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 do 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"
        }
      }
    ]
  }'

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

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

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

Especificar partições de tabela para compartilhar

Para compartilhar apenas parte de uma tabela ao adicionar a tabela a um compartilhamento, você pode fornecer uma especificação de partição. Você pode especificar partições ao adicionar uma tabela a um compartilhamento ou atualizar um compartilhamento, usando o Catalog Explorer, a CLI do Databricks Unity Catalog ou comandos SQL em um bloco de anotações do Azure Databricks 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 na inventory tabela, particionados pelas yearcolunas , monthe date :

• Dados relativos ao 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");

Usar propriedades de 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 pertence um destinatário de dados (somente compartilhamento de Databricks para Databricks).
• databricks.metastoreId: O metastore do Unity Catalog ao qual um destinatário de dados pertence (somente compartilhamento de Databricks para Databricks).
• databricks.name: O nome do destinatário dos dados.

Você pode criar qualquer propriedade personalizada que desejar 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, espaços de trabalho e usuários do Databricks, mantendo os limites de dados entre eles.

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 à sua conta do Azure Databricks.

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 de destinatário ao criar ou atualizar um compartilhamento, você pode usar o Gerenciador de Catálogos ou a CURRENT_RECIPIENT função SQL em um bloco de anotações do Azure Databricks ou no editor de consultas Databricks SQL:

Explorador de Catálogos

1. No seu espaço de trabalho do Azure Databricks, clique em Catálogo.

2. Na parte superior do painel Catálogo, clique no ícone de engrenagem e selecione Compartilhamento Delta.

   Como alternativa, na página Acesso rápido , clique no botão Compartilhamento Delta > .

3. No separador Partilhado por mim, localize a partilha que pretende atualizar e clique no respetivo nome.

4. Clique em Gerenciar ativos > Adicionar ativos de dados.

5. Na página 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, você pode procurá-la por nome, nome da coluna ou comentário usando a pesquisa do espaço de trabalho. Consulte Pesquisar objetos de espaço de trabalho.

6. (Opcional) Clique em 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')
   

7. Clique em Guardar.

SQL

Execute o seguinte comando em um bloco de anotações 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 tabelas com vetores de exclusão ou mapeamento de coluna a um compartilhamento

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

O Azure Databricks também dá suporte ao mapeamento de colunas para tabelas Delta. Consulte Renomear e soltar colunas com o mapeamento de colunas Delta Lake.

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

Quando você compartilha uma tabela com vetores de exclusão ou mapeamento de coluna, os destinatários podem consultar a tabela usando um SQL warehouse, 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 Ler tabelas com vetores de exclusão ou mapeamento de coluna habilitado e Ler tabelas com vetores de exclusão ou mapeamento de coluna habilitado.

Adicionar vistas a uma partilha

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 e gerenciar modos de exibição.

Esta seção descreve como adicionar modos de exibição a um compartilhamento usando o Gerenciador de Catálogos, a CLI do Databricks ou comandos SQL em um bloco de anotações do Azure Databricks ou o editor de consultas SQL do Databricks. Se 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 USE CATALOG de compartilhamento e USE SCHEMA no catálogo e esquema que contêm o modo de exibição e SELECT no modo de exibição. Você deve manter o SELECT privilégio pelo tempo que quiser compartilhar a exibição. Para obter mais informações, consulte Requisitos.

Requisitos adicionais:

• A partilha de vistas só é suportada na partilha entre Databricks.
• As vistas partilháveis têm de ser definidas em tabelas Delta ou noutras vistas partilháveis.
• Não é possível partilhar vistas que façam referência a tabelas partilhadas ou vistas partilhadas.
• Você deve usar um SQL warehouse ou um cluster no Databricks Runtime 13.3 LTS ou superior ao adicionar um modo de exibição a um compartilhamento.
• Para conhecer os requisitos e limitações no uso de modos de exibição pelo destinatário, consulte Ler modos de exibição compartilhados.

Para adicionar vistas a uma partilha:

Explorador de Catálogos

1. No seu espaço de trabalho do Azure Databricks, clique em Catálogo.

2. Na parte superior do painel Catálogo, clique no ícone de engrenagem e selecione Compartilhamento Delta.

   Como alternativa, na página Acesso rápido , clique no botão Compartilhamento Delta > .

3. No separador Partilhado por mim, localize a partilha à qual pretende adicionar uma vista e clique no respetivo nome.

4. Clique em Gerenciar ativos > Adicionar ativos de dados.

5. Na página Adicionar tabelas, pesquise ou procure a vista que pretende partilhar e selecione-a.

6. (Opcional) Clique em Opções avançadas de tabela para especificar um alias, ou nome de modo 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 podem usar o nome do modo de exibição real se um alias for especificado.

7. Clique em Guardar.

SQL

Execute o seguinte comando em um bloco de anotações 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 de modo de exibição alternativo, ou alias, para tornar o nome do modo de exibição mais legível. O alias é o nome do modo de exibição que o destinatário vê e deve usar nas consultas. Os destinatários não podem usar o nome do modo de exibição real se um alias for especificado. Utilize o formato <schema-name>.<view-name>.
• COMMENT "<comment>": Os comentários aparecem na interface do usuário do Catalog Explorer e quando você lista e exibe detalhes de exibiçã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 modo de exibição alternativo, ou alias, para tornar o nome do modo de exibição mais legível. O alias é o nome do modo de exibição que o destinatário vê e deve usar nas consultas. Os destinatários não podem usar o nome do modo de exibição real se um alias for especificado. Utilize 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 da API REST.

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

Adicionar vistas dinâmicas a uma partilha para filtrar linhas e colunas

Você pode usar exibições dinâmicas para configurar o controle de acesso refinado aos dados da tabela, incluindo:

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

Ao criar um modo de exibição dinâmico que usa a função CURRENT_RECIPIENT(), você pode limitar o acesso do destinatário de acordo com as propriedades especificadas na definição de destinatário.

Esta seção fornece exemplos de como restringir o acesso do destinatário aos dados da tabela no nível da linha e da coluna usando uma exibição dinâmica.

Requisitos

• Versão do Databricks Runtime: A CURRENT_RECIPIENT função é suportada no Databricks Runtime 14.2 e superior.
• Permissões:
  • Para criar um modo de exibição, você deve ser o proprietário do objeto de compartilhamento, ter USE CATALOG e USE SCHEMA no catálogo e esquema que contêm o modo de exibição, juntamente com SELECT no modo de exibição. Você deve manter o SELECT privilégio 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 restrição ao compartilhamento de Databricks para Databricks, além do seguinte:
  • Quando um provedor compartilha um modo de exibição que usa a CURRENT_RECIPIENT função, o provedor não pode consultar o modo de exibição diretamente devido ao contexto de compartilhamento. Para testar essa exibição dinâmica, o provedor deve compartilhar a exibição consigo mesmo e consultar a exibição como um destinatário.
  • Os provedores não podem criar um modo de exibição que faça referência a um modo de exibição 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 correspondente country podem exibir determinadas linhas ou colunas.

Você pode definir propriedades de destinatário usando o Gerenciador de Catálogos ou comandos SQL em um bloco de anotações do Azure Databricks ou no editor de consultas SQL.

Explorador de Catálogos

1. No seu espaço de trabalho do Azure Databricks, clique em Catálogo.

2. Na parte superior do painel Catálogo, clique no ícone de engrenagem e selecione Compartilhamento Delta.

   Como alternativa, na página Acesso rápido , clique no botão Compartilhamento Delta > .

3. Na guia Destinatários, localize o destinatário ao qual você deseja adicionar as propriedades e clique em seu nome.

4. Clique em Editar propriedades.

5. Na caixa de diálogo Editar propriedades do destinatário, insira o nome da coluna como uma chave (neste casocountry) e o valor pelo qual você deseja filtrar como o valor (por exemplo, CA).

6. Clique em Guardar.

SQL

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

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

Criar uma vista dinâmica com permissão ao nível da linha para destinatários

Neste exemplo, apenas os destinatários com uma propriedade correspondente country 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 dissociados para maior flexibilidade.

Criar uma vista dinâmica com permissão ao nível da coluna para destinatários

Neste exemplo, apenas os destinatários que correspondem à country propriedade podem exibir determinadas colunas. Outros vêem os dados devolvidos 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;

Partilhar a vista dinâmica com um destinatário

Para compartilhar o modo de exibição dinâmico com um destinatário, use os mesmos comandos SQL ou procedimento de interface do usuário que faria para um modo de exibição padrão. Consulte Adicionar vistas a uma partilha.

Adicionar volumes a uma partilha

Os volumes são objetos do Unity Catalog que representam um volume lógico de armazenamento em um local de armazenamento de objetos na nuvem. Destinam-se principalmente a fornecer governança sobre ativos de dados não tabulares. Consulte O que são volumes do Catálogo Unity?.

Esta seção descreve como adicionar volumes a um compartilhamento usando o Gerenciador de Catálogos, a CLI do Databricks ou comandos SQL em um bloco de anotações do Azure Databricks ou editor de consultas SQL. Se 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 USE CATALOG de compartilhamento e USE SCHEMA no catálogo e esquema que contêm o volume e READ VOLUME no volume. Você deve manter o READ VOLUME privilégio pelo tempo que quiser compartilhar o volume. Para obter mais informações, consulte Requisitos.

Requisitos adicionais:

• A partilha de volumes só é suportada na partilha entre Databricks.
• Você deve usar um SQL warehouse na versão 2023.50 ou superior ou um cluster no Databricks Runtime 14.1 ou superior quando adicionar um volume a um compartilhamento.
• Se o armazenamento de volume no lado do provedor tiver configurações de rede personalizadas (como um firewall ou link privado), o provedor deverá garantir que o plano de controle e os endereços do plano de dados do destinatário estejam devidamente permitidos para poder se conectar ao local de armazenamento do volume.

Para adicionar volumes a uma partilha:

Explorador de Catálogos

1. No seu espaço de trabalho do Azure Databricks, clique em Catálogo.

2. Na parte superior do painel Catálogo, clique no ícone de engrenagem e selecione Compartilhamento Delta.

   Como alternativa, na página Acesso rápido , clique no botão Compartilhamento Delta > .

3. No separador Partilhado por mim, localize a partilha à qual pretende adicionar um volume e clique no respetivo nome.

4. Clique em Gerenciar ativos > Editar ativos.

5. Na página Editar ativos, pesquise ou procure o volume que deseja compartilhar e selecione-o.

   Como alternativa, você pode selecionar o esquema inteiro que contém o volume. Consulte Adicionar esquemas a um compartilhamento.

6. (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 podem usar o nome do volume real se um alias for especificado.

7. Clique em Guardar.

SQL

Execute o seguinte comando em um bloco de anotações 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 podem usar o nome do volume real se um alias for especificado. Utilize o formato <schema-name>.<volume-name>.
• COMMENT "<comment>": Os comentários aparecem na interface do usuário do Catalog Explorer 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 nas consultas. Os destinatários não podem usar o nome do volume real se um alias for especificado. Utilize 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 da API REST.

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

Adicionar modelos a uma partilha

Esta seção descreve como adicionar modelos a um compartilhamento usando o Gerenciador de Catálogos, a CLI do Databricks ou comandos SQL em um bloco de anotações do Azure Databricks ou editor de consultas SQL. Se 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 USE CATALOG de compartilhamento e USE SCHEMA no catálogo e esquema que contêm o modelo e EXECUTE no modelo. Você deve manter o EXECUTE privilégio pelo tempo que quiser compartilhar o modelo. Para obter mais informações, consulte Requisitos.

Requisitos adicionais:

• A partilha de modelos só é suportada na partilha entre Databricks.
• Você deve usar um SQL warehouse na versão 2023.50 ou superior ou um cluster no Databricks Runtime 14.0 ou superior ao adicionar um modelo a um compartilhamento.

Para adicionar modelos a um compartilhamento:

Explorador de Catálogos

1. No seu espaço de trabalho do Azure Databricks, clique em Catálogo.

2. Na parte superior do painel Catálogo, clique no ícone de engrenagem e selecione Compartilhamento Delta.

   Como alternativa, na página Acesso rápido , clique no botão Compartilhamento Delta > .

3. No separador Partilhado por mim, localize a partilha à qual pretende adicionar um modelo e clique no respetivo nome.

4. Clique em Gerenciar ativos > Editar ativos.

5. Na página Editar ativos, pesquise ou procure o modelo que deseja compartilhar e selecione-o.

   Como alternativa, você pode selecionar todo o esquema que contém o modelo. Consulte Adicionar esquemas a um compartilhamento.

6. (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 podem usar o nome do modelo real se um alias for especificado.

7. Clique em Guardar.

SQL

Execute o seguinte comando em um bloco de anotações 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 em consultas. Os destinatários não podem usar o nome do modelo real se um alias for especificado. Utilize 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 deve usar em consultas. Os destinatários não podem usar o nome do modelo real se um alias for especificado. Utilize 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 da API REST.

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

Adicionar esquemas a um compartilhamento

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ê cria o compartilhamento, mas a todos os ativos que são adicionados ao esquema ao longo do tempo. Isso inclui todas as tabelas, exibições e volumes no esquema. As tabelas partilhadas desta forma incluem sempre 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. Fazer o mesmo usando o Catalog Explorer não tem requisitos de computação.

Permissões necessárias: proprietário do objeto de compartilhamento e proprietário do esquema (ou um usuário com USE SCHEMA e SELECT privilégios 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 o esquema inteiro ao compartilhamento.

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

Adicionar ficheiros do bloco de notas a uma partilha

Use o Gerenciador de Catálogos para adicionar um arquivo de bloco de anotações a um compartilhamento.

Permissões necessárias: Proprietário do objeto de compartilhamento e permissão PODE LER no bloco de anotações que você deseja compartilhar.

1. No seu espaço de trabalho do Azure Databricks, clique em Catálogo.

2. Na parte superior do painel Catálogo, clique no ícone de engrenagem e selecione Compartilhamento Delta.

   Como alternativa, na página Acesso rápido , clique no botão Compartilhamento Delta > .

3. No separador Partilhado por mim, localize a partilha à qual pretende adicionar um bloco de notas e clique no respetivo nome.

4. Clique em Gerenciar ativos e selecione Adicionar arquivo de bloco de anotações.

5. Na página Adicionar ficheiro do bloco de notas, clique no ícone de ficheiro para procurar o bloco de notas que pretende partilhar.

   Clique no ficheiro que pretende partilhar e clique em Selecionar.

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

6. Clique em Guardar.

O arquivo de bloco de anotações compartilhado agora aparece na lista Arquivos de bloco de anotações na guia Ativos .

Remover ficheiros do bloco de notas das partilhas

Para remover um ficheiro de bloco de notas de uma partilha:

1. No seu espaço de trabalho do Azure Databricks, clique em Catálogo.

2. Na parte superior do painel Catálogo, clique no ícone de engrenagem e selecione Compartilhamento Delta.

   Como alternativa, na página Acesso rápido , clique no botão Compartilhamento Delta > .

3. No separador Partilhado por mim, localize a partilha que inclui o bloco de notas e clique no nome da partilha.

4. Na guia Ativos, localize o arquivo de bloco de anotações que você deseja remover do compartilhamento.

5. Clique no menu kebab à direita da linha e selecione Excluir arquivo do bloco de anotações.

6. Na caixa de diálogo de confirmação, clique em Excluir.

Atualizar arquivos do bloco de anotações em compartilhamentos

Para atualizar um bloco de notas que já partilhou, tem de voltar a adicioná-lo, dando-lhe um novo alias no campo Partilhar como . O Databricks recomenda que você use um nome que indique o status revisado do bloco de anotações, como <old-name>-update-1. Poderá ter de notificar o destinatário da alteração. O destinatário deve selecionar e clonar o novo bloco de anotações para aproveitar a atualização.

Conceder aos destinatários acesso a um compartilhamento

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

Permissões necessárias: uma das seguintes opções:

• Administrador da Metastore.
• Permissões delegadas ou propriedade nos objetos de compartilhamento e 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 Gerenciar o acesso a compartilhamentos de dados do Delta Sharing (para provedores). Este artigo também explica como revogar o acesso de um destinatário a um compartilhamento.

Ver partilhas e partilhar detalhes

Para exibir uma lista de compartilhamentos ou detalhes sobre um compartilhamento, você pode usar o Gerenciador de Catálogos, a CLI do Catálogo Unity do Databricks ou comandos SQL em um bloco de anotações do Azure Databricks ou no editor de consultas Databricks SQL.

Permissões necessárias: a lista de compartilhamentos retornados depende de sua função e permissões. Os administradores da Metastore e os usuários com o USE SHARE privilégio veem todos os compartilhamentos. Caso contrário, você pode exibir apenas os compartilhamentos dos quais você é o proprietário do objeto de compartilhamento.

Os detalhes incluem:

• O proprietário, criador, carimbo de data/hora de criação, atualizador, carimbo de data/hora atualizado, comentários.
• Ativos de dados no compartilhamento.
• Destinatários com acesso ao compartilhamento.

Explorador de Catálogos

1. No seu espaço de trabalho do Azure Databricks, clique em Catálogo.

2. Na parte superior do painel Catálogo, clique no ícone de engrenagem e selecione Compartilhamento Delta.

   Como alternativa, na página Acesso rápido , clique no botão Compartilhamento Delta > .

3. Abra a guia Compartilhamentos para exibir uma lista de compartilhamentos.

4. Veja os detalhes da partilha no separador Detalhes .

SQL

Para exibir uma lista de compartilhamentos, execute o seguinte comando em um bloco de anotações ou no editor de consultas Databricks SQL. Opcionalmente, substitua <pattern> por um LIKE predicado.

SHOW SHARES [LIKE <pattern>];

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

DESCRIBE SHARE <share-name>;

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

SHOW ALL IN SHARE <share-name>;

CLI

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

databricks shares list

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

databricks shares get <share-name>

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

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

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

Explorador de Catálogos

1. No seu espaço de trabalho do Azure Databricks, clique em Catálogo.

2. Na parte superior do painel Catálogo, clique no ícone de engrenagem e selecione Compartilhamento Delta.

   Como alternativa, na página Acesso rápido , clique no botão Compartilhamento Delta > .

3. Na guia Compartilhado por mim, localize e selecione o destinatário.

4. Vá para a guia Destinatários para exibir a lista de destinatários que podem acessar o compartilhamento.

SQL

Execute o seguinte comando em um bloco de anotações ou no editor de consultas Databricks SQL.

SHOW GRANTS ON SHARE <share-name>;

CLI

Execute o seguinte comando usando a CLI do Databricks.

databricks shares share-permissions <share-name>

Atualizar compartilhamentos

Além de adicionar tabelas, vistas, volumes e blocos de notas a uma partilha, pode:

• Renomeie um compartilhamento.
• Remova tabelas, exibições, volumes e esquemas de um compartilhamento.
• Adicione ou atualize um comentário em um compartilhamento.
• Habilite ou desabilite o acesso aos dados do histórico de uma tabela, permitindo que os destinatários realizem consultas de viagem no tempo ou leituras de streaming da tabela.
• Adicione, atualize ou remova definições de partição.
• Altere o proprietário da ação.

Para fazer essas atualizações em compartilhamentos, você pode usar o Gerenciador de Catálogos, a CLI do Catálogo Databricks Unity ou comandos SQL em um bloco de anotações do Azure Databricks ou no editor de consultas Databricks SQL. Não é possível usar o Catalog Explorer 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 privilégios e USE SHARE SET SHARE PERMISSION . Para atualizar o nome do compartilhamento, você deve ser um administrador de metastore (ou usuário com o privilégio) e proprietário do CREATE_SHARE compartilhamento. Para atualizar quaisquer outras propriedades compartilhadas, você deve ser o proprietário.

Explorador de Catálogos

1. No seu espaço de trabalho do Azure Databricks, clique em Catálogo.

2. Na parte superior do painel Catálogo, clique no ícone de engrenagem e selecione Compartilhamento Delta.

   Como alternativa, na página Acesso rápido , clique no botão Compartilhamento Delta > .

3. No separador Partilhado por mim, localize a partilha que pretende atualizar e clique no respetivo nome.

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

• Clique no ícone de edição ao lado do campo Proprietário ou Comentário para atualizar esses valores.
• Clique no botão de menu kebab em uma linha de ativos para removê-lo.
• 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 seguintes comandos em um bloco de anotações ou no editor SQL do Databricks.

Renomeie 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 sobre uma partilha:

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

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 ALTER SHARE parâmetros, consulte ALTER SHARE.

CLI

Execute os seguintes comandos usando a CLI do Databricks.

Renomeie 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>"
        }
      }
    ]
  }'

Adicionar ou atualizar um comentário sobre uma partilha:

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

Alterar proprietário da ação:

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

O principal deve ser um endereço de e-mail de usuário ou nome de grupo no nível da conta.

Excluir um compartilhamento

Para excluir um compartilhamento, você pode usar o Gerenciador de Catálogos, a CLI do Catálogo Unity do Databricks ou o DELETE SHARE comando SQL em um bloco de anotações do Azure Databricks ou o editor de consultas do Databricks SQL. Você deve ser um proprietário da ação.

Quando você exclui um compartilhamento, os destinatários não podem mais acessar os dados compartilhados.

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

Explorador de Catálogos

1. No seu espaço de trabalho do Azure Databricks, clique em Catálogo.

2. Na parte superior do painel Catálogo, clique no ícone de engrenagem e selecione Compartilhamento Delta.

   Como alternativa, na página Acesso rápido , clique no botão Compartilhamento Delta > .

3. No separador Partilhado por mim, localize a partilha que pretende eliminar e clique no respetivo nome.

4. Clique no menu kebab e selecione Excluir.

5. Na caixa de diálogo de confirmação, clique em Excluir.

SQL

Execute o seguinte comando em um bloco de anotações ou no editor de consultas Databricks SQL.

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

CLI

Execute o seguinte comando usando a CLI do Databricks.

databricks shares delete <share-name>