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

Este artigo descreve como ler dados que foram compartilhados com você usando o protocolo de compartilhamento aberto Delta Sharing. Ele inclui instruções para ler dados compartilhados usando Databricks, Apache Spark, pandas, Power BI e Tableau.

No compartilhamento aberto, você usa um arquivo de credenciais que foi compartilhado com um membro da sua equipe pelo provedor de dados para obter acesso de leitura seguro aos dados compartilhados. O acesso persiste enquanto a credencial for válida e o provedor continuar a compartilhar os dados. Os provedores gerenciam a expiração e a rotação de credenciais. As atualizações dos dados estão disponíveis para você 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 o Azure Databricks, Apache Spark, pandas e Power BI para acessar e ler dados compartilhados usando o arquivo 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 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 tem de transferir o 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 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 DBFS 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ê.

Neste exemplo, você cria um bloco de anotações com várias células que pode ser executado independentemente. Em vez disso, você pode adicionar os comandos do bloco de anotações à mesma célula e executá-los em sequência.

Etapa 1: Armazenar o arquivo de credenciais no DBFS (instruções do Python)

Nesta etapa, você usa um bloco de anotações Python no Azure Databricks para armazenar o arquivo de credenciais para que os usuários da sua equipe possam acessar dados compartilhados.

Pule para a próxima etapa se você ou alguém da sua equipe já tiver armazenado o arquivo de credenciais no DBFS.

1. Em um editor de texto, abra o arquivo de credenciais.

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

   • Introduza um nome.
   • Defina o idioma padrão para o bloco de anotações como Python.
   • Selecione um cluster para anexar ao bloco de anotações.
   • Clique em Criar.

   O bloco de notas é aberto no editor do bloco de notas.

3. Para usar Python ou pandas para acessar os dados compartilhados, instale o conector Python de compartilhamento delta. No editor de bloco de anotações, cole o seguinte comando:

   %sh pip install delta-sharing
   

4. Execute a célula.

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

5. Em uma nova célula, cole o seguinte comando, que carrega o conteúdo do arquivo de credenciais para uma pasta no DBFS. Substitua as variáveis da seguinte forma:

   • <dbfs-path>: o caminho para a pasta onde você deseja salvar o arquivo de credenciais

   • <credential-file-contents>: o conteúdo do arquivo de credencial. Este não é um caminho para o arquivo, mas o conteúdo copiado do arquivo.

     O arquivo de credenciais contém JSON que define três campos: shareCredentialsVersion, endpointe bearerToken.

     %scala
     dbutils.fs.put("<dbfs-path>/config.share","""
     <credential-file-contents>
     """)
     

6. Execute a célula.

   Depois que o arquivo de credenciais for carregado, você poderá excluir essa célula. Todos os usuários do espaço de trabalho podem ler o arquivo de credenciais do DBFS, e o arquivo de credenciais está disponível no DBFS em todos os clusters e armazéns SQL em seu espaço de trabalho. Para excluir a célula, clique em x no menu de ações da célula à direita.

Etapa 2: usar um bloco de anotações para listar e ler tabelas compartilhadas

Nesta etapa, você lista as tabelas no compartilhamento ou conjunto de tabelas e partições compartilhadas e consulta uma tabela.

1. Usando Python, liste as tabelas no compartilhamento.

   Em uma nova célula, cole o seguinte comando. Substitua <dbfs-path> pelo caminho que foi criado na Etapa 1: armazenar o arquivo de credenciais no DBFS (instruções do Python).

   Quando o código é executado, o Python lê o arquivo de credenciais do DBFS no cluster. Acesse os dados armazenados no DBFS no caminho /dbfs/.

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

2. Execute a 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.

3. Consultar uma tabela compartilhada.

   • Usando o Scala:

     Em uma nova célula, cole o seguinte comando. Quando o código é executado, o arquivo de credenciais é lido do DBFS através da JVM.

     Substitua as variáveis da seguinte forma:

     • <profile-path>: o caminho DBFS do arquivo de credencial. Por exemplo, /<dbfs-path>/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);
     

     Execute a 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 compartilhados não são armazenados ou 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:

   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. A versão da tabela para carregar os dados. Só funciona se o provedor de dados compartilhar o histórico da tabela. Requer delta-sharing-spark 0.5.0 ou superior.
• <timestamp-as-of>: opcional. Carregue os dados na versão antes ou no carimbo de data/hora fornecido. 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))

Scala

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. A versão da tabela para carregar os dados. Só funciona se o provedor de dados compartilhar o histórico da tabela. Requer delta-sharing-spark 0.5.0 ou superior.
• <timestamp-as-of>: opcional. Carregue os dados na versão antes ou no carimbo de data/hora fornecido. Só funciona se o provedor de dados compartilhar o histórico da tabela. Requer delta-sharing-spark 0.6.0 ou superior.

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)

Acessar feed de dados de alteração compartilhado usando o 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, você poderá acessar o feed de dados de alteração executando o seguinte, substituindo essas variáveis. Requer delta-sharing-spark 0.5.0 ou superior.

Deve ser fornecido um único parâmetro de partida.

• <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 um longo.
• <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. O carimbo de data/hora final da consulta, que é convertido em uma versão criada anteriormente ou igual a esse carimbo de data/hora. 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("statingVersion", <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

spark.read.format("deltaSharing").option("readChangeFeed", "true")
.option("statingVersion", <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 compartilhado com você, você poderá transmitir os dados compartilhados. 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 inalteradas 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 a jusante. ignoreChanges subsumes ignoreDeletes. Portanto, se você usar ignoreChangeso , seu fluxo não será interrompido por exclusões ou atualizações da tabela de origem.
• startingVersion: A versão da tabela compartilhada para começar. Todas as alterações de tabela a partir desta versão (inclusive) serão lidas pela fonte de streaming.
• startingTimestamp: O carimbo de data/hora a partir do qual começar. Todas as alterações de tabela confirmadas no ou após o carimbo de data/hora (inclusive) serã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: Stream ler o feed de dados de alteração da tabela compartilhada.

Opções não suportadas:

• Trigger.availableNow

Exemplos de consultas de streaming estruturado

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 Streaming no Azure Databricks.

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 soltar colunas com o mapeamento de colunas 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.

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

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

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 estes passos para aceder a dados partilhados no 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.

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.

Acessar dados compartilhados usando pandas

Para acessar dados compartilhados em pandas usando 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 acessar o feed de dados de alteração para uma tabela compartilhada em pandas usando Python, execute o seguinte, substituindo as variáveis da seguinte maneira. 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 em uma versão criada maior ou igual a esse carimbo de data/hora.
• <ending-timestamp>: opcional. O carimbo de data/hora final da consulta. Isso é convertido em uma versão criada anteriormente ou igual a esse carimbo de data/hora.

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=<starting-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 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 de Compartilhamento Delta.
6. Opcionalmente, na guia Opções Avançadas , defina um Limite de Linha para o número máximo de linhas que você pode baixar. 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 compartilhados

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 superior
• 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, procure por "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 do conector de compartilhamento delta do Tableau

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.

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.