오류 메시지

BigQuery를 사용한 작업에서 직면하는 오류에는 HTTP 오류 코드 또는 작업 오류, 두 가지 유형이 있습니다. 작업 오류는 jobs.get 호출 시 status 객체에 나타납니다.

오류 표

다음 표에서는 BigQuery가 반환할 수 있는 오류 코드를 보여줍니다. BigQuery API의 응답에는 HTTP 오류 코드 및 응답 본문의 오류 객체가 포함됩니다. 아래 '오류 코드' 열은 오류 객체의 reason 속성에 매핑됩니다. 이 표에는 모든 가능한 HTTP 오류 또는 다른 네트워킹 오류가 포함되지 않습니다. 따라서 errors 객체가 BigQuery의 모든 오류 응답에 포함된다고 추정해서는 안 됩니다.

또한 BigQuery API에 Cloud 클라이언트 라이브러리를 사용하는 경우 다른 오류 또는 오류 객체가 수신될 수 있습니다. 자세한 내용은 BigQuery API 클라이언트 라이브러리를 참조하세요.

아래 목록에 없는 HTTP 응답 코드를 받는 경우, 해당 응답 코드는 문제 또는 HTTP 요청의 예상 결과를 나타냅니다. 5xx 범위의 응답 코드는 서버 측 오류를 나타냅니다. 5xx 응답 코드를 수신하면 나중에 요청을 다시 시도하세요. 경우에 따라 프록시와 같은 중간 서버에서 5xx 응답 코드를 반환할 수 있습니다. 오류에 대한 자세한 내용은 응답 본문과 응답 헤더를 검토하세요. 전체 HTTP 응답 코드 목록은 HTTP 응답 코드를 참조하세요.

bq 명령줄 도구를 사용하여 작업 상태를 확인하는 경우, 오류 객체가 기본적으로 반환되지 않습니다. 객체 및 다음 표에 매핑되는 해당 reason 속성을 보려면 -- format=prettyjson 플래그를 사용합니다. 예를 들면 다음과 같습니다. bq --format=prettyjson show -j <job id>

오류 코드 HTTP 코드 설명 문제해결
accessDenied 403 이 오류는 액세스할 권한이 없는 데이터세트, 테이블, , 작업과 같은 리소스에 액세스하려고 하면 반환됩니다. 읽기 전용 객체를 수정하려 하는 경우에도 이 오류가 반환됩니다. 리소스 소유자에게 연락하여 리소스에 대한 액세스를 요청합니다.
backendError 500 또는 503 이 오류는 네트워크 연결 문제 또는 서버 과부하와 같은 일시적인 서버 장애 발생 시 반환됩니다. 일반적으로 몇 초 정도 기다린 후 다시 시도합니다. 그러나 이 오류의 문제해결을 위한 두 가지 특수한 사례(jobs.get 호출과 jobs.insert 호출)가 있습니다.

jobs.get 호출

  • jobs.get 폴링 시 503 오류가 발생하면 몇 초 정도 기다린 후 다시 폴링합니다.
  • 작업이 완료되더라도 backendError가 있는 오류 객체가 포함되면 작업은 실패합니다. 데이터 일관성에 대해 걱정할 필요 없이 안전하게 작업을 재시도할 수 있습니다.

jobs.insert 호출

jobs.insert 호출 시 이 오류가 발생하면 작업 성공 여부가 분명하지 않습니다. 이 경우 작업을 재시도해야 합니다.

billingNotEnabled 403 프로젝트에서 청구가 사용 설정되지 않은 경우 이 오류가 반환됩니다. Google Cloud Console에서 프로젝트의 결제를 설정합니다.
blocked 403 이 오류는 일반적으로 서비스 중단을 방지하기 위해 BigQuery에서 사용자가 시도하는 작업을 일시적으로 차단 목록에 포함하는 경우에 반환됩니다. 이 오류는 거의 발생하지 않습니다. 자세한 내용은 지원팀에 문의하세요.
duplicate 409 이 오류는 이미 존재하는 작업, 데이터세트, 테이블을 만들려고 시도할 때 반환됩니다. 또한 작업의 writeDisposition 속성이 WRITE_EMPTY로 설정되어 있고 작업이 액세스하는 대상 테이블이 이미 존재하는 경우에도 이 오류가 반환됩니다. 만들려는 리소스의 이름을 바꾸거나 작업의 writeDisposition 값을 변경합니다.
internalError 500 이 오류는 BigQuery 내에서 내부 오류가 발생하면 반환됩니다. 작업을 다시 시도해도 문제가 지속되는 경우 지원팀에 문의하거나 BigQuery Issue Tracker를 사용하여 버그를 보고합니다.
invalid 400 이 오류는 잘못된 쿼리 외에 필수 입력란 누락 또는 잘못된 테이블 스키마와 같은 잘못된 입력이 있는 경우에 반환됩니다. 잘못된 쿼리는 대신 invalidQuery 오류를 반환합니다.
invalidQuery 400 이 오류는 잘못된 쿼리를 시도하는 경우 반환됩니다. 쿼리에서 구문 오류를 다시 확인합니다. 쿼리 참조에는 유효한 쿼리를 작성하는 방법에 대한 설명과 예가 포함되어 있습니다.
invalidUser 400 이 오류는 잘못된 사용자 인증 정보를 사용하여 쿼리를 예약하려고 시도할 때 반환됩니다. 쿼리 예약에 설명된 대로 사용자 인증 정보를 새로고침합니다.
notFound 404 이 오류는 존재하지 않는 리소스(데이터세트, 테이블 또는 작업)를 참조하는 경우에 반환됩니다. 스냅샷 데코레이터를 사용하여 최근에 스트리밍되었지만 삭제된 테이블을 참조하는 경우에도 이 오류가 발생할 수 있습니다. 리소스 이름을 수정하거나, 삭제된 테이블을 쿼리하기 전에 스트리밍 후 최소 6시간 동안 기다립니다.
notImplemented 501 이 작업 오류는 구현되지 않은 기능에 액세스하려고 시도하는 경우 반환됩니다. 자세한 내용은 지원팀에 문의하세요.
quotaExceeded 403 이 오류는 프로젝트가 BigQuery 할당량, 커스텀 할당량을 초과하는 경우 또는 청구를 설정하지 않고 무료 쿼리 등급을 초과하는 경우에 반환됩니다. 초과된 할당량에 대한 자세한 내용은 오류 객체의 message 속성을 참조하세요. BigQuery 할당량을 재설정하거나 늘리려면 지원팀에 문의합니다. 커스텀 할당량을 수정하려면 Google Cloud Console 페이지에서 요청을 제출하세요. BigQuery 샌드박스를 사용하다가 이 오류가 발생하면 업그레이드하면 됩니다.

자세한 내용은 BigQuery 할당량 오류 문제 해결을 참조하세요.

rateLimitExceeded 403 이 오류는 프로젝트가 과다한 요청을 지나치게 빠른 속도로 전송함으로써 단기 비율 제한을 초과하는 경우 반환됩니다. 예를 들어 쿼리 작업의 비율 제한API 요청의 비율 제한을 참조하세요. 요청 속도를 낮추세요.

프로젝트에 해당 제한을 초과한 항목이 없다고 판단되면 지원팀에 문의하세요.

자세한 내용은 BigQuery 할당량 오류 문제 해결을 참조하세요.

resourceInUse 400 이 오류는 테이블이 포함된 데이터세트를 삭제하려 하거나 현재 실행 중인 작업을 삭제하려 하는 경우에 반환됩니다. 데이터세트를 삭제하기 전에 비우거나 작업이 완료될 때까지 기다린 후에 데이터세트를 삭제합니다.
resourcesExceeded 400 이 오류는 쿼리에서 과다한 리소스를 사용하는 경우 반환됩니다.
  • 쿼리를 더 작은 조각으로 나눕니다.
  • ORDER BY 절을 삭제해 봅니다.
  • 쿼리에서 JOIN을 사용하는 경우, 더 큰 테이블이 절의 왼쪽에 위치하도록 합니다.
  • 쿼리에서 FLATTEN을 사용하는 경우, 사용 사례에서 필요한지 여부를 확인합니다. 자세한 내용은 중첩 및 반복 데이터를 참조하세요.
  • 쿼리에서 EXACT_COUNT_DISTINCT를 사용하는 경우, COUNT(DISTINCT)를 대신 사용하는 방안을 고려합니다.
  • 쿼리에서 <n> 값이 큰 COUNT(DISTINCT <value>, <n>)를 사용하는 경우 GROUP BY를 대신 사용하는 방안을 고려합니다. 자세한 내용은 COUNT(DISTINCT)를 참조하세요.
  • 쿼리에서 UNIQUE를 사용하는 경우, 대신 GROUP BY를 사용하거나 하위 선택에서 윈도우 함수를 사용하는 방안을 고려합니다.
responseTooLarge 403 이 오류는 쿼리 결과가 최대 응답 크기보다 큰 경우에 반환됩니다. 일부 쿼리는 여러 단계로 실행되며, 어느 단계에서 지나치게 큰 응답 크기를 반환하면 최종 결과가 최댓값보다 작더라도 이 오류가 반환됩니다. 이 오류는 쿼리에서 ORDER BY 절을 사용하는 경우에 흔히 반환됩니다. LIMIT 절을 추가하거나 ORDER BY 절을 삭제하면 도움이 될 수 있습니다. 크기가 큰 결과가 반환되도록 하려면 allowLargeResults 속성을 true로 설정하고 대상 테이블을 지정하면 됩니다.
stopped 200 이 상태 코드는 작업이 취소되는 경우 반환됩니다.
tableUnavailable 400 특정 BigQuery 테이블에는 다른 Google 제품팀이 관리하는 데이터가 사용됩니다. 이 오류는 이러한 테이블 중 하나를 사용할 수 없음을 나타냅니다. 이 오류 메시지가 표시되면 요청을 다시 시도하거나(internalError 문제해결 제안 참조) 데이터 액세스 권한을 부여한 Google 제품팀에 문의합니다.

샘플 오류 응답

GET https://bigquery.googleapis.com/bigquery/v2/projects/12345/datasets/foo
Response:
[404]
{
  "error": {
  "errors": [
  {
    "domain": "global",
    "reason": "notFound",
    "message": "Not Found: Dataset myproject:foo"
  }],
  "code": 404,
  "message": "Not Found: Dataset myproject:foo"
  }
}

인증 오류

OAuth 토큰 생성 시스템에서 발생하는 오류는 OAuth2 사양에 정의된 대로 다음 JSON 객체를 반환합니다.

{"error" : "description_string"}

이 오류에는 HTTP 400 Bad Request 오류 또는 HTTP 401 Unauthorized 오류가 동반됩니다. description_string은 OAuth2 사양에서 정의된 오류 코드 중 하나입니다. 예를 들면 다음과 같습니다.

{"error":"invalid_client"}

맨 위로

스트리밍 삽입 문제해결

다음 섹션에서는 BigQuery로 데이터를 스트리밍할 때 발생하는 오류를 해결하는 방법을 설명합니다.

실패 HTTP 응답 코드

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

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

성공 HTTP 응답 코드

BigQuery에서 부분적으로만 행 삽입에 성공하는 경우도 있으므로 성공 HTTP 응답 코드를 받더라도 응답의 insertErrors 속성을 확인하여 행 삽입이 성공적으로 수행되었는지 여부를 판단해야 합니다.

insertErrors 속성이 빈 목록인 경우 모든 행이 성공적으로 삽입된 것입니다. 즉, 행에 스키마 불일치가 있는 경우를 제외하고 insertErrors 속성에 표시된 행은 삽입되지 않았고 다른 모든 행은 성공적으로 삽입되었습니다. errors 속성에는 성공하지 못한 행의 실패 이유에 대한 자세한 정보가 포함되어 있습니다. index 속성은 오류가 적용되는 요청의 0 기반 행 색인을 나타냅니다.

BigQuery에서 요청의 개별 행에 스키마 불일치가 발생하는 경우 아무런 행이 삽입되지 않으며 행에 스키마 불일치가 없더라도 각 행에 insertErrors 항목이 반환됩니다. 스키마 불일치가 없는 행의 경우 reason 속성이 stopped로 설정된 오류가 있으며 현재 상태 그대로 다시 보낼 수 있습니다. 실패한 행에는 스키마 불일치에 대한 자세한 정보가 포함됩니다.

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

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

일부 시나리오에는 다음이 포함됩니다.

  • 스키마 변경사항. 스트리밍 시스템은 스키마 변경을 즉각 적용하지 않을 수 있으므로 최근 스트리밍 삽입을 수신한 테이블의 스키마를 수정하는 경우 스키마 불일치 오류 응답이 발생할 수 있습니다.
  • 테이블 만들기/삭제. 존재하지 않는 테이블로 스트리밍하면 notFound 응답 변형이 반환됩니다. 응답으로 생성된 테이블은 후속 스트리밍 삽입에서 즉시 인식되지 않을 수 있습니다. 마찬가지로 테이블을 삭제하거나 다시 만들어도 스트리밍 삽입이 실제로 이전 테이블로 전달되는 기간이 발생할 수 있습니다. 스트리밍 삽입이 새 테이블에 존재하지 않을 수 있습니다.
  • 테이블 잘림. 마찬가지로 WRITE_TRUNCATE의 writeDisposition을 사용하는 쿼리 작업을 사용해서 테이블 데이터를 자르면 일관성 기간 동안 후속 삽입이 누락될 수 있습니다.

데이터 누락/사용 불가

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

맨 위로