Leia os dados das tabelas OneLake (prévia)

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

Para ler dados de tabela, envie uma solicitação para iniciar uma sessão de leitura. A API retorna um ou mais fluxos de resultados independentes com base no tamanho dos dados que precisam ser retornados. Seu aplicativo pode baixar esses fluxos em paralelo, o que ajuda a ler grandes volumes de dados de tabela mais rapidamente. Após baixar os fluxos, processe os lotes de registros do Apache Arrow para montar o resultado completo.

A API lê a tabela a partir de um ponto consistente no tempo, então cada fluxo de resultados contém dados do mesmo instantâneo, mesmo que a tabela mude enquanto a leitura está em andamento. Também aplica a autorização do OneLake, a segurança em nível de linha (RLS) e a segurança em nível de coluna (CLS) ao chamador autenticado. Isso significa que sua aplicação recebe apenas as linhas e colunas que o chamador está autorizado a acessar, sem precisar reproduzir esses controles de segurança em seu próprio código.

Importante

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

Pré-requisitos

1. Enviar um pedido de linhas de tabela

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

  1. Construa a URL da solicitação substituindo os marcadores de posição pelos identificadores do workspace, item, esquema e tabela que você deseja 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 sua solicitação exige na solicitação. Use a opção columns para especificar quais colunas retornar.

  3. Salve todos os identificadores opacos de fluxo da resposta bem-sucedida. Um grande resultado pode ser dividido em múltiplos fluxos. Você deve recuperar cada fluxo 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 sua solicitação. Cada fluxo dessa resposta usa o mesmo snapshot.

2. Baixe todos os fluxos de resultados

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

Uma sessão de leitura expira após 60 minutos. Recupere todas as transmissões antes que a sessão expire. Se você 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 uma solicitação autenticada 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 stream IPC Apache Arrow.

  3. Processe os lotes de registros conforme chegarem. Transmitir os lotes evita carregar o resultado completo na memória.

  4. Repita a solicitação 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. Use a biblioteca Apache Arrow para a linguagem da sua aplicação para ler os lotes de registros de cada resposta. Para mais informações sobre o formato de fluxo, veja Serialização e comunicação entre processos (IPC).

O corpo da resposta contém dados brutos do fluxo IPC do Apache Arrow, incluindo as informações de esquema necessárias para interpretar os lotes de registros. Não confie na ordem das linhas, nem assuma que a posição de um fluxo na resposta determina sua posição no resultado completo.

Entenda a segurança da OneLake para API de leitura de tabelas

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

  • Se você não tiver permissão para visualizar a tabela, o serviço retornará uma resposta de "não encontrado".
  • Se a segurança em nível de linha (RLS) filtrar todas as linhas que você pode visualizar, a solicitação será bem-sucedida, mas retornará uma resposta Arrow vazia.
  • Se você usar uma projeção de coluna com caractere curinga, a resposta incluirá apenas as colunas que a segurança em nível de coluna (CLS) permite que você visualize.
  • Se você solicitar explicitamente uma coluna que você não pode ver, o serviço retornará 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 um recurso existe.

Considerações e limitações

  • A API de leitura de tabela não suporta atalhos entre regiões.
  • Você é cobrado pela operação POST /read. Recuperar dados usando /readStream não gera um evento separado de leitura de tabela de faturamento. Para mais informações, veja Consumo da API de leitura de tabela.
  • Last updated on