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
• Clientes Iceberg
• Apache Spark
• Pandas
• Power BI
• Tableau

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, pandas, Power BI e Iceberg para aceder e ler dados partilhados usando o ficheiro de credenciais. Para uma lista completa de conectores Delta Sharing e informações sobre como os utilizar, consulte a documentação open source 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 descarregar o ficheiro de credencial partilhado pelo fornecedor de dados e usar um canal seguro para partilhar esse ficheiro ou localização do ficheiro consigo. Consulte Obter acesso no modelo de compartilhamento aberto.

Para documentação específica do conector, consulte a página de credenciais de download.

Azure Databricks: Leia dados partilhados usando conectores abertos de partilha

Esta secção descreve como importar um fornecedor e como consultar os dados partilhados no Explorador de Catálogos ou num caderno Python:

• Se o seu espaço de trabalho do Azure Databricks estiver ativado para o Unity Catalog, use a interface do Import provider no Catalog Explorer. 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 o seu espaço de trabalho do Azure Databricks não estiver ativado para o Unity Catalog, use as instruções do notebook em 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 Azure Databricks, clique em Catalog para abrir o Explorador de Catálogos.

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

   Alternativamente, no canto superior direito, clique em Partilhar > Delta Sharing.

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 secção descreve como usar um conector aberto de partilha para aceder a dados partilhados usando um caderno no seu espaço de trabalho Azure Databricks. Você ou outro membro da sua equipa armazena o ficheiro de credencial no Azure Databricks, depois usa-o para autenticar na conta Azure Databricks do fornecedor de dados e ler os dados que o fornecedor partilhou contigo.

Primeiro, armazene o ficheiro de credencial como um ficheiro de espaço de trabalho do Azure Databricks para que os utilizadores da sua equipa possam aceder a dados partilhados.

1. Para importar o ficheiro de credenciais no seu espaço de trabalho de Azure Databricks, veja Importar um ficheiro.

2. Conceda permissão a outros usuários para acessar o arquivo clicando no ao lado do arquivo e, em seguida, Compartilhar (Permissões). Introduza as identidades do Azure Databricks que devem ter acesso ao ficheiro.

   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 seu espaço de trabalho Azure Databricks, clique no Novo > Bloco de Notas.

   Para mais informações sobre os notebooks do Azure Databricks, veja Databricks notebooks.

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

   %sh pip install delta-sharing
   

3. Executar célula.

   A biblioteca delta-sharing Python está instalada no cluster, caso ainda não esteja instalada.

4. Usando Python, enumera 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 ficheiro de credencial.

   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.

     Para consultar colunas de rastreamento de linhas numa tabela partilhada, veja Ler colunas de rastreio de linhas em tabelas partilhadas.

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

Clientes Iceberg: Leia dados partilhados

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.

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 do Iceberg REST Catalog (icebergEndpoint) e o token Bearer encontram-se no ficheiro de credenciais partilhado consigo pelo seu fornecedor de dados. Para obter mais informações, consulte Antes de começar. 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 do ficheiro de credenciais 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. Deves 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: Aceder a tabelas partilhadas usando diferentes clientes Iceberg

Os exemplos seguintes mostram como aceder a tabelas partilhadas Delta usando clientes externos Iceberg, como Snowflake, Apache Spark, PyIceberg e API REST, após obter as suas credenciais de ligação. Para mais informações sobre como obter credenciais de ligação, consulte Antes de começar.

Snowflake

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

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.

Apache Spark

Para aceder a tabelas partilhadas usando o Apache Spark, configure a API do Catálogo REST do Iceberg com as seguintes definições. Substitua <spark-catalog-name> por um nome para o seu catálogo e forneça as suas credenciais de ligação:

"spark.sql.extensions": "org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions",

# Configuration for accessing tables shared using Delta Sharing
"spark.sql.catalog.<spark-catalog-name>":"org.apache.iceberg.spark.SparkCatalog",
"spark.sql.catalog.<spark-catalog-name>.type": "rest",
"spark.sql.catalog.<spark-catalog-name>.uri": "<icebergEndpoint>",
"spark.sql.catalog.<spark-catalog-name>.token": "<bearerToken>",
"spark.sql.catalog.<spark-catalog-name>.warehouse":"<share_name>",
"spark.sql.catalog.<spark-catalog-name>.scope":"all-apis"

PyIceberg

PyIceberg é uma implementação Python para aceder a tabelas Iceberg sem usar uma JVM. O PyIceberg exige pyarrow operações de tabela, como ler dados e inspecionar metadados de tabelas. Instale o PyIceberg com o pyarrow extra:

pip install "pyiceberg[pyarrow]"

Para aceder a tabelas partilhadas, adicione a seguinte configuração de catálogo ao seu ficheiro de configuração PyIceberg:

catalog:
  delta_sharing:
    type: rest
    uri: <icebergEndpoint>
    warehouse: <share_name>
    token: <bearerToken>

API REST

Use uma chamada de API REST como o exemplo seguinte curl para carregar uma tabela e recuperar os seus metadados juntamente com credenciais temporárias para aceder aos ficheiros de dados:

curl -X GET -H "Authorization: Bearer <bearerToken>" -H "Accept: application/json" \
<icebergEndpoint>/v1/shares/<share_name>/namespaces/<schema_name>/tables/<table_name>

A resposta inclui os metadados da tabela Iceberg, a localização S3 e credenciais temporárias AWS que permitem ao seu cliente ler os ficheiros de dados:

{
  "metadata-location": "s3://bucket/path/to/iceberg/table/metadata/file",
  "metadata": <iceberg-table-metadata-json>,
  "config": {
    "expires-at-ms": "<epoch-ts-in-millis>",
    "s3.access-key-id": "<temporary-s3-access-key-id>",
    "s3.session-token": "<temporary-s3-session-token>",
    "s3.secret-access-key": "<temporary-secret-access-key>",
    "client.region": "<aws-bucket-region-for-metadata-location>"
  }
}

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.

Apache Spark: Ler dados partilhados

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 delta-sharing. Para informações sobre limitações de conectores Python, veja Delta Sharing limitações de conectores Python.

   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

Python

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

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

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. Ver Vetores de eliminação em Databricks.

O Azure Databricks também suporta 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)

Leitura de colunas de rastreio de linhas em tabelas partilhadas

Se o fornecedor de dados tiver ativado o rastreio de linhas numa tabela partilhada, pode consultar as colunas de metadados de rastreio de linhas usando o Scala Spark. Consulte o rastreamento de linhas no Databricks para obter uma lista das colunas disponíveis.

Deve definir a responseFormat opção para delta.

spark.read.format("deltaSharing")
  .option("responseFormat", "delta")
  .load("<profile-path>#<share-name>.<schema-name>.<table-name>")
  .select("_metadata.row_id")
  .show()

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 Delta Sharing Python

Para aceder a metadados relacionados com os dados partilhados, como a lista de tabelas partilhadas consigo, deve instalar o conector Python delta-sharing. Para informações sobre limitações dos conectores Python, veja limitações dos conectores Delta Sharing Python.

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 aceder a dados partilhados em pandas usando Python, execute o seguinte, substituindo as variáveis da seguinte forma:

• <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 de uma tabela partilhada em pandas usando Python execute o seguinte, substituindo as variáveis da seguinte forma. 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 Power BI Delta Sharing permite-lhe descobrir, analisar e visualizar conjuntos de dados partilhados consigo através do protocolo aberto Delta Sharing.

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 ligar ao Azure Databricks usando o conector Delta Sharing, 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 o 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 Power BI Delta Sharing

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

• Os dados que o conector carrega devem caber na memória da sua máquina. Para gerir este requisito, o conector limita o número de linhas importadas ao Limite de Linhas que definiste no separador 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.

Conectar ao Azure Databricks

Para se ligar ao Azure Databricks usando o conector Delta Sharing, faça o seguinte:

1. Vai a Tableau Exchange, segue as instruções para descarregar o Delta Sharing Connector e coloca-o numa pasta de ambiente 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 explorador de dados, 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.

Limitações do conector Delta Sharing Python

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

• O conector Delta Sharing Python 1.1.0+ suporta consultas snapshot 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 tiver mudado durante o intervalo de versões consultado.

Limitações da tabela de streaming

Só pode ler o snapshot atual de uma tabela de streaming partilhada. As seguintes funcionalidades não são suportadas para streaming de tabelas em partilha aberta:

• Consulta dos dados históricos da tabela
• Consultar o feed de dados de alteração (CDF) da tabela
• Usar a tabela como fonte para o Spark Structured Streaming

Limitações da vista materializada

Só pode ler o instantâneo atual de uma vista materializada partilhada. Utilizar uma vista materializada como fonte para o Spark Structured Streaming não é suportado na partilha aberta.

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.