Criar e gerenciar compartilhamentos para o Compartilhamento Delta

Esta página explica como criar e gerenciar compartilhamentos para o Delta Sharing.

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

• Tabelas e partições de tabelas
• Tabelas de streaming
• Tabelas Iceberg Gerenciadas
• Esquemas e tabelas estrangeiras
• Exibições, incluindo exibições dinâmicas que restringem o acesso em nível de linha e coluna
• Visões materializadas
• Volumes
• Notebooks
• Modelos de IA

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

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

Antes de criar um compartilhamento, verifique se você configurou o Compartilhamento Delta para sua conta (para provedores).

Para saber mais sobre o modelo de compartilhamento, consulte Compartilhamentos, provedores e destinatários.

Requirements

Verifique se você atende aos requisitos listados para cada tarefa que deseja concluir.

Requisitos de computação

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

Criar um objeto de compartilhamento

Verifique se você atende aos requisitos antes de criar um objeto de compartilhamento.

Para criar um compartilhamento, use o Catalog Explorer, a CLI do Unity Catalog do Databricks ou o CREATE SHARE comando SQL em um notebook do Azure Databricks ou no editor de consultas SQL do Databricks.

Gerenciador de Catálogos

1. No workspace do Azure Databricks, clique no Catálogo.

2. Na parte superior do painel Catálogo, clique no 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 compartilhamento, insira o Nome 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 os ativos de dados que você deseja compartilhar.

   Para obter instruções detalhadas, requisitos adicionais e limitações relacionadas, consulte:

   • Adicionar tabelas a um compartilhamento
   • Adicionar tabelas de streaming a um compartilhamento
   • Adicionar tabelas de Iceberg gerenciadas a um compartilhamento
   • Adicionar esquemas ou tabelas estrangeiras a um compartilhamento
   • Adicionar volumes a um compartilhamento
   • Adicionar vistas a um compartilhamento
   • Adicionar exibições materializadas a um compartilhamento
   • Adicionar modelos a um compartilhamento

7. Clique em Salvar e continuar.

8. Na guia Adicionar notebooks, selecione os notebooks que deseja compartilhar.

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

9. Clique em Salvar e continuar.

10. Na guia Adicionar destinatários, selecione os destinatários com os quais você deseja compartilhar.

    Para obter instruções detalhadas, confira Gerenciar o acesso aos compartilhamentos de dados do Compartilhamento Delta (para provedores).

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

SQL

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

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

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

Para obter instruções detalhadas, requisitos adicionais e limitações relacionadas, consulte:

• Adicionar tabelas a um compartilhamento
• Adicionar tabelas de streaming a um compartilhamento
• Adicionar tabelas de Iceberg gerenciadas a um compartilhamento
• Adicionar esquemas ou tabelas estrangeiras a um compartilhamento
• Adicionar volumes a um compartilhamento
• Adicionar vistas a um compartilhamento
• Adicionar exibições materializadas a um compartilhamento
• Adicionar modelos a um compartilhamento

CLI

Execute o comando a seguir usando a CLI do Databricks.

databricks shares create <share-name>

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

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

Para obter instruções detalhadas, requisitos adicionais e limitações relacionadas, consulte:

• Adicionar tabelas a um compartilhamento
• Adicionar tabelas de streaming a um compartilhamento
• Adicionar tabelas de Iceberg gerenciadas a um compartilhamento
• Adicionar esquemas ou tabelas estrangeiras a um compartilhamento
• Adicionar volumes a um compartilhamento
• Adicionar vistas a um compartilhamento
• Adicionar exibições materializadas a um compartilhamento
• Adicionar modelos a um compartilhamento

Adicionar tabelas a um compartilhamento

Verifique se você atende aos requisitos antes de adicionar tabelas a um compartilhamento.

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

Para adicionar tabelas a um compartilhamento, use o Catalog Explorer, a CLI do Catálogo do Databricks Unity ou os comandos SQL em um notebook do Azure Databricks ou no editor de consultas SQL do Databricks.

Gerenciador de Catálogos

1. No workspace do Azure Databricks, clique no Catálogo.

2. Na parte superior do painel Catálogo, clique no 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 o compartilhamento ao qual você deseja adicionar uma tabela e clique no nome dele.

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.

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

     Você pode pesquisar tabelas por nome, nome de coluna ou comentário usando a pesquisa de espaço de trabalho. Consulte Pesquisa de objetos do espaço de trabalho.

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

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

6. Histórico: compartilhe o histórico da tabela para permitir que os destinatários executem consultas de viagem no tempo ou leiam a tabela com o Streaming Estruturado do Spark. Para compartilhamentos entre Databricks, o log Delta da tabela também é compartilhado para aprimorar a performance. Confira Melhorar o desempenho de leitura da tabela com o compartilhamento de histórico. O compartilhamento de histórico requer o Databricks Runtime 12.2 LTS ou superior.

   Note

   Se você também quiser que seus clientes possam consultar o CDF (feed de dados de alteração) de uma tabela usando a função table_changes(),habilite o CDF na tabela antes de compartilhá-lo WITH HISTORY.

7. (Opcional) Clique em nas colunas Alias ou Partição para adicionar um alias ou partição. Alias e partições não estarão disponíveis se você selecionar um esquema inteiro. O histórico de tabelas será incluído por padrão se você selecionar um esquema inteiro.

   • Alias: um nome de tabela alternativo para tornar o nome da tabela mais legível. O alias é o nome da tabela que o destinatário vê e deve usar nas consultas. Os destinatários não podem usar o nome da tabela real quando um alias foi especificado.
   • Partição: compartilhe apenas parte da tabela. Por exemplo, (column = 'value'). Consulte Especificar partições de tabela para compartilhar e Usar propriedades de destinatário para fazer a filtragem de partição.

8. Clique em Salvar.

SQL

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

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

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

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

As opções incluem o seguinte. PARTITION e AS <alias> não estarão disponíveis se você selecionar um esquema inteiro.

• PARTITION(<clause>): para compartilhar somente parte da tabela, é possível especificar uma partição. Por exemplo, (column = 'value') Consulte Especificar partições de tabela para compartilhar e Usar propriedades de destinatário para fazer a filtragem de partição.

• AS <alias>: um nome de tabela alternativo ou um Alias para tornar o nome da tabela mais legível. O alias é o nome da tabela que o destinatário vê e deve usar nas consultas. Os destinatários não podem usar o nome da tabela real quando um alias foi especificado. Use o formato <schema-name>.<table-name>.

• WITH HISTORY ou WITHOUT HISTORY: quando WITH HISTORY for especificado, compartilhe a tabela com o histórico completo, permitindo que os destinatários realizem consultas de viagem no tempo e leituras de streaming. Para compartilhamentos entre Databricks, o compartilhamento do histórico também compartilha o log Delta da tabela para aprimorar a performance. O comportamento padrão do compartilhamento de tabela é WITH HISTORY se a computação estiver executando o Databricks Runtime 16.2 ou superior e WITHOUT HISTORY para versões anteriores do Databricks Runtime. Para o compartilhamento de esquema, o padrão é WITH HISTORY independentemente da versão do Databricks Runtime. WITH HISTORY e WITHOUT HISTORY exigem o Databricks Runtime 12.2 LTS ou superior. Confira também Melhorar o desempenho de leitura da tabela com o compartilhamento de histórico.

  Note

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

Para saber mais sobre as opções de ALTER SHARE, consulte ALTER SHARE.

CLI

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

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

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

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

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

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

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

Especificar partições de tabela para compartilhamento

Para compartilhar apenas parte de uma tabela quando você adicionar a tabela a um compartilhamento, forneça uma especificação de partição. Especifique partições ao adicionar uma tabela a um compartilhamento ou atualizar um compartilhamento usando o Catalog Explorer, a CLI do Catálogo do Databricks Unity ou os comandos SQL em um notebook do Azure Databricks ou no editor de consultas SQL do Databricks. Confira Adicionar tabelas a um compartilhamento e Atualizar compartilhamentos.

Example

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

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

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

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

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

As propriedades padrão incluem:

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

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

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

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

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

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

Gerenciador de Catálogos

1. No workspace do Azure Databricks, clique no Catálogo.

2. Na parte superior do painel Catálogo, clique no 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 o compartilhamento que você deseja atualizar e clique no nome dele.

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 você não tiver certeza de qual catálogo e banco de dados contêm a tabela, poderá pesquisá-la por nome, nome da coluna ou comentário usando a pesquisa de workspace. Consulte Pesquisa de objetos do espaço de trabalho.

6. (Opcional) Clique em na coluna Partição para adicionar uma partição.

   Na caixa de diálogo Adicionar partição à 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.

SQL

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

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

Por exemplo

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

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 nas tabelas Delta. Confira O que são vetores de exclusão?

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

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

Quando você compartilha uma tabela com vetores de exclusão ou mapeamento de coluna, os destinatários podem consultar a tabela usando um SQL warehouse, um ambiente de computação executando o Databricks Runtime 14.1 ou superior, ou um ambiente de computação que está executando o open source delta-sharing-spark 3.1 ou superior. Consulte tabelas de leitura com vetores de exclusão ou mapeamento de coluna habilitado e tabelas de leitura com vetores de exclusão ou mapeamento de coluna habilitado.

Adicionar esquemas a um compartilhamento

Verifique se você atende aos requisitos antes de adicionar esquemas a um compartilhamento.

A adição de um esquema inteiro a um compartilhamento fornece aos destinatários acesso a todos os ativos de dados no esquema no momento em que você cria o compartilhamento, bem como a todos os ativos adicionados ao esquema ao longo do tempo. Isso inclui todas as tabelas, exibições e volumes no esquema. As tabelas compartilhadas dessa forma sempre incluem o histórico completo.

Compartilhar esquemas com um destinatário

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.

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

Limitações

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

• Se você quiser especificar opções avançadas para uma tabela ou volume no esquema, deverá compartilhar a tabela ou o volume usando SQL e fornecer à tabela ou volume um alias com um nome de esquema diferente.

Adicionar tabelas e esquemas protegidos por políticas ABAC a um compartilhamento

O ABAC (controle de acesso baseado em atributo) é um modelo de governança de dados que fornece controle de acesso flexível, escalonável e centralizado no Azure Databricks.

Você pode compartilhar uma tabela ou esquema protegido por políticas ABAC, como tabelas padrão. Para saber como aplicar políticas abac aos seus ativos de dados, consulte Criar e gerenciar políticas de ABAC (controle de acesso baseado em atributo).

No entanto, você deve ser um usuário privilegiado. Um usuário privilegiado é o proprietário do compartilhamento e um usuário que é excluído das políticas ABAC aplicadas ao ativo de dados. A política não rege o acesso do destinatário. Os destinatários têm acesso total ao ativo compartilhado. As limitações do ABAC se aplicam.

Adicionar tabelas de streaming a um compartilhamento

As tabelas de streaming são tabelas Delta regulares com suporte extra para streaming ou processamento de dados incrementais. As tabelas de streaming são projetadas para fontes de dados somente acréscimo e entradas de processo apenas uma vez. Consulte Usar tabelas de streaming no Databricks SQL.

Verifique se você atende aos requisitos antes de adicionar tabelas de streaming a um compartilhamento.

Requisitos adicionais

• Se o espaço de trabalho tiver associações de espaço de trabalho-catálogo habilitadas, verifique se o espaço de trabalho tem acesso de leitura e gravação ao catálogo em que a tabela de streaming está. Para obter mais informações, consulte Limitar o acesso ao catálogo a workspaces específicos.
• Tabelas de streaming compartilháveis devem ser definidas em tabelas Delta ou em outras tabelas ou exibições de streaming compartilháveis.
• Você deve usar um SQL Warehouse ou uma computação no Databricks Runtime 13.3 LTS ou superior ao adicionar uma tabela de streaming a um compartilhamento.

Limitações

• A tabela de streaming não pode ter filtros de linha e máscaras de coluna.
  • A tabela base da tabela de streaming pode ter filtros de linha e máscaras de coluna.
• A tabela de streaming não pode ter filtros de partição. Em vez disso, crie uma exibição na parte superior da tabela de streaming.

Compartilhar tabelas de streaming com um destinatário

Para adicionar tabelas de streaming a um compartilhamento:

Gerenciador de Catálogos

1. No workspace do Azure Databricks, clique no Catálogo.

2. Na parte superior do painel Catálogo, clique no 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 o compartilhamento ao qual você deseja adicionar uma tabela de streaming e clique em seu nome.

4. Clique em Gerenciar ativos > Editar ativos.

5. Na página Editar ativos , pesquise ou procure a tabela de streaming que você deseja compartilhar e selecione-a.

6. (Opcional) Na coluna Alias, clique em para especificar um alias ou um nome alternativo para a tabela de streaming, tornando o nome da tabela de streaming mais legível. O alias é o nome que o destinatário vê e deve usar em consultas. Os destinatários não poderão usar o nome real da tabela de streaming se um alias for especificado.

7. Clique em Salvar.

SQL

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

ALTER SHARE <share_name> ADD TABLE <st_name> [COMMENT <comment>] [AS <shared_st_name>];

CLI

Execute o seguinte comando da CLI do Databricks.

databricks shares update <share-name> \
  --json '{
    “updates”: [
      {
        “action”: “ADD”,
        “data_object”: {
          “name”: “<st-full-name>",
          “data_object_type”: “TABLE”,
          “comment”: “<comment>”
        }
      }
    ]
  }'

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

Adicionar tabelas de Iceberg gerenciadas a um compartilhamento

O Apache Iceberg é um formato de tabela de software livre para cargas de trabalho de análise. No Azure Databricks, você pode criar tabelas iceberg no Catálogo do Unity, conhecidas como tabelas iceberg gerenciadas.

Verifique se você atende aos requisitos antes de adicionar tabelas de Iceberg gerenciadas a um compartilhamento.

As limitações da tabela Iceberg e da tabela Iceberg gerenciada se aplicam. Veja as limitações da tabela Iceberg.

Para adicionar tabelas de Iceberg gerenciadas a um compartilhamento:

Gerenciador de Catálogos

1. No workspace do Azure Databricks, clique no Catálogo.

2. Na parte superior do painel Catálogo, clique no 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 o compartilhamento ao qual você deseja adicionar uma tabela Iceberg gerenciada e clique no nome.

4. Clique em Gerenciar ativos>Editar ativos.

5. Na página Editar ativos, pesquise ou navegue pela tabela Iceberg gerenciada que você deseja compartilhar e selecione-a.

6. (Opcional) Na coluna Alias, clique em para especificar um alias, ou um nome alternativo de tabela Iceberg gerenciada, tornando o nome mais legível. O alias é o nome que o destinatário vê e deve usar em consultas. Os destinatários não poderão usar o nome efetivo da tabela Iceberg gerenciada se um alias for especificado.

7. Clique em Salvar.

SQL

Execute o comando a seguir em um notebook ou no editor de SQL do Databricks. Opcionalmente, especifique <shared_iceberg_table_name> para expor a tabela Iceberg gerenciada sob um nome diferente.

ALTER SHARE <share_name> ADD TABLE <managed_iceberg_name> [COMMENT <comment>] [AS <shared_iceberg_table_name>];

CLI

Execute o seguinte comando da CLI do Databricks.

databricks shares update <share-name> \
  --json '{
    “updates”: [
      {
        “action”: “ADD”,
        “data_object”: {
          “name”: “<managed-iceberg-full-name>",
          “data_object_type”: “TABLE”,
          “comment”: “<comment>”
        }
      }
    ]
  }'

Adicionar esquemas ou tabelas estrangeiras a um compartilhamento

A federação Lakehouse permite que você use o Azure Databricks para executar consultas em fontes de dados externas. Você pode criar esquemas e tabelas estrangeiras, que contêm dados e metadados gerenciados por sistemas externos, com o Catálogo do Unity adicionando governança de dados para consultar essas tabelas. Para saber mais sobre como se conectar a fontes externas, confira o que é a Federação Lakehouse?.

O Compartilhamento Delta permite que você compartilhe com segurança dados estrangeiros de sua localização original, sem copiar dados para o Azure Databricks, configurações de rede complexas ou transferências de credenciais.

Verifique se você atende aos requisitos antes de adicionar esquemas ou tabelas estrangeiras a um compartilhamento.

Requisitos adicionais

• Você deve habilitar a computação sem servidor para fluxos de trabalho, notebooks e Pipelines Declarativos do Lakeflow Spark na conta em que o esquema externo ou o compartilhamento de tabelas externas foi configurado. Consulte Conectar-se ao computador sem servidor.

• Ao compartilhar esquemas e tabelas estrangeiras, os dados são consultados e materializados temporariamente no lado do provedor. Por padrão, os dados materializados são armazenados em um esquema oculto usando o armazenamento padrão do Azure Databricks (Versão Prévia Privada). Verifique se você atende aos requisitos e observe as limitações para o armazenamento padrão.

  Para obter detalhes sobre a disponibilidade regional de armazenamento padrão, consulte a disponibilidade sem servidor.

  Para recusar o uso do armazenamento padrão do Azure Databricks e usar seu próprio armazenamento para materialização temporária, abra um caso de suporte.

• Se você optar por usar o armazenamento padrão, deverá habilitar o Compartilhamento Delta para Armazenamento Padrão – versão prévia do Acesso Expandido no nível da conta. Consulte Gerenciar visualizações do Azure Databricks.

Padrões de uso recomendados

Os resultados da consulta são gerados sob demanda para cada consulta, portanto, o compartilhamento de tabelas ou de esquemas externos pode não ser tão econômico em comparação com o compartilhamento de tabelas ou de visões materializadas. O Azure Databricks recomenda o seguinte para melhorar o desempenho:

• Mantenha o tamanho dos resultados típicos da consulta menor que 10 GBs.
• Use consultas exploratórias ad hoc em vez de despejos de dados frequentes.
• Ao usar o compartilhamento de tokens na nuvem, considere compartilhar visualizações materializadas criadas sobre tabelas externas para maior eficiência de custos e melhor desempenho.

Compartilhar o esquema ou tabela estrangeira com um destinatário

Para adicionar esquemas ou tabelas estrangeiras a um compartilhamento, use o Catalog Explorer, a CLI do Catálogo do Databricks Unity ou os comandos SQL em um notebook do Azure Databricks ou no editor de consultas SQL do Databricks.

Gerenciador de Catálogos

1. No workspace do Azure Databricks, clique no Catálogo.

2. Na parte superior do painel Catálogo, clique no 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 o compartilhamento ao qual você deseja adicionar uma tabela ou esquema estrangeiro e clique em seu nome.

4. Clique em Gerenciar ativos > Editar ativos.

5. Na página Editar ativos , pesquise ou procure a tabela ou esquema estrangeiro que você deseja compartilhar e selecione-a.

6. (Opcional) Na coluna Alias, clique no ícone de mais em forma de balão de fala para especificar um alias ou um nome de tabela ou esquema estrangeiro alternativo, tornando o esquema ou o nome da tabela estrangeira mais legível. O alias é o nome que o destinatário vê e deve usar em consultas. Os destinatários não poderão usar o esquema ou nome de tabela estrangeiros reais se um alias for especificado.

7. Clique em Salvar.

SQL

ALTER SHARE <share-name>
  ADD {TABLE | SCHEMA} {federated_catalog.federated_schema.federated_table | federated_catalog.federated_schema}
  [COMMENT "<comment>"]
  [AS <alias>];

As opções incluem:

• AS <alias>: um nome ou alias alternativo para tornar o nome do ativo de dados mais legível. O alias é o nome do ativo de dados que o destinatário vê e deve usar em consultas. Os destinatários não poderão usar o nome real se um alias for especificado. Use o formato <catalog-name>.<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 do ativo de dados usando instruções SQL.

Para saber mais sobre as opções de ALTER SHARE, consulte ALTER SHARE.

CLI

databricks shares update <share-name> \
  --json '{
    “updates”: [
      {
        “action”: “ADD”,
        “data_object”: {
          “name”: “<federated-data-asset-full-name>",
          “data_object_type”: “{TABLE | SCHEMA}”,
          "shared_as": "<foreign-data-asset-alias>",
          “comment”: “<comment>”
        }
      }
    ]
  }'

Adicionar vistas a uma partilha

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

Verifique se você atende aos requisitos antes de adicionar exibições a um compartilhamento.

Requisitos adicionais

• Exibições compartilháveis devem ser definidas em tabelas Delta, outras exibições compartilháveis ou exibições materializadas locais e tabelas de streaming. Visualizações compartilháveis não podem ser definidas em tabelas externas.
• Não é possível compartilhar exibições que façam referência a tabelas ou exibições compartilhadas.
• Você precisa usar um SQL warehouse ou um computador no Databricks Runtime 13.3 LTS ou superior ao adicionar uma exibição a um compartilhamento.
• Se o workspace possuir associações de 'workspace-catalog' habilitadas, verifique se o workspace tem acesso de leitura e gravação ao catálogo. Para obter mais informações, consulte Limitar o acesso ao catálogo a workspaces específicos.
• Ao compartilhar visões, os dados são consultados e materializados temporariamente. Os dados materializados são armazenados no local de armazenamento do esquema ou catálogo pai da exibição ou no local raiz do metastore.
• Se o local de armazenamento tiver configurações de rede personalizadas, como um firewall ou um link privado, você deverá verificar se os destinatários estão na lista de permissões para se conectarem ao local de armazenamento. Para obter instruções sobre como configurar regras de firewall para computação sem servidor, consulte Configurar um firewall para acesso à computação sem servidor.

Compartilhar exibições com um destinatário

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

Gerenciador de Catálogos

1. No workspace do Azure Databricks, clique no Catálogo.

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

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

3. Na guia Compartilhado por mim, encontre o compartilhamento ao qual você deseja adicionar uma visualização e clique no nome dele.

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

5. Na página Adicionar tabelas pesquise ou procure o modo de exibição que você deseja compartilhar e selecione-o.

6. (Opcional) Clique em na coluna Alias para especificar um nome de exibição alternativo, ou Alias, para tornar o nome da exibição mais legível. O alias é o nome que o destinatário vê e deve usar em consultas. Os destinatários não poderão usar o nome de exibição real se um alias for especificado.

7. Clique em Salvar.

SQL

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

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

As opções incluem:

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

Para saber mais sobre as opções de ALTER SHARE, consulte ALTER SHARE.

CLI

Execute o seguinte comando da CLI do Databricks:

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

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

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

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

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

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

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

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

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

Requirements

• Verifique se você atende aos requisitos para adicionar uma exibição a um compartilhamento.
• Versão do Databricks Runtime: a função CURRENT_RECIPIENT é suportada no Databricks Runtime 14.2 e versões posteriores.

Limitações

• Todas as limitações para o compartilhamento de exibição se aplicam.
• Quando um provedor compartilha uma exibição que usa a CURRENT_RECIPIENT função, o provedor não pode consultar a exibição diretamente devido ao contexto de compartilhamento. Para testar uma visão dinâmica, o provedor deve compartilhá-la consigo mesmo e consultá-la na posição de destinatário.
• Os provedores não podem criar uma visualização que faça referência a uma exibição dinâmica.

Definir uma propriedade de destinatário

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

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

Gerenciador de Catálogos

1. No workspace do Azure Databricks, clique no Catálogo.

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

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

3. Na guia Recipientes, localize 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, digite o nome da coluna como chave (neste caso, country) e o valor pelo qual deseja filtrar como valor (por exemplo, CA).

6. Clique em Salvar.

SQL

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

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

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

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

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

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

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

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

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

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

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

Adicionar exibições materializadas a um compartilhamento

Assim como as visualizações, visualizações materializadas são os resultados de uma consulta, e você pode acessá-los como faria com uma tabela. Ao contrário das exibições regulares, os resultados de uma exibição materializada refletem o estado dos dados quando a exibição materializada foi atualizada pela última vez. Para obter mais detalhes sobre exibições materializadas, consulte Usar exibições materializadas no DATAbricks SQL.

Verifique se você atende aos requisitos antes de adicionar exibições materializadas a um compartilhamento.

Requisitos adicionais

• Se o workspace tiver associações de workspace-catalog habilitadas, verifique se o workspace tem acesso de leitura e gravação ao catálogo que contém a exibição materializada. Para obter mais informações, consulte Limitar o acesso ao catálogo a workspaces específicos.
• As exibições materializadas compartilháveis devem ser definidas em tabelas Delta ou outras tabelas de streaming compartilháveis, exibições ou exibições materializadas.
• Você deve usar um SQL Warehouse ou uma computação no Databricks Runtime 13.3 LTS ou superior ao adicionar uma exibição materializada a um compartilhamento.

Limitações

• A exibição materializada não pode ter filtros de linha, mas a tabela base da exibição materializada pode ter filtros de linha e máscaras de coluna.
• A exibição materializada não pode ter filtros de partição. Em vez disso, crie uma visão sobre a visão materializada.

Compartilhar visões materializadas com um destinatário

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

Gerenciador de Catálogos

1. No workspace do Azure Databricks, clique no Catálogo.

2. Na parte superior do painel Catálogo, clique no 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 o compartilhamento ao qual você deseja adicionar uma exibição materializada e clique em seu nome.

4. Clique em Gerenciar ativos > Editar ativos.

5. Na página Editar ativos , pesquise ou procure a exibição materializada que você deseja compartilhar e selecione-a.

6. (Opcional) Na coluna Alias, clique em para especificar um alias ou nome alternativo de exibição materializada, para tornar o nome da exibição materializada 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 real da exibição materializada se um alias for especificado.

7. Clique em Salvar.

SQL

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

ALTER SHARE <share_name> ADD MATERIALIZED VIEW <mv_name> [COMMENT <comment>] [AS <shared_mv_name>];

CLI

databricks shares update <share-name> \
  --json '{
    “updates”: [
      {
        “action”: “ADD”,
        “data_object”: {
          “name”: “<mat-view-full-name>”,
          “data_object_type”: “MATERIALIZED_VIEW”,
          “comment”: “<comment>”
        }
      }
    ]
  }'

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

Adicionar volumes a um compartilhamento

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

Verifique se você atende aos requisitos antes de adicionar volumes a um compartilhamento.

Requisitos adicionais

• O compartilhamento de volume só tem suporte no compartilhamento do Databricks para o Databricks.
• Você deve usar um SQL Warehouse na versão 2023.50 ou superior ou um recurso de computação no Databricks Runtime 14.1 ou superior ao 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á verificar se os endereços do plano de controle e do plano de dados do destinatário estão corretamente na lista de permissões para poder se conectar ao local de armazenamento do volume.

Compartilhar volumes com um destinatário

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

Gerenciador de Catálogos

1. No workspace do Azure Databricks, clique no Catálogo.

2. Na parte superior do painel Catálogo, clique no 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 o compartilhamento ao qual você deseja adicionar um volume e clique no nome dele.

4. Clique em Gerenciar ativos > Editar ativos.

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

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

6. (Opcional) Clique em na coluna Alias 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. Se um alias for especificado, os destinatários não poderão usar o nome real do volume.

7. Clique em Salvar.

SQL

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

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

As opções incluem:

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

Para saber mais sobre as opções de ALTER SHARE, consulte ALTER SHARE.

CLI

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

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

"string_shared_as": "<volume-alias>" é opcional e fornece um nome de volume alternativo, ou alias, para tornar o nome do volume mais legível. O alias é o nome do volume que o destinatário vê e deve usar em consultas. Os destinatários não podem 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 confira PATCH /api/2.1/unity-catalog/shares/ na referência da API REST.

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

Adicionar UDFs do Python a um compartilhamento

As UDFs (funções definidas pelo usuário) permitem que você reutilize e compartilhe código que estende a funcionalidade interna no Azure Databricks. Para saber como criar UDFs do Python, consulte as funções escalares definidas pelo usuário – Python.

Verifique se você atende aos requisitos antes de adicionar UDFs do Python a um compartilhamento.

Limitações adicionais

• Não é possível compartilhar UDFs do Python com um destinatário aberto.

Compartilhar UDFs do Python com um destinatário

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

Gerenciador de Catálogos

1. No workspace do Azure Databricks, clique no Catálogo.

2. Na parte superior do painel Catálogo, clique no 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 o compartilhamento ao qual você deseja adicionar um UDF do Python e clique em seu nome.

4. Clique em Gerenciar ativos > Editar ativos.

5. Na página Editar ativos , pesquise ou procure a UDF do Python que você deseja compartilhar e selecioná-la.

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

6. (Opicional) Clique no Na coluna Alias para especificar um nome UDF alternativo do Python ou Alias, tornando o nome UDF do Python 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. Se um alias for especificado, os destinatários não poderão usar o nome UDF do Python real.

7. Clique em Salvar.

SQL

Execute o seguinte comando, que usa ADD MODEL, em um notebook ou no editor de consultas SQL do Databricks:

ALTER SHARE <share-name> ADD MODEL <catalog-name>.<schema-name>.<python-udf-name>
   [AS <alias>];

As opções incluem:

• AS <alias>: um nome UDF do Python alternativo, ou alias, para tornar o nome UDF do Python mais legível. O alias é o nome UDF do Python que o destinatário vê e deve usar em consultas. Os destinatários não poderão usar o nome UDF do Python real se um alias for especificado. Use o formato <schema-name>.<python-udf-name>.

Para saber mais sobre as opções de ALTER SHARE, consulte ALTER SHARE.

CLI

Execute o seguinte comando, que especifica o tipo de objeto como modelo, usando a CLI do Databricks 0.210 ou superior:

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

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

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

Adicionar FeatureSpecs a um compartilhamento

Um FeatureSpec é um conjunto definido pelo usuário de recursos e funções. Os destinatários podem criar um endpoint para servir recursos a partir do compartilhado FeatureSpec. Para saber como criar FeatureSpecs, consulte Criar um FeatureSpec.

Verifique se você atende aos requisitos antes de adicionar FeatureSpecs a um compartilhamento.

Requisitos adicionais

• Todas as dependências devem ser adicionadas ao compartilhamento. Ao usar a interface do usuário para adicionar um FeatureSpec a um compartilhamento, todas as dependências devem ser adicionadas automaticamente ao compartilhamento.
• Se uma dependência for adicionada ao modelo, ela também deverá ser adicionada ao compartilhamento.

Limitações adicionais

• Se esse ativo for uma dependência de outro modelo, você não poderá especificar um alias.
• Você não pode compartilhar FeatureSpecs com um destinatário aberto.

Compartilhar FeatureSpecs com um destinatário

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

Gerenciador de Catálogos

1. No workspace do Azure Databricks, clique no Catálogo.

2. Na parte superior do painel Catálogo, clique no 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 o compartilhamento ao qual você deseja adicionar um FeatureSpec e clique em seu nome.

4. Clique em Gerenciar ativos > Editar ativos.

5. Na página Editar ativos, pesquise ou navegue pelo ativo FeatureSpec que você deseja compartilhar e selecione-o.

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

6. (Opcional) Clique no na coluna Alias para especificar um nome alternativo, também conhecido como FeatureSpec, para tornar o nome 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. Se um alias for especificado, os destinatários não poderão usar o nome real FeatureSpec .

7. Se houver dependências, a caixa de diálogo Adicionar todas as dependências informará que todas elas serão adicionadas automaticamente. Clique em Adicionar todas as dependências.

8. Clique em Salvar.

SQL

Execute o seguinte comando, que usa ADD MODEL, em um notebook ou no editor de consultas SQL do Databricks:

ALTER SHARE <share-name> ADD MODEL <catalog-name>.<schema-name>.<featurespec-name>
   [AS <alias>];

--Opções incluem:

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

Para saber mais sobre as opções de ALTER SHARE, consulte ALTER SHARE.

CLI

Execute o seguinte comando, que especifica o tipo de objeto como modelo, usando a CLI do Databricks 0.210 ou superior:

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

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

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

Adicionar modelos a um compartilhamento

Verifique se você atende aos requisitos antes de adicionar modelos a um compartilhamento.

Requisitos adicionais

• O compartilhamento de modelos é suportado apenas no compartilhamento do Databricks para o Databricks.
• Você deve usar um sql warehouse na versão 2023.50 ou superior ou um recurso de computação no Databricks Runtime 14.0 ou superior ao adicionar um modelo a um compartilhamento.

Compartilhar modelos com um destinatário

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

Para adicionar modelos a um compartilhamento:

Gerenciador de Catálogos

1. No workspace do Azure Databricks, clique no Catálogo.

2. Na parte superior do painel Catálogo, clique no 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 o compartilhamento ao qual você deseja adicionar um modelo e clique no nome dele.

4. Clique em Gerenciar ativos > Editar ativos.

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

   Alternativamente, você pode selecionar o esquema inteiro que contém o modelo. Consulte Adicionar esquemas a um compartilhamento.

6. (Opcional) Clique em na coluna Alias para especificar um nome de modelo alternativo, ou Alias, para tornar o nome do modelo mais legível.

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

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

7. Clique em Salvar.

SQL

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

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

As opções incluem:

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

Para saber mais sobre as opções de ALTER SHARE, consulte ALTER SHARE.

CLI

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

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

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

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

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

Adicionar um arquivo de notebook a um compartilhamento

Verifique se você atende aos requisitos antes de adicionar arquivos de notebook a um compartilhamento.

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

1. No workspace do Azure Databricks, clique no Catálogo.
2. Clique no botão Compartilhamento >Delta.
3. Na guia Compartilhado por mim, localize o compartilhamento ao qual você deseja adicionar um notebook e clique no nome dele.
4. Clique em Gerenciar ativos e selecione Adicionar arquivo de notebook.
5. Na página Adicionar arquivo de notebook, clique no ícone de arquivo para procurar o notebook que você deseja compartilhar.
   • Clique no arquivo que você deseja compartilhar e clique em Selecionar.
   • (Opcionalmente) especifique um alias amigável para o arquivo no campo Compartilhar como. Esse é o identificador que os destinatários veem.
   • Em local de armazenamento, insira o local externo no armazenamento em nuvem em que você deseja armazenar o notebook. Você pode especificar um subcaminho no local externo definido. Se você não especificar um local externo, o notebook será armazenado no local de armazenamento no nível do metastore (ou "local raiz do metastore"). Se nenhum local raiz for definido para o metastore, você deverá inserir um local externo aqui. Confira Adicionar armazenamento gerenciado a um metastore existente.
6. Clique em Salvar.

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

Remover arquivos de notebook de compartilhamentos

Para remover um arquivo de notebook de um compartilhamento:

1. No workspace do Azure Databricks, clique no Catálogo.

2. Na parte superior do painel Catálogo, clique no 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 o compartilhamento que inclui o notebook e clique no nome do compartilhamento.

4. Na guia Ativos, localize o arquivo de notebook que você deseja remover do compartilhamento.

5. Clique no menu de três linhas horizontais à direita da linha e selecione Excluir arquivo de notebook.

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

Atualizar arquivos de notebook em compartilhamentos

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

Habilitar o compartilhamento para clientes externos do Iceberg

Você pode compartilhar tabelas Delta, tabelas estrangeiras de Iceberg, exibições, exibições materializadas e tabelas de streaming com clientes externos do Iceberg que usam a API do Catálogo REST do Apache Iceberg.

Antes de compartilhar, verifique se você atende aos requisitos de compartilhamento Delta necessários para adicionar seu ativo de dados a um compartilhamento. Você também deve desabilitar vetores de exclusão para tabelas.

Para compartilhar ativos de dados com clientes externos do Iceberg:

1. Se você estiver compartilhando uma tabela Delta, configure cada tabela Delta com IcebergCompatV2 para expô-la como uma tabela compatível com Iceberg. Isso permite a geração assíncrona de metadados do Iceberg junto com as operações delta padrão. Verifique se você atende aos requisitos de compartilhamento de tabelas Delta com clientes Iceberg e observe as limitações. Para saber como habilitar as leituras do Iceberg, consulte Enable Iceberg reads (UniForm).

   Se você estiver compartilhando com o Snowflake, somente as tabelas com o recurso 'uniform' habilitado serão exibidas para o destinatário. Outras tabelas são filtradas.

   Note

   • Use DESCRIBE HISTORY para confirmar que a geração de metadados do Iceberg foi concluída antes que a tabela possa ser consultada dos clientes Iceberg.
   • Não há suporte para o tipo de autenticação OIDC.

2. Adicione o ativo de dados a uma partilha. Para obter instruções detalhadas, consulte:

   • Adicionar tabelas a um compartilhamento
   • Adicionar vistas a um compartilhamento
   • Adicionar exibições materializadas a um compartilhamento
   • Adicionar tabelas de streaming a um compartilhamento
   • O compartilhamento de tabelas de Iceberg estrangeiras está disponível na Visualização Privada. Para ingressar nesta versão prévia, entre em contato com sua equipe de conta do Azure Databricks.

   Important

   A materialização de dados pelo provedor é ativada se você compartilhar visualizações, visualizações materializadas ou tabelas de streaming, o que pode levar ao acúmulo de custos computacionais. Para obter mais informações, consulte Como incorrer em e verificar os custos de Delta Sharing?.

3. Compartilhe com o destinatário aberto. Para obter instruções sobre como criar um destinatário e conceder-lhes acesso ao compartilhamento, consulte Criar um objeto de destinatário para usuários que não são do Databricks usando tokens de portador (compartilhamento aberto).

Conceder aos destinatários acesso a um compartilhamento

Verifique se você atende aos requisitos antes de conceder aos destinatários acesso a um compartilhamento.

Para obter instruções, confira Gerenciar o acesso aos compartilhamentos de dados do Compartilhamento Delta (para provedores). Esta página também explica como revogar o acesso de um destinatário a um compartilhamento.

Exibir compartilhamentos e detalhes de compartilhamento

Verifique se você atende aos requisitos antes de exibir compartilhamentos e compartilhar detalhes.

Para exibir uma lista de compartilhamentos ou detalhes sobre um compartilhamento, use o Catalog Explorer, a CLI do Catálogo do Databricks Unity ou os comandos SQL em um notebook do Azure Databricks ou no editor de consultas SQL do Databricks.

Os detalhes do compartilhamento incluem o seguinte:

• O proprietário do compartilhamento, criador, data e hora de criação, quem atualizou, data e hora da última atualização, comentários.
• Ativos de dados no compartilhamento.
• Destinatários com acesso ao compartilhamento.

Gerenciador de Catálogos

1. No workspace do Azure Databricks, clique no Catálogo.

2. Na parte superior do painel Catálogo, clique no 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 do compartilhamento na guia Detalhes.

SQL

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

SHOW SHARES [LIKE <pattern>];

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

DESCRIBE SHARE <share-name>;

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

SHOW ALL IN SHARE <share-name>;

CLI

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

databricks shares list

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

databricks shares get <share-name>

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

Verifique se você atende aos requisitos antes de exibir os destinatários.

Para exibir a lista de compartilhamentos aos quais um destinatário recebeu acesso, use o Catalog Explorer, a CLI do Catálogo do Databricks Unity ou o SHOW GRANTS TO RECIPIENT comando SQL em um notebook do Azure Databricks ou no editor de consultas SQL do Databricks.

Gerenciador de Catálogos

1. No workspace do Azure Databricks, clique no Catálogo.

2. Na parte superior do painel Catálogo, clique no 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. Acesse a guia Destinatários para exibir a lista de destinatários que podem acessar o compartilhamento.

SQL

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

SHOW GRANTS ON SHARE <share-name>;

CLI

Execute o comando a seguir usando a CLI do Databricks.

databricks shares share-permissions <share-name>

Atualizar compartilhamentos

Verifique se você atende aos requisitos antes de fazer atualizações em um compartilhamento.

Você pode atualizar um compartilhamento das seguintes maneiras:

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

Para fazer essas atualizações em compartilhamentos, use o Catalog Explorer, a CLI do Catálogo do Databricks Unity ou os comandos SQL em um notebook do Azure Databricks ou no editor de consultas SQL do Databricks. No entanto, você não pode usar o Gerenciador de Catálogos para renomear o compartilhamento.

Gerenciador de Catálogos

1. No workspace do Azure Databricks, clique no Catálogo.

2. Na parte superior do painel Catálogo, clique no 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 o compartilhamento que você deseja atualizar e clique no nome dele.

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

• Clique no ícone editar ao lado do campo do proprietário ou do comentário para atualizar esses valores.
• Clique no botão do menu de três linhas horizontais na linha de um ativo 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 comandos a seguir em um notebook ou no editor do Databricks SQL.

Renomear um compartilhamento:

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

Remover tabelas de um compartilhamento:

ALTER SHARE share_name REMOVE TABLE <table-name>;

Remover volumes de um compartilhamento:

ALTER SHARE share_name REMOVE VOLUME <volume-name>;

Adicionar ou atualizar um comentário em um compartilhamento:

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

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

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

Alterar o proprietário do compartilhamento:

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

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

Habilite o compartilhamento de histórico para uma tabela:

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

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

CLI

Execute os comandos a seguir usando a CLI do Databricks.

Renomear um compartilhamento:

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

Remover tabelas de um compartilhamento:

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

Remover volumes de um compartilhamento usando a CLI do Databricks versão 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 em um compartilhamento:

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

Alterar o proprietário do compartilhamento:

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

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

Considerações ao atualizar o dono do compartilhamento

Quem é o proprietário do compartilhamento afeta a maneira como os recursos de autorização e segurança, como as políticas ABAC, são avaliados. Transferir a propriedade de compartilhamento para um usuário com privilégios excessivos permite que os destinatários tenham acesso com privilégios excessivos se você tiver uma tabela ou esquema protegido por políticas ABAC.

Excluir compartilhamentos

Ao excluir um compartilhamento, os destinatários não podem mais acessar os dados compartilhados. Verifique se você atende aos requisitos antes de excluir um objeto de compartilhamento.

Para excluir um compartilhamento, use o Gerenciador de Catálogos, a CLI do Catálogo do Databricks Unity ou o DELETE SHARE comando SQL em um notebook do Azure Databricks ou no editor de consultas SQL do Databricks. É necessário ser o proprietário do compartilhamento.

Gerenciador de Catálogos

1. No workspace do Azure Databricks, clique no Catálogo.

2. Na parte superior do painel Catálogo, clique no 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 o compartilhamento que você deseja excluir e clique no nome dele.

4. Clique no Menu kebab e selecione Excluir.

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

SQL

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

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

CLI

Execute o comando a seguir usando a CLI do Databricks.

databricks shares delete <share-name>