Skip to main content
BigQuery 엔진을 사용하면 공개 데이터셋을 포함한 Google BigQuery의 테이블을 읽고 쓸 수 있습니다. 읽기에는 BigQuery REST API(tabledata.list)를 사용하므로 네이티브 테이블만 읽을 수 있습니다(뷰, materialized view, 외부 테이블은 읽을 수 없음). 쓰기에는 스트리밍 삽입(tabledata.insertAll)을 사용하며, 프로젝트에서 청구를 활성화해야 합니다. 쓰기 작업은 원자적이지 않습니다. 대규모 INSERT는 배치 단위로 전송되며(요청당 최대 500개 행, BigQuery’s 10MB 요청 크기 제한을 넘지 않도록 추가 분할), 단일 요청도 부분적으로 성공할 수 있습니다(BigQuery는 요청의 일부 행을 커밋하고 나머지는 insertErrors와 함께 거부할 수 있음). 또한 이전 배치가 수락된 후 이후 배치가 거부될 수 있습니다. 두 경우 모두 이미 커밋된 행은 BigQuery에 남고 쿼리는 오류를 보고합니다. 각 행에는 안정적인 insertId(쿼리 ID와 행의 서수 위치에서 파생됨)가 포함되므로 BigQuery는 재시도된 행을 최선의 노력으로 중복 제거합니다. insertId는 서수 위치에 따라 달라지므로, 동일한 INSERT를 다시 실행할 때 행이 동일한 순서로 제공되는 경우에만 중복 제거됩니다(예: max_threads = 1max_insert_threads = 1을 사용하는 단일 스레드 환경). 자세한 내용은 bigquery 테이블 함수의 제한 사항을 참조하십시오.

테이블 생성

컬럼 목록은 선택 사항입니다. 생략하면 BigQuery 테이블 스키마에서 구조를 추론합니다. 지정하는 경우 컬럼은 BigQuery 컬럼의 부분 집합일 수 있으며, 각 컬럼은 BigQuery 스키마에 매핑된 정확한 유형으로 선언해야 합니다(데이터 타입 매핑 참조). 기본값 표현식이 없는 REQUIRED BigQuery 필드를 생략한 테이블 정의는 읽을 수는 있지만 쓸 수는 없습니다. BigQuery 스트리밍 삽입은 이러한 필드가 누락된 행을 거부하므로, 해당 INSERT는 사전에 거부됩니다. 생략된 REQUIRED 필드에 defaultValueExpression이 선언되어 있으면 BigQuery가 기본값을 채우므로 테이블은 계속 쓸 수 있습니다. NULLABLE RECORDNullable(Tuple(...))로 매핑되므로 NULL 레코드를 손실 없이 왕복할 수 있습니다. 이러한 테이블을 생성하려면(구조를 추론하든 명시적으로 선언하든) 모든 Nullable(Tuple) 컬럼과 마찬가지로 enable_nullable_tuple_type 설정이 필요합니다. 컬럼을 명시적으로 선언할 때는 이 설정을 피하기 위해 RECORD 필드를 일반 Tuple(...)로 선언할 수도 있지만, 이 경우 전체 레코드의 NULL은 기본 튜플로 강제 변환됩니다. 추론된 유형과 비교해 허용되는 유일한 차이는 RECORDTuple을 감싸는 Nullable을 제거하는 것이며, 동일한 레코드에서만 가능합니다. 널 허용 여부를 다른(내부 또는 외부) 레코드로 옮길 수는 없습니다. 엔진 매개변수
  • project — 데이터셋을 소유한 Google Cloud 프로젝트입니다.
  • dataset — 데이터셋 이름입니다.
  • table — 테이블 이름입니다.
  • access_token — OAuth 2.0 액세스 토큰(선택적 위치 인수)입니다.
매개변수는 key = value 재정의를 사용하는 명명된 컬렉션으로도 전달할 수 있습니다. 전체 키 목록과 인증 메서드에 관한 설명은 bigquery 테이블 함수를 참조하십시오. 정확히 하나의 인증 메서드를 제공해야 합니다. 액세스 토큰은 1시간 이내에 만료되므로 영구 테이블에는 access_token보다 service_account_key 또는 refresh_token을 사용하는 것이 좋습니다.

사용 예시

마지막 수정일 2026년 8월 14일