> ## 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`) を使用します。これを使用するには、プロジェクトで billing を有効にする必要があります。

書き込みはアトミックではありません。大規模な `INSERT` はバッチに分けて送信されます (1 リクエストあたり最大 500 行。BigQuery's の 10 MB リクエストサイズ上限を超えないようにも分割されます) 。また、1 つのリクエストが部分的にしか成功しない場合があります (BigQuery はリクエスト内の一部の行を commit し、残りを `insertErrors` で拒否することがあります) 。さらに、先行するバッチが受け入れられた後で、後続のバッチが拒否されることもあります。いずれの場合も、すでに commit された行は BigQuery に残り、クエリでは error が報告されます。各行には安定した `insertId` (クエリ id と行の序数位置から派生) が付与されるため、BigQuery は再試行された行の重複をベストエフォートで排除します。`insertId` は序数位置に依存するため、同じ `INSERT` を再実行した際に重複排除されるのは、行が同じ順序で渡される場合のみです (たとえば、`max_threads = 1` および `max_insert_threads = 1` を指定した single-threaded の場合) 。詳細については、[`bigquery` テーブル関数 の制限事項](/docs/ja/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/ja/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` を削除することだけであり、それも同じレコードでのみ可能です。null 許容性を別の (内側または外側の) レコードに移すことはできません。

**エンジンパラメータ**

* `project` — データセットを所有する Google Cloud プロジェクト。
* `dataset` — データセット名。
* `table` — テーブル名。
* `access_token` — OAuth 2.0 アクセストークン (省略可能な位置引数) 。

パラメータは、`key = value` によるオーバーライドを指定した[名前付きコレクション](/docs/ja/concepts/features/configuration/server-config/named-collections)として渡すこともできます。オプションの完全なリストと[認証方法](/docs/ja/reference/functions/table-functions/bigquery#authentication)の説明については、[`bigquery` テーブル関数](/docs/ja/reference/functions/table-functions/bigquery#arguments)を参照してください。認証方法は必ず 1 つ指定する必要があります。永続テーブルでは、アクセストークンは 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/ja/reference/functions/table-functions/bigquery)