Leia dados partilhados através da partilha OpenSharing Databricks-to-Open com tokens de portador

Esta página descreve como ler dados partilhados consigo utilizando o protocolo OpenSharing open 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 partilha Databricks-to-Open, utiliza-se um ficheiro de credencial, partilhado com um membro da sua equipa pelo fornecedor de dados, para obter acesso seguro em leitura aos dados partilhados. 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 OpenSharing e informações sobre como os utilizar, consulte a documentação open source do OpenSharing. 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 Como obter acesso no modelo de partilha Databricks-to-Open.

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

Azure Databricks: Leia dados partilhados usando conectores de partilha Databricks-to-Open

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.
  • Aplique uma credencial rotativa ao objeto fornecedor existente sem recriar o catálogo. Ver Rotação de credenciais para destinatários abertos.

• 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. No topo do painel de Catálogo , clique no selecione OpenSharing.

   Alternativamente, no canto superior direito, clique em Partilhar > OpenSharing.

3. No separador Partilhado comigo, clique em Instalar partilha.

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 fornecedores têm as suas próprias redes OpenSharing das quais pode receber partilhas. 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 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.

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

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 de partilha Databricks-to-Open 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 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 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 de partilha delta. No editor de bloco de anotações, cole o seguinte comando:

   %sh pip install delta-sharing
   

3. Executar a célula.

   A biblioteca delta-sharing Python está instalada no cluster, caso ainda não esteja 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 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.

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 a 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, espaço de nomes e nome da tabela podem ser descobertos programaticamente usando APIs OpenSharing.

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. 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: Aceder a tabelas partilhadas usando diferentes clientes Iceberg

Os exemplos seguintes mostram como aceder a tabelas openshared usando clientes Iceberg externos, como Snowflake, Apache Spark, PyIceberg e REST API, 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. No link de ativação do OpenSharing, 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 em 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 OpenSharing 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 Como obter acesso no modelo de partilha Databricks-to-Open.

Instale os conectores OpenSharing 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 informações sobre as limitações dos conectores Python, veja limitações dos conectores Python do OpenSharing.

   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)

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

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 remoções não são propagadas nas etapas subsequentes. ignoreChanges engloba 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 a partir da qual iniciar. 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>")

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 dá suporte ao mapeamento de colunas para tabelas Delta. ** Consulte Renomear e remover colunas utilizando o mapeamento de colunas no 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 coluna ativados, deve-se 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 Como obter acesso no modelo de partilha Databricks-to-Open.

Instale o conector Python do OpenSharing

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 as limitações dos conectores Python, veja limitações dos conectores Python do OpenSharing.

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 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 Power BI OpenSharing permite-lhe descobrir, analisar e visualizar conjuntos de dados partilhados consigo através do protocolo aberto OpenSharing.

Requerimentos

• Power BI Desktop 2.99.621.0 ou superior.
• Acesso ao arquivo de credenciais que foi compartilhado pelo provedor de dados. Consulte Como obter acesso no modelo de partilha Databricks-to-Open.

Conecte-se ao Databricks

Para se ligar ao Azure Databricks usando o conector OpenSharing, 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 por OpenSharing.
4. Selecione o conector e clique em Conectar.
5. Introduza o URL do endpoint que copiou do ficheiro de credenciais no campo URL do OpenSharing Server .
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 Conectar.

Limitações do conector Power BI OpenSharing

O Power BI OpenSharing 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 Tableau OpenSharing permite-lhe descobrir, analisar e visualizar conjuntos de dados que são partilhados consigo através do protocolo aberto OpenSharing.

Requerimentos

• Tableau Desktop e Tableau Server 2024.1 ou mais recente
• Acesso ao arquivo de credenciais que foi compartilhado pelo provedor de dados. Consulte Como obter acesso no modelo de partilha Databricks-to-Open.

Ligar ao Azure Databricks

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

1. Vai ao Tableau Exchange, segue as instruções para descarregar o OpenSharing Connector e coloca-o numa pasta apropriada.
2. Abra o Tableau Desktop.
3. Na página de Conectores , procure por "OpenSharing 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 OpenSharing 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 SQL Filter só funciona se o seu servidor OpenSharing suportar o predicateHint.
• Não há suporte para vetores de exclusão.
• Não há suporte para mapeamento de colunas.

Limitações do conector OpenSharing Python

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

• O conector Python OpenSharing 1.1.0+ suporta consultas de snapshot em tabelas com mapeamento de colunas, mas as consultas de CDF em tabelas com mapeamento de colunas não são suportadas.
• O conector Python OpenSharing faz falhar consultas CDF com use_delta_format=True se o esquema tiver sido alterado 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 na partilha Databricks-to-Open:

• 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. A utilização de uma vista materializada como origem para o Spark Structured Streaming não é suportada na partilha Databricks-to-Open.

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.

Se for um destinatário do Azure Databricks que importou a credencial como objeto fornecedor no Unity Catalog, aplique a nova credencial usando a API REST do Databricks. Ver Rotação de credenciais para destinatários abertos.