Прочитайте данные таблицы OneLake (предварительный просмотр)

Используйте API чтения таблиц OneLake, чтобы считывать строки из таблицы Delta Lake или Apache Iceberg в OneLake.

Чтобы прочитать данные таблицы, отправьте один запрос на запуск сеанса чтения. API возвращает один или несколько независимых потоков результатов в зависимости от размера данных, которые необходимо вернуть. Ваше приложение может скачивать эти потоки параллельно, что помогает быстрее читать большие объемы таблиц. После загрузки потоков обработайте их пакеты записей Apache Arrow, чтобы сформировать полный результат.

API считывает таблицу из единой точки времени, поэтому каждый поток результатов содержит данные из одного и того же снимка, даже если таблица меняется во время чтения. Он также обеспечивает авторизацию OneLake, безопасность на уровне строк (RLS) и безопасность на уровне столбцов (CLS) для аутентифицированного вызывающего. Это означает, что ваше приложение получает только те строки и столбцы, к которым вызывающий имеет право обращаться, без необходимости воспроизводить эти меры безопасности в собственном коде.

Important

API для чтения таблицы OneLake в настоящее время находится в публичном предварительном просмотре. Функции и поведение могут изменяться до общедоступной доступности.

Необходимые условия

1. Отправьте запрос на строки таблиц

Отправьте POST запрос на маршрут таблицы /read для начала сессии чтения.

  1. Сформируйте URL-адрес запроса, заменив заполнители идентификаторами рабочей области, элемента, схемы и таблицы, данные из которой вы хотите прочитать.

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

  2. Включите в запрос опции чтения, которые требуются в вашей заявке. Используйте columns опцию, чтобы указать, какие столбцы возвращать.

  3. Сохраняйте все непрозрачные идентификаторы потока из успешного ответа. Большой результат может быть разбит на несколько потоков. Чтобы получить все строки, необходимо считать каждый поток.

В ответе начинается сеанс чтения на основе согласованного снимка версий таблицы, необходимых для выполнения вашего запроса. Каждый поток этого ответа использует один и тот же снимок.

2. Скачайте каждый поток результатов

Используйте каждый идентификатор потока из ответа, чтобы получить соответствующую часть результата чтения таблицы.

Сеанс чтения заканчивается через 60 минут. Получите все потоки до истечения срока действия сеанса. Если вы остановитесь после получения лишь части потоков, вы не получите полный результат.

  1. Для каждого идентификатора потока в ответе на распределение отправьте аутентифицированный GET запрос.

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

  2. Откройте тело ответа с помощью считывателя потоков Apache Arrow IPC.

  3. Обрабатывайте партии записей по мере их прибытия. Потоковая передача пакетов позволяет избежать загрузки полного результата в память.

  4. Повторите запрос для каждого идентификатора потока и объедините результаты в соответствии с моделью обработки вашего приложения.

Каждый /readStream ответ — это независимый IPC-поток Apache Arrow. Используйте библиотеку Apache Arrow для языка вашего приложения, чтобы читать партии записей из каждого ответа. Для получения дополнительной информации о формате потока см. раздел «Сериализация и межпроцессная коммуникация (IPC).

Тело ответа содержит необработанные данные потока IPC Apache Arrow, включая сведения о схеме, необходимые для интерпретации пакетов записей. Не полагайтесь на порядок строк и не предполагайте, что положение потока в ответе определяет его позицию в полном результате.

Общие сведения о безопасности OneLake в API чтения таблиц

API обеспечивает безопасность OneLake, используя идентичность, которую представляет ваш токен-носитель:

  • Если у вас нет разрешения на просмотр таблицы, сервис возвращает ответ «не найденный».
  • Если безопасность на уровне строки (RLS) фильтрует каждую доступную строку, запрос выполняется успешно, но возвращает пустой ответ Arrow.
  • Если вы используете проекцию столбцов с подстановочным знаком, ответ содержит только те столбцы, доступ к которым разрешён защитой на уровне столбцов (CLS).
  • Если вы явно запросите столбц, который нельзя просмотреть, сервис возвращает ответ «не найденный».

Поскольку неавторизованные таблицы и столбцы возвращают ненайденные ответы, не используйте ответ «не найденный» для определения существования ресурса.

Рекомендации и ограничения

  • API для чтения таблиц не поддерживает межрегиональные ярлыки.
  • Вам выставили счёт за POST /read операцию. Получение данных с помощью /readStream не создаёт отдельного события по чтению таблиц. Для получения дополнительной информации см . раздел «Потребление API для чтения таблицы».
  • Последнее обновление: