OneLake 테이블 읽기 API를 사용해 Delta Lake 또는 Apache Iceberg 테이블에서 행을 읽으세요.
테이블 데이터를 읽으려면, 읽기 세션을 시작하기 위해 한 번의 요청을 보냅니다. API는 반환해야 할 데이터 크기에 따라 하나 이상의 독립적인 결과 스트림을 반환합니다. 애플리케이션은 이 스트림들을 병렬로 다운로드할 수 있어, 대량의 테이블 데이터를 더 빠르게 읽을 수 있습니다. 스트림을 다운로드한 후, Apache Arrow 레코드 배치를 처리하여 완전한 결과를 조립하세요.
API는 테이블을 일관된 시점에서 읽기 때문에, 읽기 중에 테이블이 변경되더라도 모든 결과 스트림에는 동일한 스냅샷의 데이터가 포함됩니다. 또한 인증된 발신자에 대해 OneLake 권한, 행 수준 보안(RLS), 열 수준 보안(CLS)을 강제합니다. 즉, 애플리케이션은 호출자가 접근할 권한이 있는 행과 열만 받으며, 자체 코드로 이러한 보안 제어를 재현할 필요가 없습니다.
중요하다
OneLake 테이블 리드 API는 현재 공개 미리보기 단계입니다. 기능 및 동작은 일반 공급 전에 변경될 수 있습니다.
사전 요구 사항
- 공유 테이블 API 전제 조건과 인증 단계를 완료하세요.
- 전체 응답을 버퍼링하지 않고 Apache Arrow IPC 스트림을 처리할 수 있는 HTTP 클라이언트입니다.
1. 테이블 행 요청 보내기
테이블의 /read 경로에 읽기 세션을 시작하기 위한 요청을 보냅니다POST.
요청 URL은 읽고자 하는 작업 공간, 항목, 스키마, 테이블의 식별자로 자리 표시자를 대체하여 구축하세요.
POST <TableReadBaseUrl>/v1.0/workspaces/<WorkspaceID>/items/<ItemID>/schemas/<SchemaName>/tables/<TableName>/read Authorization: Bearer <BearerToken>신청서에 필요한 읽기 옵션을 요청서에 포함하세요. 어떤 열을 반환할지 지정하는 옵션을 사용
columns하세요.성공적인 응답에서 발생하는 모든 불투명 스트림 식별자를 저장하세요. 큰 결과가 여러 스트림에 나뉜 수도 있습니다. 모든 행을 수신하려면 모든 스트림을 가져와야 합니다.
응답은 요청에 필요한 테이블 버전의 일관된 스냅샷을 통해 읽기 세션을 시작합니다. 이 응답에서 나오는 모든 스트림은 동일한 스냅샷을 사용합니다.
2. 모든 결과 스트림을 다운로드
응답에서 각 스트림 식별자를 사용하여 해당 테이블 읽기 결과의 부분을 불러옵니다.
읽기 세션은 60분 후에 종료됩니다. 세션이 종료되기 전에 모든 스트림을 복구하세요. 일부 스트림만 검색한 후 중단하면 완전한 결과를 받지 못합니다.
할당 응답의 각 스트림 식별자마다 인증된
GET요청을 보냅니다.GET <TableReadBaseUrl>/v1.0/workspaces/<WorkspaceID>/items/<ItemID>/schemas/<SchemaName>/tables/<TableName>/readStream/<StreamID> Authorization: Bearer <BearerToken>Apache Arrow IPC 스트림 리더로 응답 본문을 열어보세요.
레코드 배치를 도착하는 대로 처리하십시오. 배치를 스트리밍하면 전체 결과를 메모리에 로드하는 것을 피할 수 있습니다.
모든 스트림 식별자에 대해 요청을 반복하고, 애플리케이션의 처리 모델에 따라 결과를 결합하세요.
각 /readStream 응답은 독립적인 Apache Arrow IPC 스트림입니다. 애플리케이션 언어의 Apache Arrow 라이브러리를 사용해 각 응답에서 레코드 배치를 읽으세요. 스트림 형식에 대한 자세한 내용은 직렬화 및 프로세스 간 통신(IPC)을 참조하세요.
응답 본문에는 레코드 배치를 해석하는 데 필요한 스키마 정보를 포함한 원시 Apache Arrow IPC 스트림 데이터가 포함되어 있습니다. 행 순서에 의존하지 말고, 응답에서 스트림의 위치가 전체 결과에서 그 위치를 결정한다고 가정하지 마세요.
테이블 읽기 API에 대한 OneLake 보안 이해하기
API는 귀하의 베어러 토큰이 나타내는 신원을 사용하여 OneLake 보안을 강제합니다:
- 테이블을 볼 권한이 없으면 서비스는 '찾을 수 없음' 응답을 반환합니다.
- 행 수준 보안(RLS)이 볼 수 있는 모든 행을 걸러내면, 요청은 성공하지만 빈 Arrow 응답을 반환합니다.
- 와일드카드 컬럼 투영을 사용할 경우, 응답에는 컬럼 레벨 보안(CLS)이 볼 수 있는 컬럼만 포함됩니다.
- 볼 수 없는 열을 명시적으로 요청하면, 서비스는 '찾을 수 없음' 응답을 반환합니다.
권한이 없는 테이블과 컬럼은 찾을 수 없는 응답을 반환하므로, 리소스의 존재 여부를 판단하기 위해 찾을 수 없는 응답을 사용하지 마세요.
고려사항 및 제한사항
- 테이블 리드 API는 지역 간 단축키를 지원하지 않습니다.
-
POST /read작업에 대한 요금이 청구됩니다./readStream를 사용하여 데이터를 검색해도 별도의 테이블 읽기 청구 이벤트는 발생하지 않습니다. 자세한 내용은 테이블 리드 API 소비를 참조하세요.