Pourquoi mon tableau mêlé est-il devenu une colonne JSON ?

Parce qu’aucune colonne répétée ne peut le contenir. `[1, "x"]` sortait en `INTEGER REPEATED`, d’après le premier élément — et le chargement de ce même échantillon échouait sur le second. BigQuery a un type `JSON` natif qui prend la valeur telle quelle : c’est ce que reçoit un tableau mêlé. Un tableau homogène reste une colonne répétée de son type.

Pourquoi un champ est-il NULLABLE alors que ma première ligne l’a toujours ?

Parce qu’une autre ligne ne l’a pas. Le schéma est l’union de tous les objets de l’échantillon, et un champ absent de certains ne peut pas être REQUIRED : le chargement refuserait ces lignes. Ne lire que le premier objet donnait un schéma qui échouait sur le reste avec « no such field ».

Comment employer le fichier ?

`bq load --source_format=NEWLINE_DELIMITED_JSON --schema=schema.json mydataset.mytable data.ndjson`. Le schéma vit dans son propre fichier, à côté des données et non dedans ; par l’API, le même tableau se place sous `schema.fields`.

JSON en schéma BigQuery — bq load l’accepte

Transformez un échantillon JSON en fichier de schéma BigQuery. Les champs de toutes les lignes sont fusionnés : le chargement passe du premier coup.

Ce que fait cet outil

Un échantillon JSON devient un fichier de schéma BigQuery — le tableau de descriptions de champs qu’attend bq load --schema.

{ "id": 1, "firstName": "Ada", "address": { "city": "Paris" } }

[
  { "name": "id", "type": "INTEGER", "mode": "REQUIRED" },
  { "name": "firstName", "type": "STRING", "mode": "REQUIRED" },
  {
    "name": "address",
    "type": "RECORD",
    "mode": "REQUIRED",
    "fields": [{ "name": "city", "type": "STRING", "mode": "REQUIRED" }]
  }
]

Les noms de champs gardent les clés JSON — BigQuery accepte lettres, chiffres et tirets bas, ce que la plupart des clés sont déjà.

Toutes les lignes, pas seulement la première

[{ "a": 1 }, { "a": 2, "b": "x" }]

[
  { "name": "a", "type": "INTEGER", "mode": "REQUIRED" },
  { "name": "b", "type": "STRING", "mode": "NULLABLE" }
]

Le schéma était lu sur le seul premier objet : charger le reste de votre propre échantillon échouait donc avec no such field: b. Les champs sont maintenant réunis sur tous les objets, et celui qui manque quelque part est NULLABLE — ce qu’il est.

C’était un vrai défaut, trouvé en écrivant cette page et corrigé, avec les deux ci-dessous.

Les types se fondent avec les champs. Une clé typée INTEGER sur une ligne et STRING sur la suivante reçoit une colonne JSON : STRING refuserait le nombre au chargement. Deux objets, en revanche, se fondent en un seul RECORD, et un sous-champ absent d’un côté y est NULLABLE.

Un tableau mêlé est une colonne JSON

{ "arr": [1, "x"] }

[{ "name": "arr", "type": "JSON", "mode": "NULLABLE" }]

Une colonne répétée a un type, et [1, "x"] en a deux. Le typer d’après le premier élément — INTEGER REPEATED — produisait un schéma dans lequel l’échantillon lui-même ne se charge pas. Le type JSON de BigQuery porte la valeur telle quelle : c’est ce que reçoivent les tableaux mêlés et les tableaux de tableaux. Entiers et décimaux mêlés restent un FLOAT répété, qui couvre les deux.

Deux suppositions, nommées

null devient STRING NULLABLE. L’échantillon montre une clé et aucun type ; STRING est un choix, pas une lecture. Si le champ est un nombre, changez-le avant le premier chargement.
Un tableau vide devient STRING REPEATED. Même raisonnement : il n’y avait rien dedans. Les deux chargent votre échantillon sans problème, et les deux méritent un second regard quand vous connaissez le champ.

Charger vos données JSON dans BigQuery

Trois choses doivent s’aligner, et BigQuery n’en nomme aucune clairement quand ce n’est pas le cas.

Un objet par ligne. BigQuery charge du JSON délimité par des sauts de ligne, pas un tableau JSON. Si votre fichier commence par [, il ne se chargera pas — le convertisseur NDJSON d’ici fait exactement cette conversion.

Le schéma dans son propre fichier. Enregistrez le tableau ci-dessus sous schema.json. Il ne fait pas partie du fichier de données, et il n’en est pas déduit.

bq load \
  --source_format=NEWLINE_DELIMITED_JSON \
  --schema=schema.json \
  mydataset.mytable \
  data.ndjson

Ou par l’API. Le même tableau se place sous schema.fields de la configuration du job de chargement — le fichier et l’API attendent un contenu identique.

Confidentiel par conception

Tout s’exécute localement dans votre navigateur en JavaScript. Vos données ne sont jamais envoyées sur un serveur, ce qui rend l’outil sûr pour des contenus sensibles, et il fonctionne hors ligne.

JSON en schéma BigQuery — bq load l’accepte

Entrée JSON

Sortie BigQuery