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

Este artigo descreve como ler dados que foram compartilhados com você usando o protocolo de compartilhamento aberto Delta Sharing. 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 compartilhando os dados. Provedores gerenciam expiração e 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.

Observação

Se os dados foram compartilhados com você usando o compartilhamento Delta do Databricks-to-Databricks, você não precisa de um arquivo de credencial para acessar os dados, e estes artigos não se aplicam a você. Para obter instruções, consulte Ler dados compartilhados usando o compartilhamento Delta do Databricks-to-Databricks (para destinatários).

As seções a seguir descrevem como usar Databricks, Apache Spark, pandas e Power BI para acessar e ler o arquivo de credenciais de uso de dados compartilhado. Para obter uma lista completa de conectores Delta compartilhamento e informações sobre como usá-los, consulte a documentação de código aberto Delta compartilhamento. Se você tiver problemas para acessar os dados compartilhados, entre em contato com o provedor de dados.

Observação

As integrações de parceiros são, salvo indicação em contrário, fornecidas por terceiros e você deve ter uma account com o provedor apropriado para o uso de seus produtos e serviços. Embora a Databricks faça o possível para manter esse conteúdo atualizado, não fazemos nenhuma representação em relação às integrações ou à precisão do conteúdo nas páginas de integração de parceiros. Entre em contato com os fornecedores apropriados sobre as integrações.

Antes de começar

Um membro de sua equipe deve downloads o arquivo de credencial compartilhado pelo provedor 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ê.

Databricks: Leia o uso compartilhado de conectores de compartilhamento aberto de dados

Esta seção descreve como usar um conector de compartilhamento aberto para acessar o uso compartilhado de dados de um Notebook em seu workspace Databricks. Você ou outro membro de sua equipe armazena o arquivo de credencial no DBFS e, em seguida, usa-o para autenticar a account Databricks do provedor de dados e ler os dados que o provedor de dados compartilhou com você.

Observação

Se o provedor de dados estiver usando o compartilhamento Databricks-to-Databricks e não tiver compartilhado um arquivo de credencial com você, você deverá acessar o uso de dados Unity Catalog. Para obter instruções, consulte Ler dados compartilhados usando o compartilhamento Delta do Databricks-to-Databricks (para destinatários).

Neste exemplo, você cria um Notebook com várias células que podem ser executadas independentemente. Em vez disso, você pode adicionar os comandos do Notebook à mesma célula e executá-los em sequência.

passo 1: Armazene o arquivo de credencial em DBFS (instruções Python)

Nesta passo, você usa um Python Notebook no Databricks para armazenar o arquivo de credencial para que os usuários da sua equipe possam acessar os dados compartilhados.

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

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

  2. No workspace do Databricks, clique em Novo > Notebook.

    • Insira o nome.

    • Defina o idioma default do Notebook para Python.

    • Selecione um clusters para anexar ao Notebook.

    • Clique em Criar.

    O Notebook é aberto no editor Notebook .

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

    %sh pip install delta-sharing
    
  4. execução da célula.

    A biblioteca Python delta-sharing é instalada nos clusters se ainda não estiver instalada.

  5. Em uma nova célula, cole o seguinte comando, que upload o conteúdo do arquivo de credencial 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 credencial

    • <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 credencial contém JSON que define três campos: shareCredentialsVersion, endpoint e bearerToken.

      %scala
      dbutils.fs.put("<dbfs-path>/config.share","""
      <credential-file-contents>
      """)
      
  6. execução da célula.

    Após o upload do arquivo de credencial, você pode excluir esta célula. Todos os usuários workspace podem ler o arquivo de credencial do DBFS, e o arquivo de credencial está disponível no DBFS em todos os clusters e SQL warehouse em seu workspace. Para excluir a célula, clique em x no menu de ações da célula ações da célula na extrema direita.

passo 2: Use um Notebook para listar e ler tabelas compartilhadas

Nesta passo, você lista as tabelas no compartilhamento ou conjunto de tabelas e partições compartilhadas e query 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 no passo 1: Armazene o arquivo de credenciais em DBFS (instruções Python).

    Quando o código é executado, o Python lê o arquivo de credenciais do DBFS nos clusters. 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. execução da 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. query uma tabela compartilhada.

    • Usando o Scala:

      Em uma nova célula, cole o seguinte comando. Na execução do código, o arquivo de credencial é lido do DBFS por meio 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);
      

      execução da célula. Cada vez que você carrega a tabela compartilhada, você vê novos dados da fonte.

    • Usando SQL:

      Para query o uso de dados SQL, crie uma tabela local no workspace a partir da tabela compartilhada e, em seguida, query a tabela local. Os dados compartilhados não são armazenados ou armazenados em cache na tabela local. Cada vez que você query a tabela local, verá 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>: a localização do arquivo de credencial.

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

      Ao executar o comando, os dados compartilhados são query diretamente. Como teste, a tabela é query e os 10 primeiros resultados são retornados.

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

Apache Spark: ler dados compartilhados

Siga estes passos para acessar o uso compartilhado de dados Spark 3.x ouacima.

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

Instale os conectores Delta compartilhamento Python e Spark

Para acessar os 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 uso compartilhado de dados Spark

execução o seguinte, substituindo essas variáveis:

  • <profile-path>: a localização do arquivo de credencial.

  • <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 a história da tabela. Requer delta-sharing-spark 0.5.0 ouacima.

  • <timestamp-as-of>: opcional. Carregue os dados na versão anterior ou no carimbo de data/hora fornecido. Só funciona se o provedor de dados compartilhar a história da tabela. Requer delta-sharing-spark 0.6.0 ouacima.

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

execução o seguinte, substituindo essas variáveis:

  • <profile-path>: a localização do arquivo de credencial.

  • <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 a história da tabela. Requer delta-sharing-spark 0.5.0 ouacima.

  • <timestamp-as-of>: opcional. Carregue os dados na versão anterior ou no carimbo de data/hora fornecido. Só funciona se o provedor de dados compartilhar a história da tabela. Requer delta-sharing-spark 0.6.0 ouacima.

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

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

Acesse o feed de dados alterados compartilhados usando o Spark

Se a história da tabela foi compartilhada com você e o feed de dados alterados (CDF) está ativado na tabela de origem, você pode acessar o feed de dados alterados executando o seguinte, substituindo essas variáveis. Requer delta-sharing-spark 0.5.0 ouacima.

Um e apenas um parâmetro de começar deve ser fornecido.

  • <profile-path>: a localização do arquivo de credencial.

  • <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 query, inclusive. Especifique como Long.

  • <ending-version>: opcional. A versão final da query, 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 query, este é convertido para uma versão criada maior ou igual a este carimbo de data/hora. Especifique como strings no formato yyyy-mm-dd hh:mm:ss[.fffffffff].

  • <ending-timestamp>: opcional. O carimbo de data/hora final da query, este é convertido para uma versão criada anteriormente ou igual a este carimbo de data/hora. Especifique como strings no formato yyyy-mm-dd hh:mm:ss[.fffffffff]

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

Acesse uma mesa compartilhada usando o Spark transmissão estruturada

Se a história da tabela for compartilhada com você, você poderá ler os dados compartilhados por transmissão. Requer delta-sharing-spark 0.6.0 ouacima.

Opções suportadas:

  • ignoreDeletes: Ignore as transações que excluem dados.

  • ignoreChanges: reprocesse as atualizações se os arquivos foram reescritos na tabela de origem devido a operações de alteração de dados, como UPDATE, MERGE INTO, DELETE (dentro das partições) ou OVERWRITE. Linhas inalteradas ainda podem ser emitidas. Portanto, seus consumidores downstream devem ser capazes de lidar com duplicatas. As exclusões não são propagadas a jusante. ignoreChanges subsume ignoreDeletes. Portanto, se você usar ignoreChanges, sua transmissão não será interrompida por exclusões ou atualizações na tabela de origem.

  • startingVersion: a versão da tabela compartilhada a partir da qual começar. Todas as alterações de tabela a partir desta versão (inclusive) serão lidas pela fonte da transmissão.

  • startingTimestamp: O carimbo de data/hora a partir do qual começar. Todas as alterações de mesa confirmadas no ou após o carimbo de data/hora (inclusive) serão lidas pela fonte de transmissão. Exemplo: "2023-01-01 00:00:00.0".

  • maxFilesPerTrigger: O número de novos arquivos a serem considerados em todos os micro-lotes.

  • maxBytesPerTrigger: A quantidade de dados que é processada em cada micro-lote. Esta opção define um “soft max”, ou seja, uma loteria processa aproximadamente esta quantidade de dados e pode processar mais do que o limite para fazer a query transmitida avançar nos casos em que a menor unidade de entrada for maior que este limite.

  • readChangeFeed: transmissão lê o feed de dados alterados da tabela compartilhada.

Opções não suportadas:

  • Trigger.availableNow

Exemplo queryestruturada transmitida

spark.readStream.format("deltaSharing")
.option("startingVersion", 0)
.option("ignoreChanges", true)
.option("maxFilesPerTrigger", 10)
.load("<profile-path>#<share-name>.<schema-name>.<table-name>")
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 em Databricks.

Ler tabelas com vetores de exclusão ativados

Visualização

Esse recurso está em Prévia Pública.

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

Se o provedor compartilhou uma tabela com vetores de exclusão ativados, o senhor pode ler a tabela usando o compute que está executando o delta-sharing-spark 3.1 ou o acima. Se o senhor estiver usando clusters do Databricks, poderá realizar leituras de lotes usando um cluster que esteja executando o Databricks Runtime 14.1 ou acima. As consultas de CDF e transmissão exigem o Databricks Runtime 14.2 ou superior.

O senhor pode realizar muitas consultas como estão, porque elas podem resolver automaticamente responseFormat com base no recurso de tabela da tabela compartilhada.

Para ler um feed de dados de alteração (CDF) ou para realizar consultas de transmissão em tabelas compartilhadas com vetores de exclusão ou mapeamento de coluna ativados, o senhor deve definir a opção adicional responseFormat=delta.

Os exemplos a seguir mostram consultas de lotes, CDF e transmissão:

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: Leia dados compartilhados

Siga estes passos para acessar dados compartilhados em pandas 0.25.3 ouacima.

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

Instale o conector Python de compartilhamento Delta

Para acessar os 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 credencial.

import delta_sharing

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

client.list_all_tables()

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

Acesse o uso compartilhado de dados pandas

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

  • <profile-path>: a localização do arquivo de credencial.

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

Acesse um feed de dados alterados compartilhado usando pandas

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

  • <starting-version>: opcional. A versão inicial da query, inclusive.

  • <ending-version>: opcional. A versão final da query, inclusive.

  • <starting-timestamp>: opcional. O carimbo de data/hora inicial da query. 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 query. 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 compartilhados

O conector de compartilhamento Delta do Power BI permite que você descubra, analise e visualize dataset compartilhados com você por meio do protocolo aberto de compartilhamento Delta.

Requisitos

Conectar-se ao Databricks

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

  1. Abra o arquivo de credencial compartilhada com um editor de texto para recuperar a URL do terminal e os tokens.

  2. Abra o Power BI Desktop.

  3. No menu Obter Dados , procure Delta compartilhamento.

  4. Selecione o conector e clique em Conectar.

  5. Insira a URL endpoint que você copiou do arquivo de credenciais no campo Delta compartilhamento Server URL .

  6. Opcionalmente, na tab Opções avançadas , defina um Limite de linha para o número máximo de linhas que você pode downloads. Isso é definido como 1 milhão de linhas por default.

  7. Clique em OK.

  8. Para Autenticação, copie os tokens que você recuperou do arquivo de credenciais em Bearer tokenss.

  9. Clique em Conectar.

Limitações do conector Delta Sharing do Power BI

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

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

Solicite uma nova credencial

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