> ## 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.

> O motor permite ler e gravar em uma tabela do Google BigQuery, incluindo conjuntos de dados públicos.

# Motor de tabela BigQuery

O motor `BigQuery` permite ler dados de uma tabela no [Google BigQuery](https://cloud.google.com/bigquery) e gravar dados nela, incluindo em conjuntos de dados públicos.

A leitura usa a API REST do BigQuery (`tabledata.list`), portanto, apenas tabelas nativas podem ser lidas (visões, visões materializadas e tabelas externas não podem). A gravação usa inserções por streaming (`tabledata.insertAll`), o que exige que o faturamento esteja habilitado para o projeto.

As gravações não são atômicas: um `INSERT` grande é enviado em lotes (no máximo 500 linhas por solicitação e também dividido para permanecer abaixo do limite de 10 MB para o tamanho das solicitações do BigQuery), uma única solicitação pode ser parcialmente bem-sucedida (o BigQuery pode confirmar algumas linhas de uma solicitação e rejeitar outras com `insertErrors`) e um lote posterior pode ser rejeitado após lotes anteriores terem sido aceitos — em ambos os casos, as linhas já confirmadas permanecem no BigQuery enquanto a consulta relata um erro. Cada linha contém um `insertId` estável (derivado do ID da consulta e da posição ordinal da linha), para que o BigQuery deduplique, na medida do possível, as linhas reenviadas; como o `insertId` depende da posição ordinal, executar novamente o mesmo `INSERT` deduplica apenas quando as linhas são apresentadas na mesma ordem (por exemplo, em modo de thread única, com `max_threads = 1` e `max_insert_threads = 1`). Consulte as [limitações da função de tabela `bigquery`](/docs/pt-BR/reference/functions/table-functions/bigquery#limitations) para obter detalhes.

<div id="creating-a-table">
  ## Criar uma tabela
</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, ...])
```

A lista de colunas é opcional: quando omitida, a estrutura é inferida a partir do esquema da tabela do BigQuery. Quando especificadas, as colunas podem ser um subconjunto das colunas do BigQuery, e cada coluna deve ser declarada com o tipo exato para o qual o esquema do BigQuery é mapeado (consulte o [mapeamento de tipos de dados](/docs/pt-BR/reference/functions/table-functions/bigquery#data-type-mapping)). Uma tabela cuja definição omite um campo `REQUIRED` do BigQuery sem uma expressão de valor padrão pode ser lida, mas não receber gravações: as inserções por streaming do BigQuery rejeitam linhas que omitem esse campo; portanto, esse `INSERT` é rejeitado antecipadamente. Quando o campo `REQUIRED` omitido declara uma `defaultValueExpression`, o BigQuery preenche o valor padrão, e a tabela continua aceitando gravações. Um `RECORD` `NULLABLE` é mapeado para `Nullable(Tuple(...))` para que registros `NULL` possam ser gravados e lidos sem perda; criar essa tabela, seja com a estrutura inferida ou declarada explicitamente, requer a configuração `enable_nullable_tuple_type`, como ocorre com qualquer coluna `Nullable(Tuple)`. Ao declarar colunas explicitamente, um campo `RECORD` pode ser declarado como um `Tuple(...)` simples para evitar essa configuração, ao custo de converter um `NULL` do registro inteiro em uma tupla padrão; a única diferença aceita em relação ao tipo inferido é remover o `Nullable` que envolve o `Tuple` de um `RECORD`, e somente nesse mesmo registro — a anulabilidade não pode ser transferida para outro registro, interno ou externo.

**Parâmetros do motor**

* `project` — O projeto do Google Cloud proprietário do conjunto de dados.
* `dataset` — O nome do conjunto de dados.
* `table` — O nome da tabela.
* `access_token` — Um token de acesso OAuth 2.0 (argumento posicional opcional).

Os parâmetros também podem ser informados como uma [coleção nomeada](/docs/pt-BR/concepts/features/configuration/server-config/named-collections), com substituições `key = value`. Consulte a [função de tabela `bigquery`](/docs/pt-BR/reference/functions/table-functions/bigquery#arguments) para ver a lista completa de chaves e a descrição dos [métodos de autenticação](/docs/pt-BR/reference/functions/table-functions/bigquery#authentication). Exatamente um método de autenticação deve ser fornecido; para uma tabela permanente, uma `service_account_key` ou um `refresh_token` é preferível a um `access_token`, pois os tokens de acesso expiram em uma hora.

<div id="usage-example">
  ## Exemplo de uso
</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">
  ## Relacionados
</div>

* [função de tabela `bigquery`](/docs/pt-BR/reference/functions/table-functions/bigquery)