Ler dados compartilhados usando o compartilhamento aberto do Delta Sharing com tokens de portador (para destinatários)

Esta página descreve como ler dados compartilhados com você usando o protocolo de compartilhamento aberto Delta Sharing com tokens de portador. Ele inclui instruções para ler dados compartilhados usando as seguintes ferramentas:

• Databricks
• Apache Spark
• Pandas
• Power BI
• Quadro
• Clientes iceberg

Neste modelo de compartilhamento aberto, você usa um arquivo de credencial, compartilhado com um membro da sua equipe pelo provedor de dados, para obter acesso seguro de leitura aos dados compartilhados. O acesso persiste enquanto a credencial for válida e o provedor continuar compartilhando os dados. Os provedores gerenciam a expiração e a rotação das credenciais. As atualizações dos dados estão disponíveis quase em tempo real. Você pode ler e fazer cópias dos dados compartilhados, mas não pode modificar os dados de origem.

As seções a seguir descrevem como usar os clientes Azure Databricks, Apache Spark, pandasPower BI e Iceberg para acessar e ler dados compartilhados usando o arquivo de credencial. Para obter uma lista completa de conectores e informações do Compartilhamento Delta sobre como usá-los, consulte a Documentação de código aberto do Compartilhamento Delta. Caso você tenha problemas para acessar os dados compartilhados, entre em contato com o provedor de dados.

Antes de começar

Um membro da sua equipe deve baixar o arquivo de credencial compartilhado pelo provedor de dados. Confira Obter acesso no modelo de compartilhamento aberto.

Eles devem usar um canal seguro para compartilhar esse arquivo ou local de arquivo com você.

Azure Databricks: ler dados compartilhados usando conectores de compartilhamento aberto

Esta seção descreve como importar um provedor e como consultar os dados compartilhados no Gerenciador de Catálogos ou em um notebook Python:

• Se o workspace do Azure Databricks estiver habilitado para o Catálogo do Unity, use a interface do usuário do provedor de importação no Explorador do Catálogo. Você pode fazer o seguinte sem precisar armazenar ou especificar um arquivo de credencial:

  • Crie catálogos a partir de compartilhamentos com o clique de um botão.
  • Use controles de acesso do Catálogo do Unity para conceder acesso a tabelas compartilhadas.
  • Consultar dados compartilhados usando a sintaxe padrão do Catálogo do Unity.

• Se o workspace do Azure Databricks não estiver habilitado para o Catálogo do Unity, use as instruções do notebook Python como exemplo.

Gerenciador de Catálogos

Permissões necessárias: um administrador do metastore ou um usuário que tenha os privilégios de CREATE PROVIDER e USE PROVIDERpara seu metastore do Catálogo do Unity.

1. No workspace do Azure Databricks, clique no Catálogo para abrir o Gerenciador de Catálogos.

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

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

3. Na guia Compartilhado comigo, clique em Importar dados.

4. Insira o nome do provedor.

   O nome não pode incluir espaços.

5. Carregue o arquivo de credencial que o provedor compartilhou com você.

   Muitos provedores têm suas próprias redes de Delta Sharing das quais você pode receber compartilhamentos. Para obter mais informações, consulte Configurações específicas do provedor.

6. (Opcional) Insira um comentário.

   

7. Clique em Importar.

8. Crie catálogos com base nos dados compartilhados.

   Na guia Compartilhamentos, clique em Criar catálogo na linha de compartilhamento.

   Para obter informações sobre como usar o SQL ou a CLI do Databricks para criar um catálogo a partir de um compartilhamento, consulte Criar um catálogo a partir de um compartilhamento.

9. Conceda acesso aos catálogos.

   Veja Como fazer para disponibilizar dados compartilhados para minha equipe? e Gerenciar permissões para esquemas, tabelas e volumes em um catálogo do Delta Sharing.

10. Leia os objetos de dados compartilhados da mesma forma que você faria com qualquer objeto de dados registrado no Catálogo do Unity.

    Para obter detalhes, confira Acessar dados em uma tabela ou volume compartilhado.

Python

Esta seção descreve como usar um conector de compartilhamento aberto para acessar os dados compartilhados usando um notebook no workspace do Azure Databricks. Você ou outro membro da sua equipe armazena o arquivo de credencial no Azure Databricks e, em seguida, usa-o para autenticar na conta do Azure Databricks do provedor de dados e ler os dados que o provedor de dados compartilhou com você.

Primeiro armazene o arquivo de credencial como um arquivo de workspace do Azure Databricks para que os usuários em sua equipe possam acessar dados compartilhados.

1. Para importar o arquivo de credencial no workspace do Azure Databricks, consulte Importar um arquivo.

2. Conceda a outros usuários permissão para acessar o arquivo clicando no Ao lado do arquivo, compartilhe (Permissões). Insira as identidades do Azure Databricks que devem ter acesso ao arquivo.

   Para obter mais informações sobre permissões de arquivo, consulte ACLs de arquivo.

Agora que o arquivo de credencial está armazenado, use um bloco de anotações para listar e ler tabelas compartilhadas.

1. No workspace do Azure Databricks, clique em Novo > Notebook.

   Para obter mais informações sobre notebooks do Azure Databricks, consulte Notebooks do Databricks.

2. Para usar Python ou pandas para acessar os dados compartilhados, instale o conector Delta Sharing Python. No editor do notebook, cole o seguinte comando:

   %sh pip install delta-sharing
   

3. Execute a célula.

   A delta-sharing biblioteca python será instalada no cluster se ainda não estiver instalada.

4. Usando o Python, liste as tabelas no compartilhamento.

   Em uma nova célula, cole o comando a seguir. Substitua o caminho do workspace pelo caminho para o arquivo de credenciais.

   Quando o código é executado, o Python lê o arquivo de credencial.

   import delta_sharing
   
   client = delta_sharing.SharingClient(f"/Workspace/path/to/config.share")
   
   client.list_all_tables()
   

5. Execute a célula.

   O resultado é uma matriz de tabelas, com metadados para cada tabela. A seguinte saída mostra duas tabelas:

   Out[10]: [Table(name='example_table', share='example_share_0', schema='default'), Table(name='other_example_table', share='example_share_0', schema='default')]
   

   Se a saída estiver vazia ou não contiver as tabelas esperadas, entre em contato com o provedor de dados.

6. Consultar uma tabela compartilhada.

   • Usando Scala:

     Em uma nova célula, cole o comando a seguir. Quando o código é executado, o arquivo de credencial é lido do arquivo do workspace.

     Substitua as variáveis da seguinte forma:

     • <profile-path>: o caminho do ambiente de trabalho do arquivo de credenciais. Por exemplo, /Workspace/Users/user.name@email.com/config.share.
     • <share-name>: o valor de share= na tabela.
     • <schema-name>: o valor de schema= na tabela.
     • <table-name>: o valor de name= na tabela.

     %scala
         spark.read.format("deltaSharing")
         .load("<profile-path>#<share-name>.<schema-name>.<table-name>").limit(10);
     

     Execute a célula. Sempre que você carregar a tabela compartilhada, verá dados atualizados da origem.

   • Como usar o SQL:

     Para consultar os dados usando o SQL, você cria uma tabela local no workspace da tabela compartilhada e consultar a tabela local. Os dados compartilhados não são armazenados ou colocados em cache na tabela local. Sempre que você consultar a tabela local, verá o estado atual dos dados compartilhados.

     Em uma nova célula, cole o comando a seguir.

     Substitua as variáveis da seguinte forma:

     • <local-table-name>: o nome da tabela local.
     • <profile-path>: o local do arquivo de credenciais.
     • <share-name>: o valor de share= na tabela.
     • <schema-name>: o valor de schema= na tabela.
     • <table-name>: o valor de name= na tabela.

     %sql
     DROP TABLE IF EXISTS table_name;
     
     CREATE TABLE <local-table-name> USING deltaSharing LOCATION "<profile-path>#<share-name>.<schema-name>.<table-name>";
     
     SELECT * FROM <local-table-name> LIMIT 10;
     

     Quando você executa o comando, os dados compartilhados são consultados diretamente. Como um teste, a tabela é consultada, e os dez primeiros resultados são retornados.

   Se a saída estiver vazia ou não contiver os dados esperados, entre em contato com o provedor de dados.

Apache Spark: ler dados compartilhados

Siga estas etapas para acessar dados compartilhados usando o Spark 3.x ou superior.

Essas instruções pressupõem que você tenha acesso ao arquivo de credencial que foi compartilhado pelo provedor de dados. Confira Obter acesso no modelo de compartilhamento aberto.

Instalar os conectores Delta Sharing Python e Spark

Para acessar metadados relacionados aos dados compartilhados, como a lista de tabelas compartilhadas com você, faça o seguinte. Este exemplo usa o Python.

1. Instale o conector Python do Delta Sharing. Para obter informações sobre as limitações do conector Python, consulte as limitações do conector Python do Delta Sharing.

   pip install delta-sharing
   

2. Instale o Conector do Apache Spark.

Listar tabelas compartilhadas usando o Spark

Liste as tabelas do compartilhamento. No exemplo a seguir, substitua <profile-path> pelo local do arquivo de credenciais.

import delta_sharing

client = delta_sharing.SharingClient(f"<profile-path>/config.share")

client.list_all_tables()

O resultado é uma matriz de tabelas, com metadados para cada tabela. A seguinte saída mostra duas tabelas:

Out[10]: [Table(name='example_table', share='example_share_0', schema='default'), Table(name='other_example_table', share='example_share_0', schema='default')]

Se a saída estiver vazia ou não contiver as tabelas esperadas, entre em contato com o provedor de dados.

Acessar dados compartilhados usando Spark

Execute o seguinte, substituindo estas variáveis:

• <profile-path>: o local do arquivo de credenciais.
• <share-name>: o valor de share= na tabela.
• <schema-name>: o valor de schema= na tabela.
• <table-name>: o valor de name= na tabela.
• <version-as-of>: opcional. A versão da tabela para carregar os dados. Só funciona se o provedor de dados compartilhar o histórico da tabela. Requer o delta-sharing-spark 0.5.0 ou superior.
• <timestamp-as-of>: opcional. Carregue os dados na versão anterior ou no carimbo de data/hora fornecido. Só funciona se o provedor de dados compartilhar o histórico da tabela. Requer o delta-sharing-spark 0.6.0 ou superior.

Python

delta_sharing.load_as_spark(f"<profile-path>#<share-name>.<schema-name>.<table-name>", version=<version-as-of>)

spark.read.format("deltaSharing")\
.option("versionAsOf", <version-as-of>)\
.load("<profile-path>#<share-name>.<schema-name>.<table-name>")\
.limit(10)

delta_sharing.load_as_spark(f"<profile-path>#<share-name>.<schema-name>.<table-name>", timestamp=<timestamp-as-of>)

spark.read.format("deltaSharing")\
.option("timestampAsOf", <timestamp-as-of>)\
.load("<profile-path>#<share-name>.<schema-name>.<table-name>")\
.limit(10)

Scala (linguagem de programação)

spark.read.format("deltaSharing")
.option("versionAsOf", <version-as-of>)
.load("<profile-path>#<share-name>.<schema-name>.<table-name>")
.limit(10)

spark.read.format("deltaSharing")
.option("timestampAsOf", <version-as-of>)
.load("<profile-path>#<share-name>.<schema-name>.<table-name>")
.limit(10)

Acesse o feed de dados de alterações compartilhado usando o Spark

Se o histórico da tabela tiver sido compartilhado com você e o CDF (feed de dados de alteração) estiver habilitado na tabela de origem, acesse o feed de dados de alteração executando o seguinte, substituindo essas variáveis. Requer o delta-sharing-spark 0.5.0 ou superior.

Um parâmetro de início deve ser fornecido.

• <profile-path>: o local do arquivo de credenciais.
• <share-name>: o valor de share= na tabela.
• <schema-name>: o valor de schema= na tabela.
• <table-name>: o valor de name= na tabela.
• <starting-version>: opcional. A versão inicial da consulta, inclusiva. Especifique como um Longo.
• <ending-version>: opcional. A versão final da consulta, inclusiva. Se a versão final não for fornecida, a API usará a versão mais recente da tabela.
• <starting-timestamp>: opcional. O carimbo de data/hora inicial da consulta, ele é convertido em uma versão criada maior ou igual a esse carimbo de data/hora. Esta é uma cadeia de caracteres no formato yyyy-mm-dd hh:mm:ss[.fffffffff].
• <ending-timestamp>: opcional. O carimbo de data final da consulta, isso é convertido em uma versão criada menor ou igual a esse carimbo de data. Esta é uma cadeia de caracteres no formato yyyy-mm-dd hh:mm:ss[.fffffffff]

Python

delta_sharing.load_table_changes_as_spark(f"<profile-path>#<share-name>.<schema-name>.<table-name>",
  starting_version=<starting-version>,
  ending_version=<ending-version>)

delta_sharing.load_table_changes_as_spark(f"<profile-path>#<share-name>.<schema-name>.<table-name>",
  starting_timestamp=<starting-timestamp>,
  ending_timestamp=<ending-timestamp>)

spark.read.format("deltaSharing").option("readChangeFeed", "true")\
.option("startingVersion", <starting-version>)\
.option("endingVersion", <ending-version>)\
.load("<profile-path>#<share-name>.<schema-name>.<table-name>")

spark.read.format("deltaSharing").option("readChangeFeed", "true")\
.option("startingTimestamp", <starting-timestamp>)\
.option("endingTimestamp", <ending-timestamp>)\
.load("<profile-path>#<share-name>.<schema-name>.<table-name>")

Scala (linguagem de programação)

spark.read.format("deltaSharing").option("readChangeFeed", "true")
.option("startingVersion", <starting-version>)
.option("endingVersion", <ending-version>)
.load("<profile-path>#<share-name>.<schema-name>.<table-name>")

spark.read.format("deltaSharing").option("readChangeFeed", "true")
.option("startingTimestamp", <starting-timestamp>)
.option("endingTimestamp", <ending-timestamp>)
.load("<profile-path>#<share-name>.<schema-name>.<table-name>")

Se a saída estiver vazia ou não contiver os dados esperados, entre em contato com o provedor de dados.

Acessar uma tabela compartilhada usando o Streaming Estruturado do Spark

Se o histórico de tabelas for compartilhado com você, será possível transmitir a leitura dos dados compartilhados. Requer o delta-sharing-spark 0.6.0 ou superior.

Opções com suporte:

• ignoreDeletes: ignorar transações que excluem dados.
• ignoreChanges: reprocessar as atualizações se os arquivos foram reescritos na tabela de origem devido a uma operação de alteração de dados, como UPDATE, MERGE INTO, DELETE(dentro de partições) ou OVERWRITE. Linhas inalteradas ainda podem ser emitidas. Portanto, seus consumidores downstream devem ser capazes de lidar com duplicatas. As exclusões não são propagadas downstream. ignoreChanges incorpora ignoreDeletes. Portanto, se você usar ignoreChanges, o fluxo não será interrompido por exclusões ou atualizações na tabela de origem.
• startingVersion: a versão da tabela compartilhada a ser iniciada. Todas as alterações de tabela a partir desta versão (inclusive) são lidas pela fonte de streaming.
• startingTimestamp: o carimbo de data/hora do qual começar. Todas as alterações de tabela confirmadas no ou após o carimbo de data/hora (inclusive) são lidas pela fonte de streaming. Exemplo: "2023-01-01 00:00:00.0".
• maxFilesPerTrigger: o número de novos arquivos a serem considerados em cada microlote.
• maxBytesPerTrigger: a quantidade de dados processada em cada microlote. Essa opção define um "máximo flexível", o que significa que um lote processa aproximadamente essa quantidade de dados e pode processar mais do que o limite para fazer com que a consulta de streaming avance nos casos em que a menor unidade de entrada é maior que esse limite.
• readChangeFeed: o stream lê o feed de dados de alterações da tabela compartilhada.

Opções sem suporte:

• Trigger.availableNow

Exemplos de consultas de Streaming Estruturado

Scala (linguagem de programação)

spark.readStream.format("deltaSharing")
.option("startingVersion", 0)
.option("ignoreChanges", true)
.option("maxFilesPerTrigger", 10)
.load("<profile-path>#<share-name>.<schema-name>.<table-name>")

Python

spark.readStream.format("deltaSharing")\
.option("startingVersion", 0)\
.option("ignoreDeletes", true)\
.option("maxBytesPerTrigger", 10000)\
.load("<profile-path>#<share-name>.<schema-name>.<table-name>")

Veja também os conceitos de Streaming Estruturado.

Ler as tabelas com vetores de exclusão ou mapeamento de colunas ativados

Os vetores de exclusão são um recurso de otimização de armazenamento que seu provedor pode habilitar nas tabelas Delta compartilhadas. Consulte O que são vetores de exclusão?

O Azure Databricks também fornece suporte ao mapeamento de colunas para as tabelas Delta. Consulte Renomear e remover colunas usando o mapeamento de colunas do Delta Lake.

Se seu provedor compartilhou uma tabela com vetores de exclusão ou mapeamento de colunas habilitados, você poderá ler a tabela usando a computação em execução delta-sharing-spark 3.1 ou superior. Se você estiver usando os clusters do Databricks, poderá executar leituras em lote usando um cluster que está executando o Databricks Runtime 14.1 ou superior. As consultas de streaming e CDF exigem o Databricks Runtime 14.2 ou superior.

Você pode executar consultas em lote como estão, pois elas podem resolver responseFormat automaticamente com base nos recursos de tabela da tabela compartilhada.

Para ler um CDF (feed de dados de alteração) ou executar consultas de streaming em tabelas compartilhadas com vetores de exclusão ou mapeamento de colunas habilitado, você deve definir a opção adicional responseFormat=delta.

Os exemplos a seguir mostram consultas em lote, de streaming e CDF:

import org.apache.spark.sql.SparkSession

val spark = SparkSession
        .builder()
        .appName("...")
        .master("...")
        .config("spark.sql.extensions", "io.delta.sql.DeltaSparkSessionExtension")
        .config("spark.sql.catalog.spark_catalog", "org.apache.spark.sql.delta.catalog.DeltaCatalog")
        .getOrCreate()

val tablePath = "<profile-file-path>#<share-name>.<schema-name>.<table-name>"

// Batch query
spark.read.format("deltaSharing").load(tablePath)

// CDF query
spark.read.format("deltaSharing")
  .option("readChangeFeed", "true")
  .option("responseFormat", "delta")
  .option("startingVersion", 1)
  .load(tablePath)

// Streaming query
spark.readStream.format("deltaSharing").option("responseFormat", "delta").load(tablePath)

Pandas: ler dados compartilhados

Siga estas etapas para acessar dados compartilhados na pandas versão 0.25.3 ou superior.

Essas instruções pressupõem que você tenha acesso ao arquivo de credencial que foi compartilhado pelo provedor de dados. Confira Obter acesso no modelo de compartilhamento aberto.

Instale o conector Python do Delta Sharing

Para acessar metadados relacionados aos dados compartilhados, como a lista de tabelas compartilhadas com você, instale o conector do Python do compartilhamento delta. Para obter informações sobre as limitações do conector Python, consulte as limitações do conector Python do Delta Sharing.

pip install delta-sharing

Listar tabelas compartilhadas usando pandas

Para listar as tabelas no compartilhamento, execute o seguinte, substituindo <profile-path>/config.share pelo local do arquivo de credencial.

import delta_sharing

client = delta_sharing.SharingClient(f"<profile-path>/config.share")

client.list_all_tables()

Se a saída estiver vazia ou não contiver as tabelas esperadas, entre em contato com o provedor de dados.

Acessar dados compartilhados usando pandas

Para acessar dados compartilhados usando pandas o Python, execute o seguinte, substituindo as variáveis da seguinte maneira:

• <profile-path>: o local do arquivo de credenciais.
• <share-name>: o valor de share= na tabela.
• <schema-name>: o valor de schema= na tabela.
• <table-name>: o valor de name= na tabela.

import delta_sharing
delta_sharing.load_as_pandas(f"<profile-path>#<share-name>.<schema-name>.<table-name>")

Acessar um feed de dados de alteração compartilhado usando pandas

Para acessar o feed de dados de alteração de uma tabela compartilhada usando pandas Python, execute o seguinte, substituindo as variáveis da seguinte maneira. Um feed de dados de alterações pode não estar disponível, dependendo se o provedor de dados compartilhou ou não o feed de dados de alterações para a tabela.

• <starting-version>: opcional. A versão inicial da consulta, inclusiva.
• <ending-version>: opcional. A versão final da consulta, inclusiva.
• <starting-timestamp>: opcional. O carimbo de data/hora inicial da consulta. Isso é convertido em uma versão criada maior ou igual a esse carimbo de data.
• <ending-timestamp>: opcional. O carimbo de data/hora final da consulta. Isso é convertido em uma versão criada anterior ou igual a esse carimbo de data.

import delta_sharing
delta_sharing.load_table_changes_as_pandas(
  f"<profile-path>#<share-name>.<schema-name>.<table-name>",
  starting_version=<starting-version>,
  ending_version=<ending-version>)

delta_sharing.load_table_changes_as_pandas(
  f"<profile-path>#<share-name>.<schema-name>.<table-name>",
  starting_timestamp=<starting-timestamp>,
  ending_timestamp=<ending-timestamp>)

Se a saída estiver vazia ou não contiver os dados esperados, entre em contato com o provedor de dados.

Power BI: ler dados compartilhados

O conector do Compartilhamento Delta do Power BI permite que você descubra, analise e visualize conjuntos de dados compartilhados com eles pelo protocolo aberto do Compartilhamento Delta.

Requisitos

• Power BI Desktop 2.99.621.0 ou superior.
• Acesso ao arquivo de credencial que foi compartilhado pelo provedor de dados. Confira Obter acesso no modelo de compartilhamento aberto.

Conectar-se ao Databricks

Para se conectar ao Azure Databricks usando o conector de Compartilhamento Delta, faça o seguinte:

1. Abra o arquivo de credencial compartilhada com um editor de texto para recuperar a URL do ponto de extremidade e o token.
2. Abra o Power BI Desktop.
3. No menu Obter Dados, procure Compartilhamento Delta.
4. Selecione o conector e clique em Conectar.
5. Insira a URL do ponto de extremidade que você copiou do arquivo de credenciais para o campo URL do Servidor do Compartilhamento Delta.
6. Opcionalmente, na guia Opções Avançadas, defina um Limite de Linhas para o número máximo de linhas que pode ser baixado. Isso é definido como um milhão de linhas por padrão.
7. Clique em OK.
8. Em Autenticação, copie o token que você recuperou do arquivo de credenciais para Token de Portador.
9. Clique em Conectar.

Limitações do conector do Compartilhamento Delta do Power BI

O Conector de Compartilhamento Delta do Power BI tem as seguintes limitações:

• Os dados carregados pelo conector precisam caber na memória do computador. Para gerenciar esse requisito, o conector limita o número de linhas importadas ao Limite de Linhas definido na guia Opções Avançadas no Power BI Desktop.

Tableau: ler os dados compartilhados

O conector do Compartilhamento Delta do Tableau permite que você descubra, analise e visualize conjuntos de dados que são compartilhados com eles pelo protocolo aberto do Compartilhamento Delta.

Requisitos

• Tableau Desktop e Tableau Server 2024.1 ou posterior
• Acesso ao arquivo de credencial que foi compartilhado pelo provedor de dados. Confira Obter acesso no modelo de compartilhamento aberto.

Conectar o Azure Databricks

Para se conectar ao Azure Databricks usando o conector de Compartilhamento Delta, faça o seguinte:

1. Acesse o Tableau Exchange, siga as instruções para baixar o Conector de Compartilhamento Delta e coloque-o em uma pasta de área de trabalho apropriada.
2. Abra o Tableau Desktop.
3. Na página Conectores, pesquise “Compartilhamento Delta pelo Databricks”.
4. Selecione Carregar o arquivo de compartilhamento e escolha o arquivo de credencial compartilhado pelo provedor.
5. Clique em Obter Dados.
6. No Data Explorer, selecione a tabela.
7. Como opção, adicione filtros SQL ou limites de linha.
8. Clique em Obter Dados da Tabela.

Limitações

O Conector de Compartilhamento Delta do Tableau tem as seguintes limitações:

• Os dados carregados pelo conector precisam caber na memória do computador. Para gerenciar esse requisito, o conector limita o número de linhas importadas ao limite de linha definido no Tableau.
• Todas as colunas são retornadas como tipo String.
• O filtro SQL só funcionará se o servidor do Delta Sharing der suporte a predicateHint.
• Não há suporte para vetores de exclusão.
• Não há suporte para mapeamento de coluna.

Clientes Iceberg: ler tabelas Delta compartilhadas

Use clientes externos do Iceberg, como Snowflake, Trino, Flink e Spark, para ler ativos de dados compartilhados com acesso de cópia zero usando a API do Catálogo REST do Apache Iceberg.

Se você estiver usando o Snowflake, poderá usar o arquivo de credencial para gerar um comando SQL que permite ler tabelas Delta compartilhadas.

Obter credenciais de conexão

Antes de acessar ativos de dados compartilhados com clientes externos do Iceberg, colete as seguintes credenciais:

• O endpoint do Catálogo REST do Iceberg
• Um token de portador válido
• O nome do compartilhamento
• (Opcional) O namespace ou o nome do esquema
• (Opcional) O nome da tabela

O ponto de extremidade REST e o Bearer token estão no arquivo de credenciais fornecido pelo seu provedor de dados. O nome do compartilhamento, o namespace e o nome da tabela podem ser descobertos programaticamente usando APIs de Compartilhamento Delta.

Os exemplos a seguir mostram como obter as credenciais adicionais. Insira o endpoint, o endpoint do Iceberg e o token Bearer do arquivo de credenciais, quando necessário.

// List shares
curl -X GET "<endpoint>/shares" \
   -H "Authorization: Bearer <bearerToken>"

// List namespaces
curl -X GET "<icebergEndpoint>/v1/shares/<share>/namespaces" \
   -H "Authorization: Bearer <bearerToken>"

// List tables
curl -X GET "<icebergEndpoint>/v1/shares/<share>/namespaces/<namespace>/tables" \
   -H "Authorization: Bearer <bearerToken>"

Configurar o catálogo do Iceberg

Depois de obter as credenciais de conexão necessárias, configure seu cliente para usar os endpoints do Catálogo REST do Iceberg para criar e consultar tabelas.

1. Para cada compartilhamento, crie uma integração de catálogo.

   USE ROLE ACCOUNTADMIN;
   
   CREATE OR REPLACE CATALOG INTEGRATION <CATALOG_PLACEHOLDER>
   CATALOG_SOURCE = ICEBERG_REST
   TABLE_FORMAT = ICEBERG
   REST_CONFIG = (
      CATALOG_URI = '<icebergEndpoint>',
      WAREHOUSE = '<share_name>',
      ACCESS_DELEGATION_MODE = VENDED_CREDENTIALS
   )
   REST_AUTHENTICATION = (
      TYPE = BEARER,
      BEARER_TOKEN = '<bearerToken>'
   )
   ENABLED = TRUE;
   

2. Opcionalmente, adicione REFRESH_INTERVAL_SECONDS para manter os metadados atualizados. Defina o valor com base na frequência de atualização do catálogo.

   REFRESH_INTERVAL_SECONDS = 30
   

3. Depois que o catálogo for configurado, crie um banco de dados a partir do catálogo. Isso cria automaticamente todos os esquemas e tabelas nesse catálogo.

   CREATE DATABASE <DATABASE_PLACEHOLDER>
   LINKED_CATALOG = (
      CATALOG = <CATALOG_PLACEHOLDER>
   );
   

4. Para confirmar se o compartilhamento foi bem-sucedido, consulte uma tabela no banco de dados. Você deve ver os dados compartilhados do Azure Databricks.

Se o resultado estiver vazio ou ocorrer um erro, siga estas etapas comuns de solução de problemas:

• Verifique novamente os privilégios, o status de geração de snapshot e as credenciais REST.
• Entre em contato com seu provedor de dados.
• Consulte a documentação específica para seu cliente Iceberg.

Exemplo: ler tabelas Delta compartilhadas no Snowflake usando um comando SQL

Para ler ativos de dados compartilhados no Snowflake, carregue o arquivo de credencial baixado e gere o comando SQL necessário:

1. No link de ativação do Compartilhamento Delta, clique no ícone Floco de Neve.

2. Na página de integração do Snowflake, carregue o arquivo de credencial recebido do provedor de dados.

   

3. Depois de carregar a credencial, escolha o compartilhamento que você deseja acessar no Snowflake.

4. Clique em Gerar SQL depois de selecionar os ativos desejados.

   

5. Copie e cole o SQL gerado em sua planilha do Snowflake. Substitua CATALOG_PLACEHOLDER pelo nome do catálogo que você deseja usar e DATABASE_PLACEHOLDER pelo nome do banco de dados que você deseja usar.

Limitações do floco de neve

Conectar-se ao Catálogo REST do Iceberg em Snowflake tem as seguintes limitações:

• O arquivo de metadados não é atualizado automaticamente com o instantâneo mais recente. Você deve contar com atualização automática ou atualizações manuais.
• Não há suporte para R2.
• Todas as limitações do cliente Iceberg se aplicam.

Limitações do cliente iceberg

As seguintes limitações se aplicam ao consultar dados de compartilhamento Delta de clientes Iceberg:

• Ao listar tabelas em um namespace, se o namespace contiver mais de 100 exibições compartilhadas, a resposta será limitada às primeiras 100 exibições.

Limitações do conector Python do Delta Sharing

Essas limitações são específicas para o conector do Python de Compartilhamento Delta:

• O conector Delta Sharing Python 1.1.0+ dá suporte a consultas de instantâneo em tabelas com mapeamento de coluna, mas consultas CDF em tabelas com mapeamento de coluna não são suportadas.
• O conector de Python do Delta Sharing falhará use_delta_format=True nas consultas CDF se o esquema for alterado durante o intervalo de versão consultado.

Solicitar uma nova credencial

Se a URL de ativação da credencial ou a credencial baixada for perdida, corrompida ou comprometida, ou se a credencial expirar sem que o provedor envie uma nova, entre em contato com o provedor para solicitar uma nova credencial.