BigQuery API로 페이지로 나누기 사용
이 문서에서는 BigQuery API로 페이지로 나누기를 사용하여 대규모 데이터 세트에서 테이블 데이터와 쿼리 결과를 읽는 방법을 설명합니다.
페이지로 나누기를 사용하면 BigQuery에서 큰 데이터 세트를 페이지라는 작은 청크로 나눕니다. 대부분의 사용자의 경우 Cloud 클라이언트 라이브러리에서 이 프로세스를 자동으로 처리하지만 웹 애플리케이션과 같은 특정 사용 사례의 경우 페이지 나누기를 수동으로 제어할 수도 있습니다.
자동 페이지로 나누기 사용
Cloud 클라이언트 라이브러리는 API 페이지 나누기의 하위 수준 세부정보를 처리하고 반복기와 유사한 환경을 제공합니다. 결과를 반복하면 라이브러리에서 필요한 경우 다음 데이터 페이지를 자동으로 가져옵니다.
다음 샘플은 BigQuery 테이블 데이터를 자동으로 반복하는 방법을 보여줍니다.
C#
이 샘플을 사용해 보기 전에 BigQuery 빠른 시작: 클라이언트 라이브러리 사용의 C# 설정 안내를 따르세요. 자세한 내용은 BigQuery C# API 참고 문서를 확인하세요.
BigQuery에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.
Go
이 샘플을 사용해 보기 전에 BigQuery 빠른 시작: 클라이언트 라이브러리 사용의 Go 설정 안내를 따르세요. 자세한 내용은 BigQuery Go API 참고 문서를 확인하세요.
BigQuery에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.
자바
이 샘플을 사용해 보기 전에 BigQuery 빠른 시작: 클라이언트 라이브러리 사용의 Java 설정 안내를 따르세요. 자세한 내용은 BigQuery Java API 참고 문서를 확인하세요.
BigQuery에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.
Node.js
이 샘플을 사용해 보기 전에 BigQuery 빠른 시작: 클라이언트 라이브러리 사용의 Node.js 설정 안내를 따르세요. 자세한 내용은 BigQuery Node.js API 참고 문서를 확인하세요.
BigQuery에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.
PHP
이 샘플을 사용해 보기 전에 BigQuery 빠른 시작: 클라이언트 라이브러리 사용의 PHP 설정 안내를 따르세요. 자세한 내용은 BigQuery PHP API 참고 문서를 확인하세요.
BigQuery에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.
Python
이 샘플을 사용해 보기 전에 BigQuery 빠른 시작: 클라이언트 라이브러리 사용의 Python 설정 안내를 따르세요. 자세한 내용은 BigQuery Python API 참고 문서를 확인하세요.
BigQuery에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.
Ruby
이 샘플을 사용해 보기 전에 BigQuery 빠른 시작: 클라이언트 라이브러리 사용의 Ruby 설정 안내를 따르세요. 자세한 내용은 BigQuery Ruby API 참고 문서를 확인하세요.
BigQuery에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.
페이지 크기 제어
페이지 크기를 설정하여 각 네트워크 요청에서 반환되는 최대 행 수를 지정할 수 있습니다. 페이지 크기를 설정하면 네트워크 사용량을 최적화하거나 데이터를 메모리에 맞추는 데 유용합니다.
대부분의 클라이언트 라이브러리에서 list_rows 또는 query와 같은 메서드를 호출할 때 max_results 또는 page_size 매개변수를 사용할 수 있습니다.
페이지 토큰을 사용하여 수동 페이지로 나누기 사용
수동 페이지로 나누기는 사용자가 다음을 클릭하여 다음 결과 집합을 보는 웹 서비스와 같은 스테이트리스(Stateless) 애플리케이션에 유용합니다. 이 시나리오에서 서버는 요청 간에 활성 반복자를 유지하지 않습니다.
대신 다음과 같이 페이지 토큰을 사용합니다.
- 페이지를 요청합니다. API를 호출하고 행과 함께
pageToken매개변수를 수신합니다. - 계속해 줘. 다음 요청에서 동일한
pageToken매개변수를 BigQuery에 다시 전달하여 다음 데이터 청크를 가져옵니다.
다음 샘플은 페이지 토큰을 검색하고 이를 사용하여 다음 페이지의 쿼리 결과를 가져오는 방법을 보여줍니다.
API
jobs.config.query.destinationTable 필드를 읽어 쿼리 결과가 쓰인 테이블을 확인합니다.
쿼리 결과를 읽으려면 tabledata.list를 호출합니다.
자바
이 샘플을 사용해 보기 전에 BigQuery 빠른 시작: 클라이언트 라이브러리 사용의 Java 설정 안내를 따르세요. 자세한 내용은 BigQuery Java API 참고 문서를 확인하세요.
BigQuery에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.
각 페이지에서 반환되는 행 수를 설정하려면 GetQueryResults 작업을 사용하고 다음 예시와 같이 전달하는 QueryResultsOption 객체의 pageSize 옵션을 설정합니다.
TableResult result = job.getQueryResults();
QueryResultsOption queryResultsOption = QueryResultsOption.pageSize(20);
TableResult result = job.getQueryResults(queryResultsOption);
Node.js
이 샘플을 사용해 보기 전에 BigQuery 빠른 시작: 클라이언트 라이브러리 사용의 Node.js 설정 안내를 따르세요. 자세한 내용은 BigQuery Node.js API 참고 문서를 확인하세요.
BigQuery에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.
Python
QueryJob.result 메서드는 쿼리 결과의 iterable을 반환합니다. 다른 방법은 다음과 같습니다.
QueryJob.destination속성을 읽습니다. 이 속성이 구성되지 않았으면 API에서 임시 익명 테이블 참조로 설정됩니다.Client.get_table메서드를 사용하여 테이블 스키마를 가져옵니다.Client.list_rows메서드를 사용하여 대상 테이블의 모든 행에 대해 iterable을 만듭니다.
이 샘플을 사용해 보기 전에 BigQuery 빠른 시작: 클라이언트 라이브러리 사용의 Python 설정 안내를 따르세요. 자세한 내용은 BigQuery Python API 참고 문서를 확인하세요.
BigQuery에 인증하려면 애플리케이션 기본 사용자 인증 정보를 설정합니다. 자세한 내용은 클라이언트 라이브러리의 인증 설정을 참조하세요.
ETag로 최적화
페이지를 뒤로 이동하거나 캐시된 pageToken 값을 사용하여 임의의 페이지로 건너뛸 경우, 페이지를 마지막으로 본 이후 데이터가 변경되었을 수 있습니다. 이러한 결과를 방지하려면 etag 속성을 사용하면 됩니다.
모든 collection.list 메서드 (Tabledata 제외)는 결과에 etag 속성을 반환합니다. 이 속성은 마지막 요청 이후 페이지가 변경되었는지 여부를 확인하는 데 사용할 수 있는 페이지 결과의 해시입니다. ETag 값을 사용하여 BigQuery에 요청하면 BigQuery는 ETag 값을 API가 반환한 ETag 값과 비교하고 ETag 값의 일치 여부에 따라 응답합니다. 다음과 같이 ETag를 사용하여 중복 목록 호출을 방지할 수 있습니다.
- 값이 변경된 경우에만 값을 반환하려면 HTTP
If-None-Match헤더를 사용하여 이전에 저장된 ETag로 목록을 호출합니다. ETag가 일치하면 BigQuery는HTTP 304 Not Modified상태 코드와 데이터를 반환하지 않아 대역폭을 절약합니다. - 값이 변경되지 않은 경우에만 값을 반환하려면 HTTP
If-Match헤더를 사용하세요. 페이지가 변경된 경우 BigQuery는412 Precondition Failed를 반환합니다.
참조: API 한도 및 기준
모든 *collection*.list 메서드는 특정한 상황에서 페이지로 나눈 결과를 반환합니다. maxResults 속성은 페이지당 결과 수를 제한합니다.
| 메서드 | 페이지 나누기 기준 | 기본 maxResults 한도 |
최대 maxResults 한도 |
최대 maxFieldValues 한도 |
|---|---|---|---|---|
tabledata.list |
응답 크기가 10MB1를 초과하는 데이터 또는 maxResults 행보다 많은 경우 페이지로 나눈 결과를 반환합니다. |
무제한 | 무제한 | 무제한 |
기타 모든 *collection*.list 메서드 |
응답이 maxResults 행을 초과하는 동시에 최대 한도 미만인 경우 페이지로 나눈 결과를 반환합니다. |
10,000 | 무제한 | 300,000 |
결과가 바이트 또는 필드 한도보다 크면 한도에 맞도록 결과가 잘립니다. 한 행이 바이트 또는 필드 한도보다 크면 tabledata.list 메서드는 쿼리 결과에 대한 최대 행 크기 한도와 일치하는 최대 100MB 데이터1로 반환할 수 있습니다.
페이지당 최소 크기는 없으며, 일부 페이지에서 다른 페이지보다 많은 행을 반환할 수 있습니다.
jobs.getQueryResults REST API 메서드는 지원을 통해 명시적으로 요청하지 않는 한 20MB의 데이터를 반환할 수 있습니다.
1행 크기는 행 데이터의 내부 표현을 기준으로 하므로 근사치입니다. 최대 행 크기 한도는 쿼리 작업 실행의 특정 단계에서 적용됩니다.