Crie e gerencie compartilhamentos para Delta Sharing

Este artigo explica como criar e gerenciar compartilhamentos para 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 mesa

  • view, incluindo view dinâmica que restringe o acesso no nível de linha e 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 do Unity Catalog. O senhor pode adicionar ou remover dados e IA ativo de um compartilhamento a qualquer momento.

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

Requisitos

Para criar um compartilhamento, você deve:

  • Seja um administrador do metastore ou tenha o privilégio CREATE SHARE para o metastore Unity Catalog onde os dados que você deseja compartilhar estão registrados.

  • Crie o compartilhamento usando um workspace do Databricks que tenha esse metastore Unity Catalog anexado.

Para adicionar tabelas ou view a um compartilhamento, você deve:

  • Seja o proprietário das ações.

  • Ter os privilégios USE CATALOG e USE SCHEMA no catálogo e esquema que contém a tabela ou view ou propriedade do catálogo ou esquema.

  • Tenha o privilégio SELECT na tabela ou view. Você deve manter esse privilégio para que a tabela ou view continue a ser compartilhada. Se você perdê-lo, o destinatário não poderá acessar a tabela ou view através do compartilhamento. A Databricks recomenda, portanto, que utilize um grupo como proprietário da partilha.

Para adicionar volumes a um compartilhamento, você deve:

  • Seja o proprietário das ações.

  • Tenha os privilégios USE CATALOG e USE SCHEMA no catálogo e esquema que contém o volume ou propriedade do catálogo ou esquema.

  • Tenha o privilégio READ VOLUME no volume. Você deve manter esse privilégio para que o volume continue a ser compartilhado. Se você perdê-lo, o destinatário não poderá acessar o volume por meio do compartilhamento. A Databricks recomenda, portanto, que utilize um grupo como proprietário da partilha.

Para adicionar modelos a um compartilhamento, você deve:

  • Seja o proprietário das ações.

  • Tenha os privilégios USE CATALOG e USE SCHEMA no catálogo e esquema que contém o modelo ou propriedade do catálogo ou esquema.

  • Tenha o privilégio EXECUTE 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. A Databricks recomenda, portanto, que utilize um grupo como proprietário da partilha.

Para compartilhar um esquema inteiro, você deve:

  • Ser o proprietário do compartilhamento e do esquema ou ter USE SCHEMA.

  • Tenha SELECT no esquema para compartilhar tabelas.

  • Tenha READ VOLUME no esquema para compartilhar volumes.

Para adicionar arquivos Notebook a um compartilhamento, você deve:

  • O proprietário da ação e o senhor têm permissão CAN READ no site Notebook.

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

  • Administrador de metastore.

  • Usuário com permissões ou propriedade delegada no compartilhamento e nos objetos destinatários ((USE SHARE + SET SHARE PERMISSION) ou proprietário do compartilhamento) E (USE RECIPIENT ou proprietário destinatário).

Para view os compartilhamentos, você deve ser um destes:

  • Um administrador metastore (pode view tudo)

  • Um usuário com o privilégio USE SHARE (pode view tudo)

  • O proprietário do objeto de compartilhamento

requisitos compute :

  • Se você usar um Databricks Notebook para criar o compartilhamento, seus clusters deverão usar o Databricks Runtime 11.3 LTS ouacima e o modo de acesso clusters compartilhados ou de usuário único.

  • 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, você pode usar o Catalog Explorer, a CLI Unity Catalog ou o comando SQL CREATE SHARE em um Notebook do Databricks ou no editor query Databricks SQL .

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

  1. No seu workspace do Databricks, clique em Ícone de catálogo Catálogo.

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

    Como alternativa, na página de acesso rápido, clique no botão Delta Sharing >.

  3. Em Shared by me (Compartilhado por mim ) tab, clique no botão Share data (Compartilhar dados ).

  4. Na página Criar compartilhamento, digite o Nome do compartilhamento e um comentário opcional.

  5. Clique em Save (Salvar) e continue.

    O senhor pode continuar a adicionar dados ativos ou pode parar e voltar mais tarde.

  6. Em Add data ativo tab, selecione as tabelas, volumes, visualizações e modelos que deseja compartilhar.

    Para obter instruções detalhadas, consulte:

  7. Clique em Save (Salvar) e continue.

  8. Em Add Notebook tab, selecione o Notebook que deseja compartilhar.

    Para obter instruções detalhadas, consulte Adicionar arquivos Notebook a um compartilhamento.

  9. Clique em Save (Salvar) e continue.

  10. 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).

  11. Clique em Share data (Compartilhar dados ) para compartilhar os dados com os destinatários.

execução do seguinte comando em um Notebook ou no editor query 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:

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 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

Para adicionar tabelas a um compartilhamento, você pode usar o Catalog Explorer, a CLI Unity Catalog ou comandos SQL em um Notebook do Databricks ou no editor query Databricks SQL .

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

Observação

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

  1. No seu workspace do Databricks, clique em Ícone de catálogo Catálogo.

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

    Como alternativa, na página de acesso rápido, clique no botão Delta Sharing >.

  3. No Shared by me tab, localize o compartilhamento ao qual deseja adicionar uma tabela e clique em seu 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 individuais e view.

    • Para selecionar uma tabela ou view, primeiro selecione o catálogo, depois o esquema que contém a tabela ou view, em seguida, a própria tabela ou view .

      Você pode pesquisar tabelas por nome, nome da coluna ou comentário usando a pesquisa workspace . Consulte Procurar objetos workspace .

    • Para selecionar um esquema, primeiro selecione o catálogo e depois o esquema.

      Para obter informações detalhadas sobre o compartilhamento de esquemas, consulte Adicionar esquemas a um compartilhamento.

  6. (Opcional) Clique em Opções de tabela avançadas para especificar as opções a seguir. Alias e partições não estarão disponíveis se você selecionar um esquema inteiro. A tabela história é incluída por default 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 na query. Os destinatários não poderão usar o nome real da tabela se um alias for especificado.

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

    • história compartilhamento: Compartilhe a tabela história para permitir que os destinatários realizem consultas de viagem do tempo ou leiam a tabela com Spark transmissão estructurada. É necessário o site Databricks Runtime 12.2 LTS ou acima.

      Observação

      Se, além de fazer consultas de query do tempo e leituras de transmissão, você deseja que seus clientes possam query o change data feed (CDF) de uma tabela usando a função table_changes(), você deve habilitar o CDF na tabela antes de compartilhá-lo WITH HISTORY.

  7. Clique em Salvar.

execução do seguinte comando em um Notebook ou no editor query 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 você selecionar um esquema inteiro. WITH HISTORY é selecionado por default para todas as tabelas se você selecionar um esquema inteiro.

  • PARTITION(<clause>): Se você deseja compartilhar apenas parte da tabela, 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 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. 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 query do tempo e leituras de transmissão, você deseja que seus clientes possam query o change data feed (CDF) de uma tabela usando a função table_changes(), você deve habilitar o CDF na tabela antes de compartilhá-lo WITH HISTORY.

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

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

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

Observação

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

Para saber mais sobre as opções listadas neste exemplo, view as instruções na tab 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.

Especifique 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 Unity Catalog CLI ou o comando SQL em um do Databricks Notebook ou no Databricks SQL query editor . Consulte Adicionar tabelas a um compartilhamento e Atualizar compartilhamentos.

Exemplo básico

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

  • Dados do ano de 2021.

  • Dados de dezembro de 2020.

  • Dados de 25 de dezembro de 2019.

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

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

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

as propriedades default incluem:

  • databricks.accountId: a account do Databricks à qual um destinatário de dados pertence (somente compartilhamento de Databricks para Databricks).

  • databricks.metastoreId: o metastore 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 do destinatário permite que você compartilhe as mesmas tabelas, usando o mesmo compartilhamento, em várias account, workspace e usuários do Databricks, mantendo os limites de dados entre eles.

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

Diagrama de compartilhamento dinâmico de partições baseado em parâmetros no Delta Sharing

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 Catalog Explorer ou a função SQL CURRENT_RECIPIENT em um Notebook do Databricks ou no editor query Databricks SQL :

Observação

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

  1. No seu workspace do Databricks, clique em Ícone de catálogo Catálogo.

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

    Como alternativa, na página de acesso rápido, clique no botão Delta Sharing >.

  3. Em Shared by me (Compartilhado por mim ) tab, localize o compartilhamento que deseja atualizar e clique em seu 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 selecione a tabela.

    Se não tiver certeza de qual catálogo e banco de dados contém a tabela, você pode pesquisá-la por nome, nome da coluna ou comentário usando a pesquisa workspace . Consulte Procurar objetos workspace .

  6. (Opcional) Clique em Opções de tabela avançadas para adicionar especificações de partição .

    Na caixa de diálogo Adicionar partição a uma tabela , adicione a especificação de partição baseada em propriedade usando a seguinte sintaxe:

    (<column-name> = CURRENT_RECIPIENT().<property-key>)
    

    Por exemplo,

    (country = CURRENT_RECIPIENT().'country')
    
  7. Clique em Salvar.

execução do seguinte comando em um Notebook ou no editor query 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 colunas a um compartilhamento

Visualização

Este recurso está em visualização pública.

Os vetores de exclusão são um recurso de otimização de armazenamento que o senhor pode ativar nas tabelas Delta. Consulte O que são vetores de exclusão?

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

Para compartilhar uma tabela com vetores de exclusão ou mapeamento de colunas, o senhor deve compartilhá-la com a história. Consulte Adicionar tabelas a um compartilhamento.

Quando o senhor 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 Databricks Runtime 14.1 ou acima, ou compute que esteja executando código aberto delta-sharing-spark 3.1 ou acima. Consulte Ler tabelas com vetores de exclusão ou mapeamento de colunas ativ ado e Ler tabelas com vetores de exclusão ou mapeamento de colunas ativado.

Adicionar visualizações a um compartilhamento

Visualização

Este recurso está em visualização 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 view a um compartilhamento usando o Catalog Explorer, a CLI do Databricks ou o comando SQL em um Notebook do Databricks ou no editor de consultas Databricks SQL . Se você preferir usar a API REST 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 esquema que contém a view e SELECT na view. Você deve manter o privilégio SELECT enquanto quiser compartilhar a view. Para mais informações, consulte Requisitos.

Requisitos adicionais:

  • o compartilhamento view tem suporte apenas no compartilhamento Databricks-para-Databricks.

  • view compartilhável deve ser definida em tabelas Delta ou outra view compartilhável.

  • Você não pode compartilhar view que façam referência a tabelas compartilhadas ou view 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 requisitos e limitações no uso de exibições pelo destinatário, consulte Ler exibições compartilhadas.

Para adicionar view a um compartilhamento:

  1. No seu workspace do Databricks, clique em Ícone de catálogo Catálogo.

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

    Como alternativa, na página de acesso rápido, clique no botão Delta Sharing >.

  3. No Shared by me tab, localize o compartilhamento ao qual deseja adicionar um view e clique em seu nome.

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

  5. Na página Adicionar tabelas , pesquise ou navegue até a view que deseja compartilhar e selecione-a.

  6. (Opcional) Clique em Opções de tabela avançadas para especificar um Alias ou nome view alternativo para tornar o nome da view mais legível. O alias é o nome que o destinatário vê e deve usar na query. Os destinatários não podem usar o nome de view real se um alias for especificado.

  7. Clique em Salvar.

execução do seguinte comando em um Notebook ou no editor query 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 view alternativo, 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 poderão usar o nome view real se um alias for especificado. Use o formato <schema-name>.<view-name>.

  • COMMENT "<comment>": os comentários aparecem na UI do Catalog Explorer e quando você lista e exibe detalhes view usando instruções SQL.

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

execute o seguinte comando 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 view alternativo, 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 poderão usar o nome view real se um alias for especificado. Use o formato <schema-name>.<view-name>.

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

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

Adicione view dinâmica a um compartilhamento para filtrar linhas e colunas

Visualização

Este recurso está em visualização pública.

Você pode usar view dinâmica 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 uma view dinâmica que usa a função CURRENT_RECIPIENT(), você 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 como restringir o acesso do destinatário aos dados da tabela no nível de linha e coluna usando uma view dinâmica.

Requisitos

  • Versão do Databricks Runtime: a função CURRENT_RECIPIENT tem suporte no Databricks Runtime 14.2 e acima.

  • Permissões:

    • Para criar uma view, você deve ser o proprietário do objeto de compartilhamento, ter USE CATALOG e USE SCHEMA no catálogo e esquema que contém a view, juntamente com SELECT na view. Você deve manter o privilégio SELECT enquanto quiser compartilhar a view.

    • Para definir propriedades em um destinatário, você deve ser o proprietário do objeto de destinatário.

  • Limitações: Todas as limitações para compartilhamento deview , incluindo restrição ao compartilhamento de Databricks para Databricks, além do seguinte:

    • Quando um provedor compartilha uma view que usa a função CURRENT_RECIPIENT, o provedor não pode consultar a view diretamente devido ao contexto de compartilhamento. Para testar essa view dinâmica, o provedor deve compartilhar a view consigo mesmo e consultá- view como destinatário.

    • Os provedores não podem criar uma view que faça referência a uma view dinâmica.

Definir uma propriedade de destinatário

Nestes exemplos, a tabela a ser compartilhada possui uma coluna chamada country e somente destinatários com uma propriedade country correspondente podem view determinadas linhas ou colunas.

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

  1. No seu workspace do Databricks, clique em Ícone de catálogo Catálogo.

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

    Como alternativa, na página de acesso rápido, clique no botão Delta Sharing >.

  3. Na Destinatários tab, encontre o destinatário ao qual 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 key (neste caso, country) e o valor que você deseja filtrar como valor (por exemplo, CA).

  6. Clique em Salvar.

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

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

Crie uma visualização dinâmica com permissão em nível de linha para destinatários

Neste exemplo, somente destinatários com uma propriedade country correspondente podem 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 é o provedor de dados manter 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.

Crie uma visualização dinâmica com permissão em nível de coluna para destinatários

Neste exemplo, apenas 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;

Compartilhe a visualização dinâmica com um destinatário

Para compartilhar a view dinâmica com um destinatário, use o mesmo comando SQL ou procedimento de UI que você usaria para uma view padrão. Consulte Adicionar view a um compartilhamento.

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, a CLI do Databricks ou o comando SQL em um Notebook do Databricks ou editor de consulta SQL. Se você preferir usar a API REST 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 esquema que contém o volume e READ VOLUME no volume. Você deve manter o privilégio READ VOLUME enquanto quiser compartilhar o volume. Para mais informações, consulte Requisitos.

Requisitos adicionais:

  • O compartilhamento de volume tem suporte apenas no compartilhamento de Databricks para Databricks.

  • Você deve usar um SQL warehouse na versão 2023.50 ou acima ou clusters no Databricks Runtime 14.1 ou acima ao 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:

  1. No seu workspace do Databricks, clique em Ícone de catálogo Catálogo.

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

    Como alternativa, na página de acesso rápido, clique no botão Delta Sharing >.

  3. Em Shared by me (Compartilhado por mim ) tab, localize o compartilhamento ao qual deseja adicionar um volume e clique em seu nome.

  4. Clique em gerenciamento ativo > Editar ativo.

  5. Na página Editar ativo , pesquise ou navegue até o volume que deseja compartilhar e selecione-o.

    Como alternativa, você pode selecionar todo o esquema 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 nas consultas. Os destinatários não poderão usar o nome real do volume se um alias for especificado.

  7. Clique em Salvar.

execução do seguinte comando em um Notebook ou no editor query 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 UI 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.

execute o seguinte comando usando Databricks CLI 0.210 ou acima:

 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 da API REST.

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

Adicionar modelos a um compartilhamento

Visualização

Este recurso está em visualização pública.

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

Requisitos adicionais:

  • O compartilhamento de modelo tem suporte apenas no compartilhamento de Databricks para Databricks.

  • Você deve usar um SQL warehouse na versão 2023.50 ou acima ou clusters no Databricks Runtime 14.0 ou acima ao adicionar um modelo a um compartilhamento.

Para adicionar modelos a um compartilhamento:

  1. No seu workspace do Databricks, clique em Ícone de catálogo Catálogo.

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

    Como alternativa, na página de acesso rápido, clique no botão Delta Sharing >.

  3. Em Shared by me (Compartilhado por mim ) tab, localize o compartilhamento ao qual deseja adicionar um modelo e clique em seu nome.

  4. Clique em gerenciamento ativo > Editar ativo.

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

    Alternativamente, 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 nas consultas. Os destinatários não poderão usar o nome do modelo real se um alias for especificado.

  7. Clique em Salvar.

execução do seguinte comando em um Notebook ou no editor query 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 poderão usar o nome do modelo real se um alias for especificado. Use o formato <schema-name>.<model-name>.

  • COMMENT "<comment>": os comentários aparecem na UI 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.

execute o seguinte comando usando Databricks CLI 0.210 ou acima:

 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 poderão usar o nome do modelo real 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 da API REST.

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

Adicionar esquemas a um compartilhamento

Visualização

Este recurso está em visualização pública.

Quando você adiciona um esquema inteiro a um compartilhamento, seus destinatários terão acesso não apenas a todos os dados ativos no esquema no momento em que você cria o compartilhamento, mas também a todos os dados ativos que forem adicionados ao esquema ao longo do tempo. Isso inclui todas as tabelas, view e volumes no esquema. As tabelas compartilhadas desta forma sempre incluem a história completa.

Adicionar, atualizar ou remover um esquema usando SQL requer um SQL warehouse ou compute executando Databricks Runtime 13.3 LTS ou acima. Fazer o mesmo usando o Catalog Explorer não tem requisitos do site compute.

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

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

Aliases de tabela, partições e aliases de volume não estarão disponíveis se você selecionar um esquema inteiro. Se você criou aliases ou partições para algum ativo 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ê deverá compartilhar a tabela ou volume usando SQL e fornecer à tabela ou ao volume um alias com um nome de esquema diferente.

Adicionar arquivos Notebook a um compartilhamento

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

Observação

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

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

  1. No seu workspace do Databricks, clique em Ícone de catálogo Catálogo.

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

    Como alternativa, na página de acesso rápido, clique no botão Delta Sharing >.

  3. No Shared by me tab, localize o compartilhamento ao qual deseja adicionar um Notebook e clique em seu nome.

  4. Clique em gerenciar ativos e selecione Adicionar arquivo Notebook .

  5. Na página Adicionar arquivo de Notebook , clique no ícone do arquivo para procurar o Notebook que deseja compartilhar.

    Clique no arquivo que deseja compartilhar 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 Salvar.

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

Remover arquivos Notebook dos compartilhamentos

Para remover um arquivo Notebook de um compartilhamento:

  1. No seu workspace do Databricks, clique em Ícone de catálogo Catálogo.

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

    Como alternativa, na página de acesso rápido, clique no botão Delta Sharing >.

  3. Em Shared by me (Compartilhado por mim ) tab, localize o compartilhamento que inclui o Notebook e clique no nome do compartilhamento.

  4. Na tab ativo , localize o arquivo Notebook que deseja remover do compartilhamento.

  5. Clique no menu Menu Kebab kebab à direita da linha e selecione Delete Notebook file (Excluir arquivo).

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

Atualizar arquivos Notebook em compartilhamentos

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

Conceder aos destinatários acesso a um compartilhamento

Para conceder acesso de compartilhamento aos destinatários, você pode usar o Catalog Explorer, a CLI Unity Catalog ou o comando SQL GRANT ON SHARE em um Notebook do Databricks ou no editor query Databricks SQL .

Permissões necessárias: Uma das seguintes:

  • Administrador de metastore.

  • Permissões ou propriedade delegadas no compartilhamento e nos objetos do 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 aos 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 compartilhamentos e detalhes de compartilhamento

Para view uma lista de compartilhamentos ou detalhes sobre um compartilhamento, você pode usar o Catalog Explorer, a CLI Unity Catalog ou comandos SQL em um Notebook do Databricks ou no editor query Databricks SQL .

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

Os detalhes incluem:

  • Proprietário do compartilhamento, criador, registro de data e hora de criação, atualizador, registro de data e hora atualizado, comentários.

  • Dados ativos no compartilhamento.

  • Destinatários com acesso ao compartilhamento.

  1. No seu workspace do Databricks, clique em Ícone de catálogo Catálogo.

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

    Como alternativa, na página de acesso rápido, clique no botão Delta Sharing >.

  3. Abra a tab Compartilhamentos para view uma lista de compartilhamentos.

  4. view os detalhes do compartilhamento na tab Detalhes.

Para view uma lista de compartilhamentos, execute o seguinte comando em um Notebook ou no editor query Databricks SQL . Opcionalmente, substitua <pattern> por um predicado `LIKE`.

SHOW SHARES [LIKE <pattern>];

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

DESCRIBE SHARE <share-name>;

Para view detalhes sobre todas as tabelas, view e volumes em um compartilhamento, execute o comando a seguir.

SHOW ALL IN SHARE <share-name>;

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

databricks shares list

Para view 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 view a lista de compartilhamentos aos quais um destinatário recebeu acesso, você pode usar o Catalog Explorer, a CLI Unity Catalog ou o comando SQL SHOW GRANTS TO RECIPIENT em um Notebook do Databricks ou no editor query Databricks SQL .

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

  1. No seu workspace do Databricks, clique em Ícone de catálogo Catálogo.

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

    Como alternativa, na página de acesso rápido, clique no botão Delta Sharing >.

  3. No Shared by me tab, localize e selecione o destinatário.

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

execução do seguinte comando em um Notebook ou no editor query Databricks SQL .

SHOW GRANTS ON SHARE <share-name>;

execute o seguinte comando usando a CLI do Databricks.

databricks shares share-permissions <share-name>

Atualizar compartilhamentos

Além de adicionar tabelas, view, volumes e Notebook a um compartilhamento, você pode:

  • Renomeie um compartilhamento.

  • Remova tabelas, view, volumes e esquemas de um compartilhamento.

  • Adicione ou atualize um comentário em um compartilhamento.

  • Habilite ou desabilite o acesso aos dados da história de uma tabela, permitindo que os destinatários realizem query de viagem do tempo ou leituras transmitidas da tabela.

  • Adicionar, atualizar ou remover definições de partição.

  • Altere o proprietário do compartilhamento.

Para fazer essas atualizações em compartilhamentos, você pode usar o Catalog Explorer, a CLI Unity Catalog ou comandos SQL em um Notebook do Databricks ou no editor query Databricks SQL . Você não pode 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 metastore, o proprietário do objeto de compartilhamento ou um usuário com os privilégios USE SHARE e SET SHARE PERMISSION . Para atualizar o nome do compartilhamento, você deve ser um administrador metastore (ou usuário com o privilégio CREATE_SHARE ) e proprietário do compartilhamento. Para atualizar quaisquer outras propriedades de compartilhamento, você deve ser o proprietário.

  1. No seu workspace do Databricks, clique em Ícone de catálogo Catálogo.

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

    Como alternativa, na página de acesso rápido, clique no botão Delta Sharing >.

  3. 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 Editar ícone ícone de edição ao lado do campo Proprietário ou Comentário para atualizar esses valores.

  • Clique no botão do menu kebab Menu Kebab em uma linha ativa para removê-lo.

  • Clique em gerenciamento ativo > Editar 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.

execução dos seguintes comandos 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>';

Adicione ou modifique partições para uma tabela em um compartilhamento:

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

Alterar proprietário do compartilhamento:

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

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

Habilite o compartilhamento de história para uma mesa:

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 a CLI do Databricks.

Renomear um compartilhamento:

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

Remover tabelas de um compartilhamento:

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

Remova 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 nenhum 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 proprietário do compartilhamento:

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

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

Excluir um compartilhamento

Para excluir um compartilhamento, você pode usar o Catalog Explorer, a CLI Unity Catalog ou o comando SQL DELETE SHARE em um Notebook do Databricks ou no editor query Databricks SQL . Você deve ser o 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: Compartilhe o proprietário do objeto.

  1. No seu workspace do Databricks, clique em Ícone de catálogo Catálogo.

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

    Como alternativa, na página de acesso rápido, clique no botão Delta Sharing >.

  3. Em Shared by me (Compartilhado por mim ) tab, localize o compartilhamento que deseja excluir e clique em seu nome.

  4. Clique no menu Menu Kebab kebab e selecione Delete (Excluir).

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

execução do seguinte comando em um Notebook ou no editor query Databricks SQL .

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

execute o seguinte comando usando a CLI do Databricks.

databricks shares delete <share-name>