Nota:
El acceso a esta página requiere autorización. Puede intentar iniciar sesión o cambiar directorios.
El acceso a esta página requiere autorización. Puede intentar cambiar los directorios.
Utiliza la API de lectura de tabelas de OneLake para leer filas de una tabla de Delta Lake o Apache Iceberg en OneLake.
Para leer los datos de la tabla, envía una solicitud para iniciar una sesión de lectura. La API devuelve uno o más flujos de resultados independientes según el tamaño de los datos que deben ser devueltos. Tu aplicación puede descargar estos flujos en paralelo, lo que le ayuda a leer grandes volúmenes de datos de tablas más rápidamente. Después de descargar los streams, procesa sus lotes de registros de Apache Arrow para ensamblar el resultado completo.
La API lee la tabla desde un punto consistente en el tiempo, por lo que cada flujo de resultados contiene datos de la misma instantánea, incluso si la tabla cambia mientras la lectura está en curso. También aplica la autorización de OneLake, la seguridad a nivel de fila (RLS) y la seguridad a nivel de columna (CLS) al usuario autenticado. Esto significa que tu aplicación solo recibe las filas y columnas a las que el llamante está autorizado a acceder, sin necesidad de reproducir estos controles de seguridad en su propio código.
Important
La API de lectura de tablas de OneLake está actualmente en vista previa pública. Las características y el comportamiento pueden cambiar antes de la disponibilidad general.
Prerequisites
- Completar los requisitos previos de la API de tablas compartidas y los pasos de autenticación.
- Un cliente HTTP que puede procesar un flujo IPC de Apache Arrow sin almacenar en búfer la respuesta completa.
1. Enviar una solicitud para obtener filas de una tabla
Envía una POST solicitud a la ruta /read de la tabla para iniciar una sesión de lectura.
Construye la URL de la solicitud reemplazando los marcadores de posición por los identificadores del espacio de trabajo, elemento, esquema y tabla que quieres leer.
POST <TableReadBaseUrl>/v1.0/workspaces/<WorkspaceID>/items/<ItemID>/schemas/<SchemaName>/tables/<TableName>/read Authorization: Bearer <BearerToken>Incluye las opciones de lectura que tu solicitud requiera en la solicitud. Usa la
columnsopción para especificar qué columnas devolver.Guarda todos los identificadores opacos de flujo de la respuesta correcta. Un resultado grande podría dividirse en varios flujos. Debes obtener todos los flujos para recibir todas las filas.
La respuesta inicia una sesión de lectura a partir de una instantánea coherente de las versiones de tabla necesarias para la solicitud. Cada flujo de esta respuesta utiliza la misma instantánea.
2. Descargar todos los flujos de resultados
Utiliza cada identificador de flujo de la respuesta para recuperar su parte correspondiente del resultado de la lectura de la tabla.
Una sesión de lectura expira tras 60 minutos. Recupera todas las transmisiones antes de que termine la sesión. Si te detienes tras recuperar solo algunos streams, no recibirás el resultado completo.
Para cada identificador de flujo en la respuesta de asignación, envía una solicitud autenticada
GET.GET <TableReadBaseUrl>/v1.0/workspaces/<WorkspaceID>/items/<ItemID>/schemas/<SchemaName>/tables/<TableName>/readStream/<StreamID> Authorization: Bearer <BearerToken>Abre el cuerpo de respuesta con un lector de flujo IPC Apache Arrow.
Procesa los lotes de registros a medida que llegan. Transmitir los lotes evita cargar el resultado completo en memoria.
Repite la solicitud para cada identificador de flujo y combina los resultados según el modelo de procesamiento de tu aplicación.
Cada /readStream respuesta es un flujo independiente de IPC de Apache Arrow. Utiliza la biblioteca Apache Arrow correspondiente al lenguaje de tu aplicación para leer los lotes de registros de cada respuesta. Para más información sobre el formato de flujo, véase Serialización y comunicación entre procesos (IPC).
El cuerpo de respuesta contiene datos brutos del flujo IPC de Apache Arrow, incluyendo la información del esquema necesaria para interpretar los lotes de registros. No te bases en el orden de filas, ni asumas que la posición de un flujo en la respuesta determina su posición en el resultado completo.
Entiende la seguridad de OneLake para la API de lectura de tablas
La API hace cumplir la seguridad de OneLake utilizando la identidad que representa tu token portador:
- Si no tienes permiso para ver la tabla, el servicio devuelve una respuesta no encontrada.
- Si la seguridad a nivel de fila (RLS) filtra todas las filas que puedes ver, la solicitud tiene éxito pero devuelve una respuesta Arrow vacía.
- Si usas una proyección de columna comodín, la respuesta incluye solo las columnas que la seguridad a nivel de columna (CLS) te permite ver.
- Si solicitas explícitamente una columna que no puedes ver, el servicio devuelve una respuesta no encontrada.
Como las tablas y columnas no autorizadas devolven respuestas no encontradas, no uses una respuesta no encontrada para determinar si existe un recurso.
Consideraciones y limitaciones
- La API de lectura de tablas no soporta atajos entre regiones.
- Te cobran por la
POST /readoperación. La recuperación de datos mediante/readStreamno emite un evento de facturación independiente por lectura de tabla. Para más información, consulta Consumo de APIs de lectura de tablas.