Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

BigQuery Storage API 오류 문제 해결

이 문서에서는 BigQuery Storage Read API, BigQuery Storage Write API (gRPC) 또는 BigQuery Storage Write API (REST) (tabledata.insertAll 메서드)를 사용하여 BigQuery에서 데이터를 읽거나 스트리밍할 때 발생하는 문제를 해결하는 방법을 설명합니다.

INFORMATION_SCHEMA 뷰로 스트리밍 원격 분석 분석

INFORMATION_SCHEMA 뷰를 쿼리하여 스트리밍 수집 상태를 모니터링하고, 처리량 병목 현상을 식별하고, 1분 간격으로 오류 코드를 검사할 수 있습니다.

Storage Write API (gRPC): INFORMATION_SCHEMA.WRITE_API_TIMELINE 뷰를 쿼리하여 gRPC 스트리밍 수집 요청, 추가된 총 바이트 및 행, error_code별 오류 수를 검사합니다.
Storage Write API (REST): INFORMATION_SCHEMA.STREAMING_TIMELINE 뷰를 쿼리하여 기존 REST tabledata.insertAll 스트리밍 요청과 할당량 또는 비율 제한 오류를 검사합니다.

다음 예에서는 INFORMATION_SCHEMA.WRITE_API_TIMELINE_BY_PROJECT를 쿼리하여 지난 24시간 동안 Storage Write API (gRPC)의 오류 수와 수집된 바이트를 가져옵니다.

SELECT
  start_timestamp,
  error_code,
  SUM(total_requests) AS request_count,
  SUM(total_input_bytes) AS input_bytes
FROM
  `region-REGION`.INFORMATION_SCHEMA.WRITE_API_TIMELINE_BY_PROJECT
WHERE
  start_timestamp > TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 1 DAY)
  AND error_code IS NOT NULL
GROUP BY
  start_timestamp,
  error_code
ORDER BY
  start_timestamp DESC;

REGION을 데이터 세트 리전 이름(예: us 또는 europe-west1)으로 바꿉니다.

Storage Read API 오류 문제 해결

다음은 Storage Read API를 사용할 때 발생하는 일반적인 오류입니다.

오류: Stream removed: 해결 방법: Storage Read API 요청을 다시 시도합니다. 일시적인 오류일 가능성이 높으며 요청을 다시 시도하면 해결될 수 있습니다. 문제가 계속되면 Cloud Customer Care에 문의하세요.
오류: Stream expired: 원인: 이 오류는 Storage Read API 세션이 6시간 제한 시간에 도달할 때 발생합니다.; 해결 방법:

작업의 병렬 처리를 늘립니다.
작업자 노드의 CPU 사용률이 비교적 일관되고 85%를 초과하지 않는 경우 더 큰 머신 유형에서 작업을 실행하는 것이 좋습니다.
작업을 여러 작업 또는 더 작은 쿼리로 분할합니다.

세션 관리 및 데이터 읽기에 관한 자세한 내용은 Storage Read API 개요를 참고하세요.

스트리밍 삽입 문제 해결

다음 섹션에서는 Storage Write API (REST)를 사용하여 BigQuery로 데이터를 스트리밍할 때 발생하는 오류를 해결하는 방법을 설명합니다. 스트리밍 삽입의 할당량 오류를 해결하는 방법에 대한 자세한 내용은 스트리밍 삽입 할당량 오류를 참고하세요.

실패 HTTP 응답 코드

네트워크 오류와 같은 실패 HTTP 응답 코드를 받는 경우 스트리밍 삽입이 성공적으로 수행되었는지 여부를 확인할 방법이 없습니다. 요청을 다시 전송하려고 시도하는 경우 테이블에 중복된 행이 발생할 수 있습니다. 테이블에서 중복이 발생하지 않도록 하려면 요청을 보낼 때 insertId 속성을 설정합니다. BigQuery는 중복 삭제에 insertId 속성을 사용합니다.

권한 오류, 잘못된 테이블 이름 오류 또는 할당량 초과 오류를 받는 경우 행이 삽입되지 않으며 전체 요청이 실패합니다.

성공 HTTP 응답 코드

성공 HTTP 응답 코드를 받더라도 응답의 insertErrors 속성을 확인하여 행 삽입이 성공적으로 수행되었는지 여부를 판단해야 합니다. BigQuery에서 부분적으로만 행 삽입에 성공하는 경우도 있기 때문입니다. 다음 시나리오 중 하나가 발생할 수 있습니다.

모든 행이 삽입됨: insertErrors 속성이 빈 목록인 경우 모든 행이 삽입된 것입니다.
일부 행이 삽입되었습니다: 행에 스키마 불일치가 있는 경우를 제외하고 insertErrors 속성에 표시된 행은 삽입되지 않았고 다른 모든 행은 성공적으로 삽입되었습니다. errors 속성에는 성공하지 못한 행의 실패 이유에 대한 자세한 정보가 포함되어 있습니다. index 속성은 오류가 적용되는 요청의 0 기반 행 색인을 나타냅니다.
성공적으로 삽입된 행이 없음: BigQuery에서 요청의 개별 행에 스키마 불일치가 발생하는 경우 아무런 행이 삽입되지 않으며 행에 스키마 불일치가 없더라도 각 행에 insertErrors 항목이 반환됩니다. 스키마 불일치가 없는 행의 경우 reason 속성이 stopped로 설정된 오류가 있으며 현재 상태 그대로 다시 보낼 수 있습니다. 실패한 행에는 스키마 불일치에 대한 자세한 정보가 포함됩니다. 각 BigQuery 데이터 유형에 지원되는 프로토콜 버퍼 유형에 대해 알아보려면 지원되는 프로토콜 버퍼 및 Arrow 데이터 유형을 참고하세요.

스트리밍 삽입의 메타데이터 오류

BigQuery 스트리밍 API는 높은 삽입 비율에 맞게 설계되었으므로 스트리밍 시스템과 상호작용 시 기본 테이블 메타데이터의 수정은 eventual consistency를 갖게 됩니다. 대부분의 경우 메타데이터 변경사항은 몇 분 내에 전파되지만 이 기간 동안 API 응답에 테이블의 일관되지 않은 상태가 반영될 수 있습니다.

몇 가지 시나리오는 다음과 같습니다.

스키마 변경: 최근에 스트리밍 삽입을 수신한 테이블의 스키마를 수정하면 스트리밍 시스템에서 스키마 변경을 즉시 감지하지 못할 수 있으므로 스키마 불일치 오류가 포함된 응답이 발생할 수 있습니다.
표 생성 또는 삭제: 존재하지 않는 표로 스트리밍하면 notFound 응답 변형이 반환됩니다. 대답으로 생성된 테이블은 후속 스트리밍 삽입에서 즉시 인식되지 않을 수 있습니다. 마찬가지로 테이블을 삭제하거나 다시 만들면 스트리밍 삽입이 이전 테이블로 전송되는 기간이 발생할 수 있습니다. 스트리밍 삽입이 새 테이블에 없을 수도 있습니다.
테이블 자르기: WRITE_TRUNCATE의 writeDisposition 값을 사용하는 쿼리 작업을 사용하여 테이블의 데이터를 자르면 일관성 기간 동안 후속 삽입이 삭제될 수 있습니다.

데이터가 누락되었거나 사용할 수 없음

스트리밍 삽입은 일시적으로 쓰기 최적화 스토리지에 위치하는데, 스트리밍 버퍼의 가용성 특성은 관리 스토리지와는 다릅니다. 테이블 복사 작업 및 tabledata.list와 같은 API 메서드 등 BigQuery의 특정 작업은 쓰기 최적화 스토리지와 상호작용하지 않습니다. 최근 스트리밍 데이터가 대상 테이블 또는 출력에 존재하지 않습니다.

스트리밍 삽입 할당량 오류

이 섹션에서는 BigQuery로 데이터를 스트리밍하는 것과 관련된 할당량 오류를 해결하는 팁을 제공합니다.

특정 리전에서 각 행의 insertId 필드를 채우지 않으면 스트리밍 삽입의 할당량이 증가합니다. 스트리밍 삽입의 할당량에 대한 자세한 내용은 스트리밍 삽입을 참조하세요. BigQuery 스트리밍의 할당량 관련 오류는 insertId 존재 여부에 따라 다릅니다.

오류 메시지

insertId 필드가 비어 있으면 다음과 같은 할당량 오류가 발생할 수 있습니다.

할당량 한도	오류 메시지
프로젝트별 초당 바이트 수	`REGION` 리전의 `PROJECT_ID` 프로젝트에서 gaia_id가 `GAIA_ID`인 항목이 초당 삽입 바이트 수 할당량을 초과했습니다.

insertId 필드가 채워져 있으면 다음과 같은 할당량 오류가 발생할 수 있습니다.

할당량 한도	오류 메시지
프로젝트별 초당 행 수	`REGION`의 `PROJECT_ID` 프로젝트가 초당 스트리밍 삽입 행 수 할당량을 초과했습니다.
테이블별 초당 행 수	`TABLE_ID` 테이블이 초당 스트리밍 삽입 행 수 할당량을 초과했습니다.
테이블별 초당 바이트 수	`TABLE_ID` 테이블이 초당 스트리밍 삽입 바이트 수 할당량을 초과했습니다.

insertId 필드의 목적은 삽입된 행의 중복을 삭제하는 것입니다. 동일한 insertId의 삽입이 몇 분 안에 여러 번 도착하면 BigQuery는 레코드의 단일 버전을 작성합니다. 하지만 이러한 자동 중복 삭제는 보장되지 않습니다. 스트리밍 처리량을 극대화하기 위해 insertId를 포함하지 말고 수동 중복 삭제를 대신 사용하는 것이 좋습니다. 자세한 내용은 데이터 일관성 확인을 참조하세요.

이 오류가 발생하면 문제를 진단한 후 권장 단계에 따라 문제를 해결하세요.

진단

스트리밍 트래픽을 분석하려면 STREAMING_TIMELINE_BY_* 뷰를 사용합니다. 이러한 뷰는 error_code별로 그룹화된 1분 간격의 스트리밍 통계를 집계합니다. 할당량 오류는 error_code이 RATE_LIMIT_EXCEEDED 또는 QUOTA_EXCEEDED와 같은 결과에 표시됩니다.

도달한 특정 할당량 한도에 따라 total_rows 또는 total_input_bytes를 확인하세요. 오류가 테이블 수준 할당량인 경우 table_id로 필터링합니다.

예를 들어 다음 쿼리는 분당 수집된 총 바이트 수와 총 할당량 오류 수를 표시합니다.

SELECT
 start_timestamp,
 error_code,
 SUM(total_input_bytes) as sum_input_bytes,
 SUM(IF(error_code IN ('QUOTA_EXCEEDED', 'RATE_LIMIT_EXCEEDED'),
     total_requests, 0)) AS quota_error
FROM
 `region-REGION_NAME`.INFORMATION_SCHEMA.STREAMING_TIMELINE_BY_PROJECT
WHERE
  start_timestamp > TIMESTAMP_SUB(CURRENT_TIMESTAMP, INTERVAL 1 DAY)
GROUP BY
 start_timestamp,
 error_code
ORDER BY 1 DESC

해결 방법

이 할당량 오류를 해결하려면 다음 안내를 따르세요.

중복 삭제에 insertId 필드를 사용 중이고 프로젝트가 더 높은 스트리밍 할당량을 지원하는 리전에 있는 경우 insertId 필드를 삭제하는 것이 좋습니다. 이 솔루션에서는 데이터를 수동으로 중복 삭제하기 위한 추가 단계가 필요할 수 있습니다. 자세한 내용은 수동으로 중복 삭제를 참조하세요.
insertId를 사용하지 않거나 삭제할 수 없는 경우 24시간 동안 스트리밍 트래픽을 모니터링하고 할당량 오류를 분석합니다.
- 대부분 QUOTA_EXCEEDED 오류 대신 RATE_LIMIT_EXCEEDED 오류가 발생하고 전체 트래픽이 할당량의 80% 미만이면 이 오류는 일시적인 급증을 나타낼 수 있습니다. 작업 재시도 사이에 지수 백오프를 사용하는 작업 재시도로 이러한 오류를 처리할 수 있습니다.
- Dataflow 작업을 사용하여 데이터를 삽입하는 경우 스트리밍 삽입 대신 로드 작업을 사용하는 것이 좋습니다. 자세한 내용은 삽입 방식 설정을 참조하세요. 커스텀 I/O 커넥터와 함께 Dataflow를 사용하는 경우 기본 제공 I/O 커넥터를 사용하는 것이 좋습니다. 자세한 내용은 커스텀 I/O 패턴을 참조하세요.
- QUOTA_EXCEEDED 오류가 표시되거나 전체 트래픽이 지속적으로 할당량의 80%를 초과하는 경우 할당량 상향 요청을 제출하세요. 자세한 내용은 할당량 조정 요청을 참고하세요.
- 또한 스트리밍 삽입을 처리량이 높고 가격이 저렴하며 유용한 기능이 많은 최신 Storage Write API로 대체를 고려할 수도 있습니다.