> ## 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` 会分批发送 (每个 request 最多 500 行，并会进一步拆分以确保不超过 BigQuery's 10 MB request-size limit) ，单个 request 本身也可能仅部分成功 (BigQuery 可以提交 request 中的部分行，同时通过 `insertErrors` 拒绝其余行) ；此外，在较早批次已被接受后，后续批次也可能被拒绝——这两种情况下，已提交的行都会保留在 BigQuery 中，而查询将报告 error。每一行都带有稳定的 `insertId` (根据 query id 和该行的序号生成) ，使 BigQuery 能够尽力对重试的行进行去重；由于 `insertId` 取决于序号，只有以相同顺序提供行时，重新运行相同的 `INSERT` 才会进行去重 (例如，采用单线程，并设置 `max_threads = 1` 和 `max_insert_threads = 1`) 。有关详情，请参阅 [`bigquery` 表函数的限制](/docs/zh/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 表 schema 推断结构。指定时，列可以是 BigQuery 列的子集，且每列都必须声明为 BigQuery schema 映射到的准确类型 (请参阅[数据类型映射](/docs/zh/reference/functions/table-functions/bigquery#data-type-mapping)) 。如果表定义省略了没有默认值表达式的 `REQUIRED` BigQuery 字段，则该表可读但不可写：BigQuery 流式插入会拒绝缺少此类字段的行，因此此类 `INSERT` 会被直接拒绝。如果省略的 `REQUIRED` 字段声明了 `defaultValueExpression`，BigQuery 会填入默认值，表仍可写入。`NULLABLE` `RECORD` 会映射为 `Nullable(Tuple(...))`，以确保 `NULL` 记录可无损往返；创建此类表 (无论结构是推断还是显式声明) 均需启用 `enable_nullable_tuple_type` 设置，这与任何 `Nullable(Tuple)` 列相同。显式声明列时，`RECORD` 字段也可声明为普通的 `Tuple(...)` 以避免使用该设置，但代价是整个记录的 `NULL` 会被强制转换为默认元组；与推断类型相比，唯一允许的差异是移除包裹 `RECORD` 的 `Tuple` 的 `Nullable`，且只能在该记录本身移除——不能将可空性移至其他 (内部或外部) 记录。

**引擎参数**

* `project` — 拥有该数据集的 Google Cloud 项目。
* `dataset` — 数据集名称。
* `table` — 表名称。
* `access_token` — OAuth 2.0 访问令牌 (可选的位置参数) 。

这些参数也可通过[命名集合](/docs/zh/concepts/features/configuration/server-config/named-collections)传递，并使用 `key = value` 覆盖。有关完整的键列表及[身份验证方法](/docs/zh/reference/functions/table-functions/bigquery#authentication)的说明，请参阅 [`bigquery` 表函数](/docs/zh/reference/functions/table-functions/bigquery#arguments)。必须且只能提供一种身份验证方法；对于永久表，建议使用 `service_account_key` 或 `refresh_token`，而非 `access_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/zh/reference/functions/table-functions/bigquery)