JSON para esquema BigQuery — o bq load aceita

O que esta ferramenta faz

Uma amostra JSON vira um arquivo de esquema do BigQuery — o array de descrições de campo que o bq load --schema espera.

{ "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" }]
  }
]

Os nomes de campo guardam as chaves JSON — o BigQuery aceita letras, dígitos e sublinhados, que é o que a maioria das chaves já é.

Todas as linhas, não só a primeira

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

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

O esquema era lido só do primeiro objeto, então carregar o resto da sua própria amostra falhava com no such field: b. Agora os campos são unidos sobre todos os objetos, e aquele que falta em algum é NULLABLE — que é o que ele é.

Era um defeito real, encontrado ao escrever esta página e corrigido, junto com os dois abaixo.

Os tipos se fundem junto com os campos. Uma chave tipada INTEGER numa linha e STRING na seguinte recebe uma coluna JSON: STRING recusaria o número no carregamento. Dois objetos, por outro lado, se fundem num único RECORD, e um subcampo ausente de um dos lados fica ali NULLABLE.

Um array misto é uma coluna JSON

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

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

Uma coluna repetida tem um tipo, e [1, "x"] tem dois. Tipá-lo pelo primeiro elemento — INTEGER REPEATED — produzia um esquema no qual a própria amostra não carrega. O tipo JSON do BigQuery leva o valor como está: é o que recebem os arrays mistos e os arrays de arrays. Inteiros e decimais misturados continuam sendo um FLOAT repetido, que cobre os dois.

Dois palpites, ditos

• null vira STRING NULLABLE. A amostra mostra uma chave e nenhum tipo; STRING é uma escolha, não uma leitura. Se o campo for um número, troque antes da primeira carga.
• Um array vazio vira STRING REPEATED. Mesmo raciocínio: não havia nada dentro. Os dois carregam a sua amostra sem problema, e os dois merecem um segundo olhar quando você conhecer o campo.

Carregar os seus dados JSON no BigQuery

Três coisas precisam bater, e o BigQuery não nomeia nenhuma com clareza quando não batem.

Um objeto por linha. O BigQuery carrega JSON delimitado por quebras de linha, não um array JSON. Se o seu arquivo começa com [, ele não carrega — o conversor NDJSON daqui faz exatamente essa conversão.

O esquema no arquivo dele. Salve o array acima como schema.json. Ele não faz parte do arquivo de dados nem é lido dele.

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

Ou pela API. O mesmo array vai em schema.fields da configuração do job de carga — o arquivo e a API esperam o mesmo conteúdo.

Privado por padrão

Tudo é executado localmente no seu navegador com JavaScript. Os seus dados nunca são enviados para um servidor, o que torna a ferramenta segura para conteúdo sensível e funciona offline.