> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> 이 엔진을 사용하면 공개 데이터셋을 포함한 Google BigQuery 테이블에서 데이터를 읽고 쓸 수 있습니다.

# BigQuery 테이블 엔진

`BigQuery` 엔진을 사용하면 공개 데이터셋을 포함한 [Google BigQuery](https://cloud.google.com/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 = 1` 및 `max_insert_threads = 1`을 사용하는 단일 스레드 환경). 자세한 내용은 [`bigquery` 테이블 함수의 제한 사항](/docs/ko/reference/functions/table-functions/bigquery#limitations)을 참조하십시오.

<div id="creating-a-table">
  ## 테이블 생성
</div>

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

컬럼 목록은 선택 사항입니다. 생략하면 BigQuery 테이블 스키마에서 구조를 추론합니다. 지정하는 경우 컬럼은 BigQuery 컬럼의 부분 집합일 수 있으며, 각 컬럼은 BigQuery 스키마에 매핑된 정확한 유형으로 선언해야 합니다([데이터 타입 매핑](/docs/ko/reference/functions/table-functions/bigquery#data-type-mapping) 참조). 기본값 표현식이 없는 `REQUIRED` BigQuery 필드를 생략한 테이블 정의는 읽을 수는 있지만 쓸 수는 없습니다. BigQuery 스트리밍 삽입은 이러한 필드가 누락된 행을 거부하므로, 해당 `INSERT`는 사전에 거부됩니다. 생략된 `REQUIRED` 필드에 `defaultValueExpression`이 선언되어 있으면 BigQuery가 기본값을 채우므로 테이블은 계속 쓸 수 있습니다. `NULLABLE` `RECORD`는 `Nullable(Tuple(...))`로 매핑되므로 `NULL` 레코드를 손실 없이 왕복할 수 있습니다. 이러한 테이블을 생성하려면(구조를 추론하든 명시적으로 선언하든) 모든 `Nullable(Tuple)` 컬럼과 마찬가지로 `enable_nullable_tuple_type` 설정이 필요합니다. 컬럼을 명시적으로 선언할 때는 이 설정을 피하기 위해 `RECORD` 필드를 일반 `Tuple(...)`로 선언할 수도 있지만, 이 경우 전체 레코드의 `NULL`은 기본 튜플로 강제 변환됩니다. 추론된 유형과 비교해 허용되는 유일한 차이는 `RECORD`의 `Tuple`을 감싸는 `Nullable`을 제거하는 것이며, 동일한 레코드에서만 가능합니다. 널 허용 여부를 다른(내부 또는 외부) 레코드로 옮길 수는 없습니다.

**엔진 매개변수**

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

매개변수는 `key = value` 재정의를 사용하는 [명명된 컬렉션](/docs/ko/concepts/features/configuration/server-config/named-collections)으로도 전달할 수 있습니다. 전체 키 목록과 [인증 메서드](/docs/ko/reference/functions/table-functions/bigquery#authentication)에 관한 설명은 [`bigquery` 테이블 함수](/docs/ko/reference/functions/table-functions/bigquery#arguments)를 참조하십시오. 정확히 하나의 인증 메서드를 제공해야 합니다. 액세스 토큰은 1시간 이내에 만료되므로 영구 테이블에는 `access_token`보다 `service_account_key` 또는 `refresh_token`을 사용하는 것이 좋습니다.

<div id="usage-example">
  ## 사용 예시
</div>

```sql theme={null}
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');
```

<div id="related">
  ## 관련 항목
</div>

* [`bigquery` 테이블 함수](/docs/ko/reference/functions/table-functions/bigquery)