Leia os dados das tabelas OneLake (pré-visualização)

Use a API de leitura de tabelas OneLake para ler linhas de uma tabela Delta Lake ou Apache Iceberg no OneLake.

Para ler os dados da tabela, envie um pedido para iniciar uma sessão de leitura. A API devolve um ou mais fluxos de resultados independentes com base no tamanho dos dados que precisam de ser devolvidos. A sua aplicação pode descarregar estes fluxos em paralelo, o que a ajuda a ler grandes volumes de dados de tabela mais rapidamente. Depois de transferir os fluxos de dados, processe os lotes de registos do Apache Arrow para compor o resultado completo.

A API lê a tabela num determinado momento no tempo de forma consistente, pelo que cada fluxo de resultados contém dados da mesma captura, mesmo que a tabela mude enquanto a leitura está a decorrer. Também aplica autorização OneLake, segurança ao nível de linha (RLS) e segurança ao nível de coluna (CLS) para o chamador autenticado. Isto significa que a sua aplicação recebe apenas as linhas e colunas a que o chamador está autorizado a aceder, sem necessidade de reproduzir esses controlos de segurança no seu próprio código.

Importante

A API de leitura de tabelas do OneLake está atualmente em pré-visualização pública. As funcionalidades e o comportamento podem mudar antes da disponibilidade geral.

Pré-requisitos

1. Enviar um pedido de linhas de tabela

Envie um POST pedido para a rota da tabela /read para iniciar uma sessão de leitura.

  1. Constrói o URL do pedido substituindo os marcadores de posição pelos identificadores do espaço de trabalho, item, esquema e tabela que queres ler.

    POST <TableReadBaseUrl>/v1.0/workspaces/<WorkspaceID>/items/<ItemID>/schemas/<SchemaName>/tables/<TableName>/read
Authorization: Bearer <BearerToken>

  2. Inclua as opções de leitura que a sua candidatura exige no pedido. Use a columns opção para especificar quais as colunas a devolver.

  3. Guarde todos os identificadores de stream opacos da resposta bem-sucedida. Um grande resultado pode ser dividido em vários fluxos. Tens de recuperar todas as transmissões para receber todas as linhas.

A resposta inicia uma sessão de leitura sobre um snapshot consistente das versões das tabelas necessárias para o seu pedido. Cada fluxo desta resposta utiliza o mesmo instantâneo.

2. Descarregar todos os fluxos de resultados

Use cada identificador de fluxo da resposta para recuperar a sua parte correspondente do resultado da leitura da tabela.

Uma sessão de leitura termina após 60 minutos. Recupera todas as transmissões antes da sessão expirar. Se parar depois de recuperar apenas alguns fluxos, não receberá o resultado completo.

  1. Para cada identificador de fluxo na resposta de alocação, envie um pedido autenticado GET.

    GET <TableReadBaseUrl>/v1.0/workspaces/<WorkspaceID>/items/<ItemID>/schemas/<SchemaName>/tables/<TableName>/readStream/<StreamID>
Authorization: Bearer <BearerToken>

  2. Abra o corpo de resposta com um leitor de fluxo IPC Apache Arrow.

  3. Processa os lotes de registos à medida que chegam. Transmitir os lotes evita carregar o resultado completo na memória.

  4. Repita o pedido para cada identificador de fluxo e combine os resultados de acordo com o modelo de processamento da sua aplicação.

Cada resposta /readStream é um fluxo IPC independente do Apache Arrow. Utilize a biblioteca Apache Arrow para a linguagem de programação da sua aplicação para ler os lotes de registos de cada resposta. Para mais informações sobre o formato do fluxo, veja Serialização e comunicação entre processos (IPC).

O corpo da resposta contém dados em bruto do fluxo IPC do Apache Arrow, incluindo a informação sobre o esquema necessária para interpretar os blocos de registos. Não confie na ordem das linhas, nem assuma que a posição de um fluxo na resposta determina a sua posição no resultado completo.

Compreenda a segurança OneLake para API de leitura de tabelas

A API reforça a segurança do OneLake usando a identidade que o seu token portador representa:

  • Se não tiver permissão para visualizar a tabela, o serviço devolve uma resposta não encontrada.
  • Se a segurança ao nível da linha (RLS) filtrar todas as linhas que consegue visualizar, o pedido tem sucesso mas devolve uma resposta Arrow vazia.
  • Se usar uma projeção de coluna coringa, a resposta inclui apenas colunas que a segurança ao nível da coluna (CLS) permite visualizar.
  • Se solicitar explicitamente uma coluna que não pode ver, o serviço devolve uma resposta de não encontrado.

Como tabelas e colunas não autorizadas retornam respostas não encontradas, não use uma resposta não encontrada para determinar se existe um recurso.

Considerações e limitações

  • A API de leitura de tabela não suporta atalhos entre regiões.
  • É cobrado pela operação POST /read. Recuperar dados usando /readStream não gera um evento separado de leitura de tabela de faturação. Para mais informações, consulte Consumo da API de leitura de tabelas.
  • Última atualização a