> ## 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) и записывать в них, включая публичные наборы данных.

Для чтения используется REST API BigQuery (`tabledata.list`), поэтому поддерживается чтение только нативных таблиц (представления, materialized view и внешние таблицы читать нельзя). Для записи используются потоковые вставки (`tabledata.insertAll`), для которых в проекте должен быть включён биллинг.

Записи неатомарны: большой `INSERT` отправляется батчами (не более 500 строк в запросе; кроме того, он разбивается так, чтобы не превысить ограничение BigQuery на размер запроса в 10 МБ), при этом один запрос может быть выполнен лишь частично (BigQuery может закоммитить некоторые строки запроса, отклонив остальные с `insertErrors`), а последующий батч может быть отклонён после успешного принятия предыдущих. В обоих случаях уже закоммиченные строки остаются в BigQuery, а запрос завершается с ошибкой. Каждая строка содержит стабильный `insertId` (полученный из идентификатора запроса и порядкового номера строки), чтобы BigQuery по возможности выполнял дедупликацию повторно отправленных строк. Поскольку `insertId` зависит от порядкового номера, повторный запуск того же `INSERT` выполняет дедупликацию только в том случае, если строки передаются в том же порядке (например, в однопоточном режиме с `max_threads = 1` и `max_insert_threads = 1`). Подробнее см. в [ограничениях табличной функции `bigquery`](/docs/ru/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/ru/reference/functions/table-functions/bigquery#data-type-mapping)). Таблицу, в определении которой отсутствует поле BigQuery `REQUIRED` без выражения значения по умолчанию, можно читать, но нельзя записывать в неё: потоковые вставки BigQuery отклоняют строки без такого поля, поэтому такой `INSERT` отклоняется заранее. Если для опущенного поля `REQUIRED` указано `defaultValueExpression`, BigQuery подставляет значение по умолчанию, и в таблицу по-прежнему можно записывать данные. `NULLABLE` `RECORD` сопоставляется с `Nullable(Tuple(...))`, поэтому записи со значением `NULL` передаются без потерь при записи и последующем чтении; для создания такой таблицы (независимо от того, выводится ли структура или объявляется явно) требуется настройка `enable_nullable_tuple_type`, как и для любого столбца `Nullable(Tuple)`. При явном объявлении столбцов поле `RECORD` можно объявить как обычный `Tuple(...)`, чтобы избежать этой настройки, но при этом `NULL` для всей записи будет преобразован в кортеж по умолчанию; единственное допустимое отличие от выведенного типа — удаление `Nullable`, оборачивающего `Tuple` поля `RECORD`, причём только у этой же записи: nullable нельзя перенести на другую (внутреннюю или внешнюю) запись.

**Параметры движка**

* `project` — проект Google Cloud, которому принадлежит набор данных.
* `dataset` — имя набора данных.
* `table` — имя таблицы.
* `access_token` — токен доступа OAuth 2.0 (необязательный позиционный аргумент).

Параметры также можно передать в виде [именованной коллекции](/docs/ru/concepts/features/configuration/server-config/named-collections) с переопределениями `key = value`. Полный список ключей и описание [методов аутентификации](/docs/ru/reference/functions/table-functions/bigquery#authentication) см. в [табличной функции `bigquery`](/docs/ru/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/ru/reference/functions/table-functions/bigquery)