BigQuery 테이블 엔진

Google BigQuery의 테이블(공개 데이터셋 포함)에서 읽고 쓸 수 있게 해주는 테이블 엔진이에요. 읽기는 BigQuery REST API(tabledata.list)를 사용하고, 쓰기는 스트리밍 삽입(tabledata.insertAll)을 사용해요.

출처: 문서

본문

BigQuery 엔진은 Google BigQuery의 테이블(공개 데이터셋 포함)에서 읽고 쓸 수 있게 해줘요. 읽기는 BigQuery REST API(tabledata.list)를 사용하므로 네이티브 테이블만 읽을 수 있어요(뷰, materialized view, 외부 테이블은 불가). 쓰기는 스트리밍 삽입(tabledata.insertAll)을 사용하며, 이는 프로젝트의 빌링이 활성화되어 있어야 해요.

쓰기는 원자적이지 않아요. 큰 INSERT는 배치로 보내지고(요청당 최대 500행, BigQuery의 10 MB 요청 크기 제한 아래로 유지), 단일 요청 자체가 부분적으로 성공할 수 있어요(BigQuery가 한 요청의 일부 행은 커밋하고 다른 행은 insertErrors로 거부할 수 있음), 그리고 나중 배치가 이전 배치가 받아들여진 후 거부될 수 있어요. 두 경우 모두 이미 커밋된 행은 BigQuery에 남고 쿼리는 오류를 보고해요. 각 행은 안정적인 insertId(쿼리 id와 행의 서수 위치에서 파생)를 담아 BigQuery가 재시도된 행을 best-effort로 중복 제거하게 해요. insertId가 서수 위치에 의존하므로 같은 INSERT를 다시 실행해도 행이 같은 순서로 제시될 때만(예: 단일 스레드, max_threads = 1과 max_insert_threads = 1로) 중복 제거돼요. 자세한 내용은 bigquery 테이블 함수 제한을 참고해요.

테이블 만들기 (Creating a table)

CREATE TABLE [IF NOT EXISTS] [db.]table_name
[(
    name1 [type1],
    name2 [type2],
    ...
)]
ENGINE = BigQuery(project, dataset, table[, access_token][, key = value, ...])

컬럼 목록은 선택 사항이에요. 생략하면 구조가 BigQuery 테이블 스키마에서 추론돼요. 지정하면 컬럼은 BigQuery 컬럼의 부분집합일 수 있고, 각 컬럼은 BigQuery 스키마가 매핑하는 정확한 타입으로 선언되어야 해요(데이터 타입 매핑 참고). 기본값 표현식이 없는 REQUIRED BigQuery 필드를 생략한 테이블 정의는 읽을 수 있지만 쓸 수 없어요. BigQuery 스트리밍 삽입은 그런 필드를 생략한 행을 거부하므로, 그런 INSERT는 사전에 거부돼요. 생략된 REQUIRED 필드가 defaultValueExpression을 선언하면 BigQuery가 기본값을 채우고 테이블은 쓰기 가능하게 유지돼요. NULLABLE RECORD는 Nullable(Tuple(...))로 매핑되므로 NULL 레코드가 무손실로 왕복돼요. 컬럼을 명시적으로 선언할 때 RECORD 필드는 대신 일반 Tuple(...)로 선언할 수 있는데, 이는 전체 레코드 NULL을 기본 튜플로 강제 변환하는 대가를 치러요. 추론된 타입과의 유일하게 허용되는 차이는 RECORD의 Tuple을 감싸는 Nullable을 제거하는 것이고, 그것도 같은 레코드에서만 가능해요. nullability는 다른(안쪽 또는 바깥쪽) 레코드로 옮길 수 없어요.

엔진 매개변수 (Engine parameters)

project — 데이터셋을 소유한 Google Cloud 프로젝트.
dataset — 데이터셋 이름.
table — 테이블 이름.
access_token — OAuth 2.0 액세스 토큰(선택적 위치 인자).

매개변수는 key = value 오버라이드와 함께 명명된 컬렉션(named collection)으로도 전달할 수 있어요. 전체 키 목록과 인증 방법의 설명은 bigquery 테이블 함수를 참고해요. 정확히 하나의 인증 방법을 제공해야 해요. 영구 테이블의 경우 access token은 한 시간 내에 만료되므로 service_account_key나 refresh_token이 access_token보다 선호돼요.

사용 예시 (Usage example)

CREATE TABLE shakespeare
ENGINE = BigQuery('bigquery-public-data', 'samples', 'shakespeare',
                  service_account_key = '{"type": "service_account", ...}');

SELECT word, word_count FROM shakespeare ORDER BY word_count DESC LIMIT 3;

CREATE TABLE events (id Int64, payload Nullable(String))
ENGINE = BigQuery('my-project', 'my_dataset', 'events',
                  service_account_key = '{"type": "service_account", ...}');

INSERT INTO events VALUES (1, 'started');

더 알아보기 (Learn more)

bigquery 테이블 함수