Ler dados partilhados utilizando o Delta Sharing para partilha aberta com tokens de autenticação (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. Inclui instruções para ler dados partilhados utilizando as seguintes ferramentas:

• Databricks
• Apache Spark
• Pandas
• Power BI
• Tabela
• Clientes Iceberg

Neste modelo de compartilhamento aberto, você usa um arquivo de credenciais, compartilhado com um membro da sua equipe pelo provedor de dados, para obter acesso de leitura seguro aos dados compartilhados. O acesso persiste contanto que a credencial seja válida e o provedor continue a partilhar dados. Os provedores gerenciam a expiração e a rotação de 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 secções seguintes descrevem como usar clientes Azure Databricks, Apache Spark, pandasPower BI e Iceberg para aceder e ler dados partilhados usando o ficheiro de credenciais. Para obter uma lista completa de conectores Delta Sharing e informações sobre como usá-los, consulte a documentação de código aberto do Delta Sharing. Se você tiver problemas para acessar os dados compartilhados, entre em contato com o provedor de dados.

Antes de começar

Um membro da sua equipa deve fazer o download do ficheiro de credenciais partilhado pelo fornecedor de dados. Consulte 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 abertos

Esta seção descreve como importar um provedor e como consultar os dados compartilhados no Catalog Explorer ou em um bloco de anotações Python:

• Se o seu espaço de trabalho do Azure Databricks estiver habilitado para o Catálogo Unity, use a interface de utilizador do provedor de importação no Gerenciador de Catálogos. 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 os controles de acesso do Catálogo Unity para conceder acesso a tabelas compartilhadas.
  • Consulte dados compartilhados usando a sintaxe padrão do Catálogo Unity.

• Se seu espaço de trabalho do Azure Databricks não estiver habilitado para o Catálogo Unity, use as instruções do bloco de anotações Python como exemplo.

Explorador de Catálogos

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

1. No seu espaço de trabalho do Azure Databricks, clique no Catálogo para abrir o Catalog Explorer.

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. No separador Partilhado comigo, clique em Importar dados.

4. Insira o nome do provedor.

   O nome não pode incluir espaços.

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

   Muitos provedores têm suas próprias redes 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 Importar.

8. Crie catálogos a partir dos dados compartilhados.

   No separador Partilhas, clique em Criar catálogo na linha da partilha.

   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.

   Consulte Como posso disponibilizar dados partilhados à minha equipa? e Gerir permissões para os esquemas, tabelas e volumes num catálogo de Compartilhamento Delta.

10. Leia os objetos de dados compartilhados como faria com qualquer objeto de dados registrado no Unity Catalog.

    Para obter detalhes e exemplos, consulte aceder a dados em uma tabela ou volume partilhado.

Python

Esta seção descreve como usar um conector de compartilhamento aberto para acessar dados compartilhados usando um bloco de anotações em seu espaço de trabalho do Azure Databricks. Você ou outro membro da sua equipe armazena o arquivo de credenciais 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 credenciais como um arquivo de espaço de trabalho do Azure Databricks para que os usuários da sua equipe possam acessar dados compartilhados.

1. Para importar o arquivo de credenciais em seu espaço de trabalho do Azure Databricks, consulte Importar um arquivo.

2. Conceda permissão a outros usuários para acessar o arquivo clicando no ao lado do arquivo e, em seguida, Compartilhar (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 credenciais está armazenado, use um bloco de anotações para listar e ler tabelas compartilhadas.

1. No espaço de trabalho do Azure Databricks, clique em Novo > Bloco de Anotações.

   Para obter mais informações sobre blocos de anotações do Azure Databricks, consulte Blocos de anotações Databricks.

2. Para usar Python ou pandas para aceder aos dados partilhados, instale o conector Python de partilha delta. No editor de bloco de anotações, cole o seguinte comando:

   %sh pip install delta-sharing
   

3. Executar célula.

   A delta-sharing biblioteca Python é instalada no cluster se ainda não estiver instalada.

4. Usando Python, liste as tabelas no compartilhamento.

   Em uma nova célula, cole o seguinte comando. Substitua o caminho do espaço de trabalho pelo caminho para o ficheiro de credenciais.

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

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

5. Executar célula.

   O resultado é uma matriz de tabelas, juntamente com metadados para cada tabela. A saída a seguir 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 seguinte comando. Quando o código é executado, o arquivo de credenciais é lido do arquivo de espaço de trabalho.

     Substitua as variáveis da seguinte forma:

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

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

     Executar célula. Cada vez que você carrega a tabela compartilhada, você vê dados novos da fonte.

   • Usando SQL:

     Para consultar os dados usando SQL, crie uma tabela local no espaço de trabalho a partir da tabela compartilhada e, em seguida, consulte a tabela local. Os dados partilhados não são armazenados nem armazenados em cache na tabela local. Cada vez que você consulta a tabela local, você vê o estado atual dos dados compartilhados.

     Em uma nova célula, cole o seguinte comando.

     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= para a tabela.
     • <schema-name>: o valor de schema= para a tabela.
     • <table-name>: o valor de name= para a 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 teste, a tabela é consultada e os primeiros 10 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.

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

Instale 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 Python.

1. Instale o conector Python de compartilhamento delta. Para obter informações sobre as limitações do conector Python, consulte Limitações do conector Python de compartilhamento Delta.

   pip install delta-sharing
   

2. Instale o conector Apache Spark.

Listar tabelas compartilhadas usando o Spark

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

import delta_sharing

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

client.list_all_tables()

O resultado é uma matriz de tabelas, juntamente com metadados para cada tabela. A saída a seguir 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 o Spark

Execute o seguinte, substituindo essas variáveis:

• <profile-path>: o local do arquivo de credenciais.
• <share-name>: o valor de share= para a tabela.
• <schema-name>: o valor de schema= para a tabela.
• <table-name>: o valor de name= para a tabela.
• <version-as-of>: opcional. Versão da tabela usada para carregar os dados. Só funciona se o provedor de dados compartilhar o histórico da tabela. Requer a versão delta-sharing-spark 0.5.0 ou superior.
• <timestamp-as-of>: opcional. Carregue os dados na versão correspondente à marca temporal fornecida ou anterior. Só funciona se o provedor de dados compartilhar o histórico da tabela. Requer 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)

linguagem de programação Scala

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)

Aceder ao feed de dados de alterações partilhado usando Spark

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

Deve ser fornecido um parâmetro start.

• <profile-path>: o local do arquivo de credenciais.
• <share-name>: o valor de share= para a tabela.
• <schema-name>: o valor de schema= para a tabela.
• <table-name>: o valor de name= para a tabela.
• <starting-version>: opcional. A versão inicial da consulta, inclusive. Especifique como Long.
• <ending-version>: opcional. A versão final da consulta, inclusive. 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, que é convertido em uma versão criada maior ou igual a esse carimbo de data/hora. Especifique como uma cadeia de caracteres no formato yyyy-mm-dd hh:mm:ss[.fffffffff].
• <ending-timestamp>: opcional. A data limite da consulta, que é transformada numa versão criada previamente ou igual a esta marca temporal. Especificar como 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>")

linguagem de programação Scala

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 Spark Structured Streaming

Se o histórico da tabela for partilhado consigo, poderá ler em fluxo contínuo os dados partilhados. Requer delta-sharing-spark 0.6.0 ou superior.

Opções suportadas:

• ignoreDeletes: Ignore transações que excluem dados.
• ignoreChanges: Reprocesse 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 que não foram alteradas ainda podem ser emitidas. Por conseguinte, os seus consumidores a jusante devem ser capazes de lidar com duplicados. As eliminações não são propagadas para os níveis seguintes. ignoreChanges abarca ignoreDeletes. Portanto, se utilizar ignoreChanges, o seu fluxo não será interrompido por exclusões ou atualizações na tabela de origem.
• startingVersion: A versão da tabela partilhada para começar. Todas as alterações de tabela a partir desta versão (inclusive) são lidas pela fonte de streaming.
• startingTimestamp: A data e hora de início. 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 que são processados em cada microlote. Esta opção define um "soft max", o que significa que um lote processa aproximadamente essa quantidade de dados e pode processar mais do que o limite para fazer a consulta de streaming avançar nos casos em que a menor unidade de entrada é maior do que esse limite.
• readChangeFeed: O stream lê o feed de dados de alteração da tabela partilhada.

Opções não suportadas:

• Trigger.availableNow

Exemplos de consultas de streaming estruturado

linguagem de programação Scala

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

Consulte também os conceitos de Streaming estruturado.

Ler tabelas com vetores de exclusão ou mapeamento de colunas habilitados

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

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

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

Pode realizar consultas em lote tal como estão, pois estas conseguem resolver automaticamente responseFormat com base nas funcionalidades da tabela compartilhada.

Para ler um feed de dados de alteração (CDF) ou para executar consultas de streaming em tabelas partilhadas com vetores de eliminação ou mapeamento de colunas ativados, deve definir a opção adicional responseFormat=delta.

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

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 partilhados

Siga estas etapas para acessar dados compartilhados em pandas 0.25.3 ou superior.

Estas instruções pressupõem que você tenha acesso ao arquivo de credenciais que foi compartilhado pelo provedor de dados. Consulte 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ê, você deve instalar o conector Python de compartilhamento delta. Para obter informações sobre as limitações do conector Python, consulte Limitações do conector Python de compartilhamento Delta.

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

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.

Aceda a dados partilhados utilizando pandas

Para acessar dados compartilhados usando pandas 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= para a tabela.
• <schema-name>: o valor de schema= para a tabela.
• <table-name>: o valor de name= para a 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 aceder ao feed de dados de alteração para uma tabela partilhada em pandas utilizando o Python, execute o seguinte, alterando as variáveis da forma seguinte. Um feed de dados de alteração pode não estar disponível, dependendo se o provedor de dados compartilhou ou não o feed de dados de alteração para a tabela.

• <starting-version>: opcional. A versão inicial da consulta, inclusive.
• <ending-version>: opcional. A versão final da consulta, inclusive.
• <starting-timestamp>: opcional. O carimbo de data/hora inicial da consulta. Isso é convertido para uma versão criada maior ou igual a este carimbo de data/hora.
• <ending-timestamp>: opcional. O marcador de tempo final da consulta. Isto é convertido em uma versão criada anteriormente ou igual a esta marca temporal.

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 partilhados

O conector de Partilha Delta do Power BI permite-lhe descobrir, analisar e visualizar conjuntos de dados partilhados consigo através do protocolo aberto de Partilha Delta.

Requisitos

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

Conecte-se ao Databricks

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

1. Abra o arquivo de credenciais compartilhadas com um editor de texto para recuperar a URL do ponto de extremidade e o token.
2. Abra Power BI Desktop.
3. No menu Obter dados, procure Partilha Delta.
4. Selecione o conector e clique em Conectar.
5. Insira a URL do ponto de extremidade que copiou do arquivo de credenciais no campo URL do Servidor de 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 transferir. Isso é definido como 1 milhão de linhas por padrão.
7. Clique em OK.
8. Para Autenticação, copie o token recuperado do arquivo de credenciais para o Token do Portador.
9. Clique em Ligar.

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

O Power BI Delta Sharing Connector tem as seguintes limitações:

• Os dados que o conector carrega devem caber na memória da sua máquina. Para gerenciar esse requisito, o conector limita o número de linhas importadas ao Limite de Linha definido na guia Opções Avançadas no Power BI Desktop.

Tableau: Ler dados partilhados

O conector de compartilhamento delta do Tableau permite descobrir, analisar e visualizar conjuntos de dados compartilhados com você por meio do protocolo aberto de compartilhamento delta.

Requisitos

• Tableau Desktop e Tableau Server 2024.1 ou mais recente
• Acesso ao arquivo de credenciais que foi compartilhado pelo provedor de dados. Consulte Obter acesso no modelo de compartilhamento aberto.

Ligar ao Azure Databricks

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

1. Vá para o Tableau Exchange, siga as instruções para baixar o Delta Sharing Connector e coloque-o em uma pasta de área de trabalho apropriada.
2. Abra o Tableau Desktop.
3. Na página Conectores, pesquise "Delta Sharing by Databricks".
4. Selecione Carregar arquivo de compartilhamento e escolha o arquivo de credenciais que foi compartilhado pelo provedor.
5. Clique em Obter Dados.
6. No Data Explorer, selecione a tabela.
7. Opcionalmente, adicione filtros SQL ou limites de linha.
8. Clique em Obter dados da tabela.

Limitações

O Tableau Delta Sharing Connector tem as seguintes limitações:

• Os dados que o conector carrega devem caber na memória da sua máquina. Para gerenciar esse requisito, o conector limita o número de linhas importadas ao limite de linhas definido no Tableau.
• Todas as colunas são retornadas como tipo String.
• O Filtro SQL só funciona se o seu servidor de Partilha Delta suportar predicateHint.
• Não há suporte para vetores de exclusão.
• Não há suporte para mapeamento de colunas.

Clientes Iceberg: Ler tabelas Delta partilhadas

Utilize clientes externos Iceberg, como Snowflake, Trino, Flink e Spark, para ler ativos de dados partilhados com acesso sem cópia, utilizando a API do Catálogo REST do Apache Iceberg.

Se estiveres a usar o Snowflake, podes usar o ficheiro de credenciais para gerar um comando SQL que te permita ler tabelas Delta partilhadas.

Obter credenciais de ligação

Antes de aceder a ativos de dados partilhados com clientes Iceberg externos, recolha as seguintes credenciais:

• O ponto final do Catálogo Iceberg REST
• Um token portador válido
• O nome do compartimento
• (Opcional) O nome do espaço de nomes ou do esquema
• (Opcional) O nome da tabela

O endpoint REST e o token Bearer estão no ficheiro de credenciais fornecido pelo seu fornecedor de dados. O nome da partilha, o espaço de nomes e o nome da tabela podem ser descobertos programaticamente usando as APIs Delta Sharing.

Os exemplos seguintes mostram como obter as credenciais adicionais. Introduza o endpoint, o endpoint Iceberg e o token Bearer a partir do ficheiro de credencial, onde 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 catálogo Iceberg

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

1. Para cada partilha, 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, adiciona REFRESH_INTERVAL_SECONDS para manter os metadados atualizados. Define o valor com base na frequência de atualização do teu catálogo.

   REFRESH_INTERVAL_SECONDS = 30
   

3. Depois de configurado o catálogo, cria-se uma base de dados a partir do catálogo. Isto cria automaticamente todos os esquemas e tabelas desse catálogo.

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

4. Para confirmar que a partilha foi bem-sucedida, faça uma consulta a partir de uma tabela na base de dados. Deverias ver os dados partilhados do Azure Databricks.

Se o resultado estiver vazio ou ocorrer um erro, siga estes passos comuns de resolução de problemas:

• Verifique novamente os privilégios, o estado da geração de snapshots e as credenciais REST.
• Contacte o seu fornecedor de dados.
• Consulte a documentação específica do seu cliente Iceberg.

Exemplo: Ler tabelas Delta partilhadas no Snowflake usando um comando SQL

Para ler os ativos de dados partilhados no Snowflake, carregue o ficheiro de credencial que descarregou e gere o comando SQL necessário:

1. A partir do seu link de ativação do Delta Sharing, clique no ícone Floco de Neve.

2. Na página de integração do Snowflake, carregue o ficheiro de credencial que recebeu do fornecedor de dados.

   

3. Depois de carregar a credencial, escolha a partilha que quer aceder no Snowflake.

4. Clica em Gerar SQL depois de selecionares os assets desejados.

   

5. Copie e cole o SQL gerado na sua folha de trabalho do Snowflake. Substitui CATALOG_PLACEHOLDER pelo nome do catálogo que queres usar e DATABASE_PLACEHOLDER pelo nome da base de dados que queres usar.

Limitações dos flocos de neve

A ligação ao catálogo Iceberg REST em Snowflake tem as seguintes limitações:

• O ficheiro de metadados não é atualizado automaticamente com o snapshot mais recente. Deve confiar na atualização automática ou nas atualizações manuais.
• R2 não é suportado.
• Todas as limitações do cliente Iceberg aplicam-se.

Limitações do cliente Iceberg

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

• Ao listar tabelas num espaço de nomes, se o espaço de nomes contiver mais de 100 vistas partilhadas, a resposta limita-se às primeiras 100 visualizações.

Limitações do conector Python do Delta Sharing

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

• O conector Python Delta Sharing 1.1.0+ suporta consultas de instantâneo em tabelas com mapeamento de colunas, mas não suporta consultas CDF em tabelas com mapeamento de colunas.
• O conector Delta Sharing Python falha nas consultas CDF com use_delta_format=True se o esquema mudar durante o intervalo de versões consultadas.

Solicitar uma nova credencial

Se o 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.