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

> Le moteur permet de lire et d’écrire dans une table Google BigQuery, y compris dans les jeux de données publics.

# Moteur de table BigQuery

Le moteur `BigQuery` permet de lire et d’écrire dans une table [Google BigQuery](https://cloud.google.com/bigquery), y compris dans des datasets publics.

La lecture utilise l’API REST BigQuery (`tabledata.list`) ; seules les tables natives peuvent donc être lues (les vues, vues matérialisées et tables externes ne le peuvent pas). L’écriture utilise des insertions en streaming (`tabledata.insertAll`), ce qui nécessite d’activer la facturation pour le projet.

Les écritures ne sont pas atomiques : un `INSERT` volumineux est envoyé par batches (500 lignes au maximum par requête et scindé si nécessaire pour respecter la limite de 10 Mo imposée par BigQuery's pour la taille des requêtes), une même requête peut ne réussir que partiellement (BigQuery peut valider certaines lignes d’une requête tout en rejetant les autres avec `insertErrors`), et un batch ultérieur peut être rejeté après l’acceptation de batches précédents — dans les deux cas, les lignes déjà validées restent dans BigQuery tandis que la requête signale une erreur. Chaque ligne comporte un `insertId` stable (dérivé de l’identifiant de la requête et de la position ordinale de la ligne) afin que BigQuery déduplique au mieux les lignes réessayées ; comme le `insertId` dépend de la position ordinale, la réexécution du même `INSERT` ne déduplique que si les lignes sont présentées dans le même ordre (par exemple en mode monothread, avec `max_threads = 1` et `max_insert_threads = 1`). Consultez les [limitations de la fonction de table `bigquery`](/docs/fr/reference/functions/table-functions/bigquery#limitations) pour plus de détails.

<div id="creating-a-table">
  ## Création d’une 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, ...])
```

La liste des colonnes est facultative : si elle est omise, la structure est déduite du schéma de la table BigQuery. Lorsqu’elles sont spécifiées, les colonnes peuvent constituer un sous-ensemble des colonnes BigQuery, et chaque colonne doit être déclarée avec le type exact auquel correspond le schéma BigQuery (voir le [mappage des types de données](/docs/fr/reference/functions/table-functions/bigquery#data-type-mapping)). Une table dont la définition omet un champ BigQuery `REQUIRED` sans expression de valeur par défaut peut être lue, mais pas écrite : les insertions en streaming BigQuery rejettent les lignes omettant un tel champ, et cet `INSERT` est donc rejeté d’emblée. Lorsque le champ `REQUIRED` omis déclare une `defaultValueExpression`, BigQuery renseigne la valeur par défaut et la table reste accessible en écriture. Un `RECORD` `NULLABLE` est mappé vers `Nullable(Tuple(...))` afin que les enregistrements `NULL` puissent effectuer un aller-retour sans perte ; la création d’une telle table (que la structure soit déduite ou déclarée explicitement) nécessite le paramètre `enable_nullable_tuple_type`, comme pour toute colonne `Nullable(Tuple)`. Lors de la déclaration explicite des colonnes, un champ `RECORD` peut à la place être déclaré comme un simple `Tuple(...)` afin d’éviter ce paramètre, au prix de la conversion d’un `NULL` correspondant à l’ensemble de l’enregistrement en tuple par défaut ; la seule différence acceptée par rapport au type déduit consiste à supprimer le `Nullable` qui encapsule le `Tuple` d’un `RECORD`, et uniquement pour cet enregistrement — la nullabilité ne peut pas être déplacée vers un autre enregistrement, interne ou externe.

**Paramètres du moteur**

* `project` — Le projet Google Cloud propriétaire du jeu de données.
* `dataset` — Le nom du jeu de données.
* `table` — Le nom de la table.
* `access_token` — Un jeton d’accès OAuth 2.0 (argument positionnel facultatif).

Les paramètres peuvent également être transmis sous forme de [collection nommée](/docs/fr/concepts/features/configuration/server-config/named-collections), avec des surcharges `key = value`. Consultez la [fonction de table `bigquery`](/docs/fr/reference/functions/table-functions/bigquery#arguments) pour obtenir la liste complète des clés et une description des [méthodes d’authentification](/docs/fr/reference/functions/table-functions/bigquery#authentication). Une seule méthode d’authentification doit être fournie ; pour une table permanente, il est préférable d’utiliser un `service_account_key` ou un `refresh_token` plutôt qu’un `access_token`, car les jetons d’accès expirent au bout d’une heure.

<div id="usage-example">
  ## Exemple d’utilisation
</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">
  ## À consulter également
</div>

* [Fonction de table `bigquery`](/docs/fr/reference/functions/table-functions/bigquery)