Como carregar dados JSON do Cloud Storage

É possível carregar dados JSON delimitados (JSONL) por linha nova do Cloud Storage em uma nova tabela ou partição, ou anexar ou substituir uma tabela ou partição atual. Quando os dados são carregados no BigQuery, eles são convertidos em Capacitor, o formato de armazenamento em colunas do BigQuery.

Quando você carrega dados do Cloud Storage em uma tabela do BigQuery, o conjunto de dados que contém a tabela precisa estar no mesmo local regional ou multirregional que o bucket do Cloud Storage.

O formato JSONL é igual ao JSON Lines.

Limitações

Você está sujeito às limitações a seguir ao carregar dados de um intervalo do Cloud Storage para o BigQuery:

• Se o local do conjunto de dados estiver definido como um valor diferente da multirregião US, o bucket do Cloud Storage precisará estar na mesma região ou estar contido na mesma multirregião que o conjunto de dados.
• O BigQuery não garante a consistência dos dados para fontes de dados externas. Alterações nos dados subjacentes enquanto uma consulta estiver em execução podem resultar em comportamentos inesperados.
• O BigQuery não é compatível com o controle de versões de objetos do Cloud Storage. Se você incluir um número de geração no URI do Cloud Storage, o job de carregamento falhará.

Ao carregar arquivos JSON no BigQuery, considere os itens a seguir:

• Os dados JSON precisam ser delimitados pela nova linha ou JSONL. Cada objeto JSON precisa estar em uma linha separada no arquivo.
• Se você usar a compactação gzip, o BigQuery não conseguirá ler os dados em paralelo. O carregamento de dados JSON compactados no BigQuery é mais lento do que o carregamento de dados não compactados.
• Não é possível incluir arquivos compactados e descompactados no mesmo job de carga.
• O tamanho máximo de um arquivo gzip é de 4 GB.

• O BigQuery é compatível com o tipo JSON, mesmo que as informações do esquema não sejam conhecidas no momento da ingestão. Um campo declarado como tipo JSON é carregado com os valores JSON brutos.

• Se você usar a API BigQuery para carregar um número inteiro fora do intervalo de [-2⁵³+1, 2⁵³-1], isso geralmente significa que maior que 9.007.199.254.740.991, em uma coluna de números inteiros (INT64), transmita-a como uma string para evitar o corrompimento de dados. Esse problema é causado por uma limitação no tamanho do inteiro em JSON ou ECMAScript. Para mais informações, consulte a seção "Números" da RFC 7159.

• Ao carregar dados CSV ou JSON, os valores nas colunas DATE precisam usar o traço (-) e a data precisa estar no seguinte formato: YYYY-MM-DD (ano-mês-dia).
• Quando você carrega dados JSON ou CSV, os valores nas colunas TIMESTAMP precisam usar um traço (-) ou uma barra (/) para a parte da data do carimbo de data/hora, e a data precisa estar em um dos seguintes formatos: YYYY-MM-DD (ano-mês-dia) ou YYYY/MM/DD (ano/mês/dia). A parte hh:mm:ss (hora-minuto-segundo) do carimbo de data/hora precisa usar um separador de dois pontos (:).

• Seus arquivos precisam atender aos limites de tamanho de arquivo JSON descritos nos limites dos jobs de carregamento.

Antes de começar

Atribua papéis do Identity and Access Management (IAM) que concedem aos usuários as permissões necessárias para executar cada tarefa neste documento e crie um conjunto de dados para armazenamento.

Permissões necessárias

Para carregar dados no BigQuery, você precisa de permissões do IAM para executar um job de carregamento e carregar dados nas tabelas e partições do BigQuery. Se você estiver carregando dados do Cloud Storage, também precisará de permissões do IAM para acessar o bucket que contém os dados.

Permissões para carregar dados no BigQuery

Para carregar dados em uma nova tabela ou partição do BigQuery ou anexar ou substituir uma tabela ou partição existente, você precisa das seguintes permissões do IAM:

• bigquery.tables.create
• bigquery.tables.updateData
• bigquery.tables.update
• bigquery.jobs.create

Cada um dos seguintes papéis de IAM predefinidos inclui as permissões necessárias para carregar dados em uma tabela ou partição do BigQuery:

• roles/bigquery.dataEditor
• roles/bigquery.dataOwner
• roles/bigquery.admin (inclui a permissão bigquery.jobs.create)
• bigquery.user (inclui a permissão bigquery.jobs.create)
• bigquery.jobUser (inclui a permissão bigquery.jobs.create)

Além disso, se você tiver a permissão bigquery.datasets.create, poderá criar e atualizar tabelas usando um job de carregamento nos conjuntos de dados que criar.

Para mais informações sobre papéis e permissões do IAM no BigQuery, consulte Papéis e permissões predefinidos.

Permissões para carregar dados do Cloud Storage

Para receber as permissões necessárias para carregar dados de um bucket do Cloud Storage, peça ao administrador para conceder a você o o papel IAM doAdministrador de armazenamento (roles/storage.admin) no bucket. Para mais informações sobre como conceder papéis, consulte Gerenciar acesso.

Esse papel predefinido contém as permissões necessárias para carregar dados de um bucket do Cloud Storage. Para conferir as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As permissões a seguir são necessárias para carregar dados de um bucket do Cloud Storage:

• storage.buckets.get
• storage.objects.get
• storage.objects.list (required if you are using a URI wildcard)

Essas permissões também podem ser concedidas com papéis personalizados ou outros papéis predefinidos.

crie um conjunto de dados

Crie um conjunto de dados do BigQuery para armazenamento.

Compactação de JSON

Você pode usar o utilitário gzip para compactar arquivos JSON. Observe que gzip realiza a compactação completa de arquivos, ao contrário da compactação de conteúdo de arquivos realizada por codecs de compactação para outros formatos de arquivo, como Avro. Usar gzip para compactar seus arquivos JSON pode ter um impacto no desempenho. Para mais informações sobre as desvantagens, consulte Como carregar dados compactados e descompactados.

Como carregar dados JSON em uma nova tabela

Para carregar dados JSON do Cloud Storage em uma nova tabela do BigQuery:

Console

1. No Console do Google Cloud, acesse a página BigQuery.

   Acessar o BigQuery

2. No painel Explorer, expanda seu projeto e selecione um conjunto de dados.
3. Na seção Informações do conjunto de dados, clique em Criar tabela.
4. No painel Criar tabela, especifique os seguintes detalhes:
1. Na seção Origem, selecione Google Cloud Storage na lista Criar tabela de. Em seguida, faça o seguinte:
   1. Selecione um arquivo do bucket do Cloud Storage ou insira o URI do Cloud Storage. Não é possível incluir vários URIs no console do Google Cloud, mas caracteres curinga são suportados. O bucket do Cloud Storage precisa estar no mesmo local que o conjunto de dados que contém a tabela que você quer criar, anexar ou substituir.
   2. Em Formato do arquivo, selecione JSONL (JSON delimitado por nova linha).
2. Na seção Destino, especifique os seguintes campos:
   1. Em Conjunto de dados, selecione o conjunto de dados em que você quer criar a tabela.
   2. No campo Tabela, insira o nome da tabela que você quer criar.
   3. Verifique se o campo Tipo de tabela está definido como Tabela nativa.
3. Na seção Esquema, insira a definição do esquema. Para ativar a detecção automática de um esquema, selecione Detecção automática. É possível inserir as informações do esquema manualmente usando um dos seguintes métodos:
   • Opção 1: clique em Editar como texto e cole o esquema na forma de uma matriz JSON. Com ela, você gera o esquema usando um processo igual ao de criação de um arquivo de esquema JSON. É possível visualizar o esquema de uma tabela existente no formato JSON inserindo o seguinte comando:

         bq show --format=prettyjson dataset.table
         

   • Opção 2: clique em Adicionar campo e insira o esquema da tabela. Especifique o Nome, o Tipo e o Modo de cada campo.
4. Opcional: especifique configurações de partição e cluster. Para mais informações, consulte Como criar tabelas particionadas e Como criar e usar tabelas em cluster.
5. Clique em Opções avançadas e faça o seguinte:
   • Em Preferência de gravação, selecione Gravar apenas se a tabela estiver vazia. Usando essa opção, você cria uma nova tabela e carrega seus dados nela.
   • Em Número de erros permitidos, aceite o valor padrão 0 ou insira o número máximo de linhas com erros que podem ser ignoradas. Se o número de linhas com erros exceder esse valor, o job exibirá uma mensagem invalid e falhará. Essa opção se refere apenas a arquivos CSV e JSON.
   • Se você quiser ignorar valores em uma linha ausentes no esquema da tabela, selecione Valores desconhecidos.
   • Em Criptografia, clique em Chave gerenciada pelo cliente para usar uma chave do Cloud Key Management Service. Se você optar pela configuração Chave gerenciada pelo Google, o BigQuery criptografará os dados em repouso.
6. Selecione Criar tabela.

Observação: ao carregar dados em uma tabela vazia usando o console do Google Cloud, não será possível adicionar um identificador, uma descrição ou uma validade de tabela ou de partição.

Após a criação da tabela, é possível atualizar a validade, a descrição e os identificadores dela. No entanto, não é possível adicionar uma validade de partição depois de criar uma tabela com o console do Google Cloud. Para mais informações, consulte Como gerenciar tabelas.

SQL

Use a instrução DDL LOAD DATA. O exemplo a seguir carrega um arquivo JSON na nova tabela mytable:

1. No Console do Google Cloud, acesse a página BigQuery.

   Ir para o BigQuery

2. No editor de consultas, digite a seguinte instrução:

   LOAD DATA OVERWRITE mydataset.mytable
   (x INT64,y STRING)
   FROM FILES (
     format = 'JSON',
     uris = ['gs://bucket/path/file.json']);
   

3. Clique em Executar.

Para mais informações sobre como executar consultas, acesse Executar uma consulta interativa.

bq

Use o comando bq load, especifique NEWLINE_DELIMITED_JSON usando a sinalização --source_format e inclua um URI do Cloud Storage. É possível incluir um único URI, uma lista de URIs separados por vírgulas ou um URI que contém um caractere curinga. Forneça o esquema in-line em um arquivo de definição de esquema ou use a detecção automática de esquemas.

Opcional: forneça a sinalização --location e defina o valor do local.

Estas são outras sinalizações opcionais:

• --max_bad_records: um número inteiro que especifica o número máximo de registros inválidos permitidos antes de uma falha em todo o job. O valor padrão é 0. No máximo, cinco erros de qualquer tipo são retornados, seja qual for o valor de --max_bad_records.
• --ignore_unknown_values: quando especificado, permite e ignora valores extras não reconhecidos em dados CSV ou JSON.
• --autodetect: quando especificado, ativa a detecção automática de esquemas em dados CSV e JSON.
• --time_partitioning_type: ativa o particionamento baseado em tempo na tabela e define o tipo de partição. Os valores possíveis são HOUR, DAY, MONTH e YEAR. Essa sinalização é opcional quando você cria uma tabela particionada em uma coluna DATE, DATETIME ou TIMESTAMP. O tipo de partição padrão para o particionamento baseado em tempo é DAY. Não é possível alterar a especificação de particionamento em uma tabela existente.
• --time_partitioning_expiration: um número inteiro que especifica em segundos quando uma partição baseada em tempo precisa ser excluída. O prazo de validade é a soma da data UTC da partição com o valor do número inteiro.
• --time_partitioning_field: a coluna DATE ou TIMESTAMP usada para criar uma tabela particionada. Se o particionamento baseado em tempo for ativado sem esse valor, será criada uma tabela particionada por tempo de processamento.
• --require_partition_filter: quando ativada, essa opção exige que os usuários incluam uma cláusula WHERE que especifica as partições a serem consultadas. A exigência de um filtro de partição pode reduzir custos e melhorar o desempenho. Para mais informações, veja Como consultar tabelas particionadas.
• --clustering_fields: uma lista separada por vírgulas de até quatro nomes de colunas usadas para criar uma tabela em cluster.

• --destination_kms_key: a chave do Cloud KMS para criptografia dos dados da tabela.

  Para mais informações sobre tabelas particionadas, consulte:

  • Como criar tabelas particionadas

  Para mais informações sobre tabelas em cluster, consulte:

  • Como criar e usar tabelas em cluster

  Para mais informações sobre a criptografia de tabelas, consulte:

  • Como proteger dados com chaves do Cloud KMS

Para carregar dados JSON no BigQuery, insira o comando a seguir:

bq --location=LOCATION load \
--source_format=FORMAT \
DATASET.TABLE \
PATH_TO_SOURCE \
SCHEMA

Substitua:

• LOCATION: seu local. A sinalização --location é opcional. Por exemplo, se estiver usando o BigQuery na região de Tóquio, defina o valor da sinalização como asia-northeast1. Defina um valor padrão para a unidade usando o arquivo .bigqueryr.
• FORMAT: NEWLINE_DELIMITED_JSON.
• DATASET: um conjunto de dados existente
• TABLE: o nome da tabela em que você está carregando dados.
• PATH_TO_SOURCE é um URI do Cloud Storage totalmente qualificado ou uma lista de URIs separados por vírgulas. Caracteres curinga também são aceitos
• SCHEMA: um esquema válido; É possível que ele seja um arquivo JSON local ou inserido in-line como parte do comando. Se você usar um arquivo de esquema, não atribua uma extensão a ele. Também é possível usar a sinalização --autodetect em vez de fornecer uma definição de esquema.

Exemplos:

O comando a seguir carrega dados de gs://mybucket/mydata.json em uma tabela chamada mytable em mydataset. O esquema é definido em um arquivo de esquema local chamado myschema.

    bq load \
    --source_format=NEWLINE_DELIMITED_JSON \
    mydataset.mytable \
    gs://mybucket/mydata.json \
    ./myschema

O comando a seguir carrega dados de gs://mybucket/mydata.json em uma nova tabela particionada por tempo de processamento chamada mytable em mydataset. O esquema é definido em um arquivo de esquema local chamado myschema.

    bq load \
    --source_format=NEWLINE_DELIMITED_JSON \
    --time_partitioning_type=DAY \
    mydataset.mytable \
    gs://mybucket/mydata.json \
    ./myschema

O comando a seguir carrega dados de gs://mybucket/mydata.json em uma tabela particionada chamada mytable em mydataset. A tabela é particionada na coluna mytimestamp. O esquema é definido em um arquivo de esquema local chamado myschema.

    bq load \
    --source_format=NEWLINE_DELIMITED_JSON \
    --time_partitioning_field mytimestamp \
    mydataset.mytable \
    gs://mybucket/mydata.json \
    ./myschema

O comando a seguir carrega dados de gs://mybucket/mydata.json em uma tabela chamada mytable em mydataset. O esquema é detectado automaticamente.

    bq load \
    --autodetect \
    --source_format=NEWLINE_DELIMITED_JSON \
    mydataset.mytable \
    gs://mybucket/mydata.json

O comando a seguir carrega dados de gs://mybucket/mydata.json em uma tabela chamada mytable em mydataset. O esquema é definido in-line no formato FIELD:DATA_TYPE, FIELD:DATA_TYPE.

    bq load \
    --source_format=NEWLINE_DELIMITED_JSON \
    mydataset.mytable \
    gs://mybucket/mydata.json \
    qtr:STRING,sales:FLOAT,year:STRING

Observação: quando você especifica o esquema usando a ferramenta bq, não pode incluir um tipo RECORD (STRUCT), inserir uma descrição de campo nem especificar o modo de campo. Todos os modos de campo assumem NULLABLE como padrão. Para incluir descrições de campos, modos e tipos RECORD, forneça um arquivo de esquema JSON.

O seguinte comando carrega dados de vários arquivos em gs://mybucket/ em uma tabela chamada mytable em mydataset. O URI do Cloud Storage usa um caractere curinga. O esquema é detectado automaticamente.

    bq load \
    --autodetect \
    --source_format=NEWLINE_DELIMITED_JSON \
    mydataset.mytable \
    gs://mybucket/mydata*.json

O seguinte comando carrega dados de vários arquivos em gs://mybucket/ em uma tabela chamada mytable em mydataset. O comando inclui uma lista separada por vírgulas de URIs do Cloud Storage com caracteres curinga. O esquema é definido em um arquivo de esquema local chamado myschema.

    bq load \
    --source_format=NEWLINE_DELIMITED_JSON \
    mydataset.mytable \
    "gs://mybucket/00/*.json","gs://mybucket/01/*.json" \
    ./myschema

API

1. Crie um job load que aponte para os dados de origem no Cloud Storage.

2. (Opcional) Especifique o local na propriedade location da seção jobReference do recurso do job.

3. É necessário que a propriedade source URIs seja totalmente qualificada no formato gs://BUCKET/OBJECT. Cada URI pode conter um caractere curinga "*".

4. Defina a propriedade sourceFormat como NEWLINE_DELIMITED_JSON para especificar o formato dos dados JSON.

5. Para verificar o status do job, chame jobs.get(JOB_ID*), substituindo JOB_ID pelo ID do job retornado pela solicitação inicial.

   • status.state = DONE indica que o job foi concluído.
   • Se a propriedade status.errorResult estiver presente, a solicitação falhou e esse objeto incluirá informações que descrevem o que deu errado. Quando há falha na solicitação, nenhuma tabela é criada, e os dados não são carregados.
   • A ausência de status.errorResult indica que o job foi concluído com sucesso. No entanto, é possível que tenha havido alguns erros não fatais, como problemas ao importar algumas linhas. Os erros não fatais são listados na propriedade status.errors do objeto do job retornado.

Observações sobre a API:

• Os jobs de carregamento são atômicos e consistentes. Se um deles falhar, nenhum dos dados estará disponível. Se um deles for bem-sucedido, todos os dados estarão disponíveis.

• Como prática recomendada, gere um ID exclusivo e transmita-o como jobReference.jobId ao chamar jobs.insert para criar um job de carregamento. Essa abordagem é mais resistente a falhas de rede porque o cliente pode pesquisar ou tentar novamente com o ID do job conhecido.

• Chamar jobs.insert em um determinado ID do job é idempotente. É possível tentar quantas vezes quiser com o mesmo ID do job e, no máximo, uma das operações será bem-sucedida.

C#

Antes de testar esta amostra, siga as instruções de configuração do C# no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery em C#.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

Use o método BigQueryClient.CreateLoadJob() para iniciar um job de carregamento no Cloud Storage. Para usar JSONL, crie uma CreateLoadJobOptions e defina seu SourceFormat como FileFormat.NewlineDelimitedJson.

using Google.Apis.Bigquery.v2.Data;
using Google.Cloud.BigQuery.V2;
using System;

public class BigQueryLoadTableGcsJson
{
    public void LoadTableGcsJson(
        string projectId = "your-project-id",
        string datasetId = "your_dataset_id"
    )
    {
        BigQueryClient client = BigQueryClient.Create(projectId);
        var gcsURI = "gs://cloud-samples-data/bigquery/us-states/us-states.json";
        var dataset = client.GetDataset(datasetId);
        var schema = new TableSchemaBuilder {
            { "name", BigQueryDbType.String },
            { "post_abbr", BigQueryDbType.String }
        }.Build();
        TableReference destinationTableRef = dataset.GetTableReference(
            tableId: "us_states");
        // Create job configuration
        var jobOptions = new CreateLoadJobOptions()
        {
            SourceFormat = FileFormat.NewlineDelimitedJson
        };
        // Create and run job
        BigQueryJob loadJob = client.CreateLoadJob(
            sourceUri: gcsURI, destination: destinationTableRef,
            schema: schema, options: jobOptions);
        loadJob = loadJob.PollUntilCompleted().ThrowOnAnyError();  // Waits for the job to complete.
        // Display the number of rows uploaded
        BigQueryTable table = client.GetTable(destinationTableRef);
        Console.WriteLine(
            $"Loaded {table.Resource.NumRows} rows to {table.FullyQualifiedId}");
    }
}

Go

Antes de testar esta amostra, siga as instruções de configuração do Go no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery em Go.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

import (
	"context"
	"fmt"

	"cloud.google.com/go/bigquery"
)

// importJSONExplicitSchema demonstrates loading newline-delimited JSON data from Cloud Storage
// into a BigQuery table and providing an explicit schema for the data.
func importJSONExplicitSchema(projectID, datasetID, tableID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	// tableID := "mytable"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	gcsRef := bigquery.NewGCSReference("gs://cloud-samples-data/bigquery/us-states/us-states.json")
	gcsRef.SourceFormat = bigquery.JSON
	gcsRef.Schema = bigquery.Schema{
		{Name: "name", Type: bigquery.StringFieldType},
		{Name: "post_abbr", Type: bigquery.StringFieldType},
	}
	loader := client.Dataset(datasetID).Table(tableID).LoaderFrom(gcsRef)
	loader.WriteDisposition = bigquery.WriteEmpty

	job, err := loader.Run(ctx)
	if err != nil {
		return err
	}
	status, err := job.Wait(ctx)
	if err != nil {
		return err
	}

	if status.Err() != nil {
		return fmt.Errorf("job completed with error: %v", status.Err())
	}
	return nil
}

Java

Antes de testar esta amostra, siga as instruções de configuração do Java no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery em Java.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

Use o método LoadJobConfiguration.builder(tableId, sourceUri) para iniciar um job de carregamento no Cloud Storage. Para usar JSON delimitado por nova linha, use LoadJobConfiguration.setFormatOptions(FormatOptions.json()).

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Field;
import com.google.cloud.bigquery.FormatOptions;
import com.google.cloud.bigquery.Job;
import com.google.cloud.bigquery.JobInfo;
import com.google.cloud.bigquery.LoadJobConfiguration;
import com.google.cloud.bigquery.Schema;
import com.google.cloud.bigquery.StandardSQLTypeName;
import com.google.cloud.bigquery.TableId;

// Sample to load JSON data from Cloud Storage into a new BigQuery table
public class LoadJsonFromGCS {

  public static void runLoadJsonFromGCS() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    String sourceUri = "gs://cloud-samples-data/bigquery/us-states/us-states.json";
    Schema schema =
        Schema.of(
            Field.of("name", StandardSQLTypeName.STRING),
            Field.of("post_abbr", StandardSQLTypeName.STRING));
    loadJsonFromGCS(datasetName, tableName, sourceUri, schema);
  }

  public static void loadJsonFromGCS(
      String datasetName, String tableName, String sourceUri, Schema schema) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      TableId tableId = TableId.of(datasetName, tableName);
      LoadJobConfiguration loadConfig =
          LoadJobConfiguration.newBuilder(tableId, sourceUri)
              .setFormatOptions(FormatOptions.json())
              .setSchema(schema)
              .build();

      // Load data from a GCS JSON file into the table
      Job job = bigquery.create(JobInfo.of(loadConfig));
      // Blocks until this load table job completes its execution, either failing or succeeding.
      job = job.waitFor();
      if (job.isDone()) {
        System.out.println("Json from GCS successfully loaded in a table");
      } else {
        System.out.println(
            "BigQuery was unable to load into the table due to an error:"
                + job.getStatus().getError());
      }
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Column not added during load append \n" + e.toString());
    }
  }
}

Node.js

Antes de testar esta amostra, siga as instruções de configuração do Node.js no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery em Node.js.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

// Import the Google Cloud client libraries
const {BigQuery} = require('@google-cloud/bigquery');
const {Storage} = require('@google-cloud/storage');

// Instantiate clients
const bigquery = new BigQuery();
const storage = new Storage();

/**
 * This sample loads the json file at
 * https://storage.googleapis.com/cloud-samples-data/bigquery/us-states/us-states.json
 *
 * TODO(developer): Replace the following lines with the path to your file.
 */
const bucketName = 'cloud-samples-data';
const filename = 'bigquery/us-states/us-states.json';

async function loadJSONFromGCS() {
  // Imports a GCS file into a table with manually defined schema.

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const datasetId = "my_dataset";
  // const tableId = "my_table";

  // Configure the load job. For full list of options, see:
  // https://cloud.google.com/bigquery/docs/reference/rest/v2/Job#JobConfigurationLoad
  const metadata = {
    sourceFormat: 'NEWLINE_DELIMITED_JSON',
    schema: {
      fields: [
        {name: 'name', type: 'STRING'},
        {name: 'post_abbr', type: 'STRING'},
      ],
    },
    location: 'US',
  };

  // Load data from a Google Cloud Storage file into the table
  const [job] = await bigquery
    .dataset(datasetId)
    .table(tableId)
    .load(storage.bucket(bucketName).file(filename), metadata);
  // load() waits for the job to finish
  console.log(`Job ${job.id} completed.`);

  // Check the job's status for errors
  const errors = job.status.errors;
  if (errors && errors.length > 0) {
    throw errors;
  }
}

PHP

Antes de testar esta amostra, siga as instruções de configuração do PHP no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery em PHP.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

use Google\Cloud\BigQuery\BigQueryClient;
use Google\Cloud\Core\ExponentialBackoff;

/** Uncomment and populate these variables in your code */
// $projectId  = 'The Google project ID';
// $datasetId  = 'The BigQuery dataset ID';

// instantiate the bigquery table service
$bigQuery = new BigQueryClient([
    'projectId' => $projectId,
]);
$dataset = $bigQuery->dataset($datasetId);
$table = $dataset->table('us_states');

// create the import job
$gcsUri = 'gs://cloud-samples-data/bigquery/us-states/us-states.json';
$schema = [
    'fields' => [
        ['name' => 'name', 'type' => 'string'],
        ['name' => 'post_abbr', 'type' => 'string']
    ]
];
$loadConfig = $table->loadFromStorage($gcsUri)->schema($schema)->sourceFormat('NEWLINE_DELIMITED_JSON');
$job = $table->runJob($loadConfig);
// poll the job until it is complete
$backoff = new ExponentialBackoff(10);
$backoff->execute(function () use ($job) {
    print('Waiting for job to complete' . PHP_EOL);
    $job->reload();
    if (!$job->isComplete()) {
        throw new Exception('Job has not yet completed', 500);
    }
});
// check if the job has errors
if (isset($job->info()['status']['errorResult'])) {
    $error = $job->info()['status']['errorResult']['message'];
    printf('Error running job: %s' . PHP_EOL, $error);
} else {
    print('Data imported successfully' . PHP_EOL);
}

Python

Antes de testar esta amostra, siga as instruções de configuração do Python no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery em Python.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

Use o método Client.load_table_from_uri() para iniciar um job de carregamento no Cloud Storage. Para usar JSONL, defina a propriedade LoadJobConfig.source_format como a string NEWLINE_DELIMITED_JSON e transmita a configuração do job como o argumento job_config para o método load_table_from_uri().

from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

# TODO(developer): Set table_id to the ID of the table to create.
# table_id = "your-project.your_dataset.your_table_name"

job_config = bigquery.LoadJobConfig(
    schema=[
        bigquery.SchemaField("name", "STRING"),
        bigquery.SchemaField("post_abbr", "STRING"),
    ],
    source_format=bigquery.SourceFormat.NEWLINE_DELIMITED_JSON,
)
uri = "gs://cloud-samples-data/bigquery/us-states/us-states.json"

load_job = client.load_table_from_uri(
    uri,
    table_id,
    location="US",  # Must match the destination dataset location.
    job_config=job_config,
)  # Make an API request.

load_job.result()  # Waits for the job to complete.

destination_table = client.get_table(table_id)
print("Loaded {} rows.".format(destination_table.num_rows))

Ruby

Antes de testar esta amostra, siga as instruções de configuração do Ruby no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery em Ruby.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

Use o método Dataset.load_job() para iniciar um job de carregamento no Cloud Storage. Para usar JSONL, defina o parâmetro format como "json".

require "google/cloud/bigquery"

def load_table_gcs_json dataset_id = "your_dataset_id"
  bigquery = Google::Cloud::Bigquery.new
  dataset  = bigquery.dataset dataset_id
  gcs_uri  = "gs://cloud-samples-data/bigquery/us-states/us-states.json"
  table_id = "us_states"

  load_job = dataset.load_job table_id, gcs_uri, format: "json" do |schema|
    schema.string "name"
    schema.string "post_abbr"
  end
  puts "Starting job #{load_job.job_id}"

  load_job.wait_until_done! # Waits for table load to complete.
  puts "Job finished."

  table = dataset.table table_id
  puts "Loaded #{table.rows_count} rows to table #{table.id}"
end

Como carregar dados JSON aninhados e repetidos

O BigQuery permite o carregamento de dados aninhados e repetidos de formatos de origem compatíveis com esquemas baseados em objeto, como JSON, Avro, ORC, Parquet, Firestore e Datastore.

Um objeto JSON, incluindo campos aninhados ou repetidos, aparece em cada linha.

O exemplo a seguir mostra dados de amostra aninhados ou repetidos. Esta tabela contém informações sobre pessoas. Ela consiste nos campos abaixo:

• id
• first_name
• last_name
• dob (data de nascimento)
• addresses (um campo aninhado e repetido)
  • addresses.status (atual ou anterior)
  • addresses.address
  • addresses.city
  • addresses.state
  • addresses.zip
  • addresses.numberOfYears (anos no endereço)

O arquivo de dados JSON se parece com o seguinte exemplo. O campo de endereço contém uma matriz de valores (indicada por [ ]).

{"id":"1","first_name":"John","last_name":"Doe","dob":"1968-01-22","addresses":[{"status":"current","address":"123 First Avenue","city":"Seattle","state":"WA","zip":"11111","numberOfYears":"1"},{"status":"previous","address":"456 Main Street","city":"Portland","state":"OR","zip":"22222","numberOfYears":"5"}]}
{"id":"2","first_name":"Jane","last_name":"Doe","dob":"1980-10-16","addresses":[{"status":"current","address":"789 Any Avenue","city":"New York","state":"NY","zip":"33333","numberOfYears":"2"},{"status":"previous","address":"321 Main Street","city":"Hoboken","state":"NJ","zip":"44444","numberOfYears":"3"}]}

O esquema dessa tabela se parece com este:

[
    {
        "name": "id",
        "type": "STRING",
        "mode": "NULLABLE"
    },
    {
        "name": "first_name",
        "type": "STRING",
        "mode": "NULLABLE"
    },
    {
        "name": "last_name",
        "type": "STRING",
        "mode": "NULLABLE"
    },
    {
        "name": "dob",
        "type": "DATE",
        "mode": "NULLABLE"
    },
    {
        "name": "addresses",
        "type": "RECORD",
        "mode": "REPEATED",
        "fields": [
            {
                "name": "status",
                "type": "STRING",
                "mode": "NULLABLE"
            },
            {
                "name": "address",
                "type": "STRING",
                "mode": "NULLABLE"
            },
            {
                "name": "city",
                "type": "STRING",
                "mode": "NULLABLE"
            },
            {
                "name": "state",
                "type": "STRING",
                "mode": "NULLABLE"
            },
            {
                "name": "zip",
                "type": "STRING",
                "mode": "NULLABLE"
            },
            {
                "name": "numberOfYears",
                "type": "STRING",
                "mode": "NULLABLE"
            }
        ]
    }
]

Para informações sobre como especificar um esquema aninhado e repetido, consulte Como especificar campos aninhados e repetidos.

Como carregar dados JSON semiestruturados

O BigQuery é compatível com o carregamento de dados semiestruturados, em que um campo aceita valores de diferentes tipos. O exemplo a seguir mostra dados semelhantes aos exemplos anteriores de dados JSON aninhados e repetidos, exceto que o campo address pode ser um STRING, um STRUCT ou um ARRAY:

{"id":"1","first_name":"John","last_name":"Doe","dob":"1968-01-22","address":"123 First Avenue, Seattle WA 11111"}

{"id":"2","first_name":"Jane","last_name":"Doe","dob":"1980-10-16","address":{"status":"current","address":"789 Any Avenue","city":"New York","state":"NY","zip":"33333","numberOfYears":"2"}}

{"id":"3","first_name":"Bob","last_name":"Doe","dob":"1982-01-10","address":[{"status":"current","address":"789 Any Avenue","city":"New York","state":"NY","zip":"33333","numberOfYears":"2"}, "321 Main Street Hoboken NJ 44444"]}

É possível carregar esses dados no BigQuery usando o seguinte esquema:

[
    {
        "name": "id",
        "type": "STRING",
        "mode": "NULLABLE"
    },
    {
        "name": "first_name",
        "type": "STRING",
        "mode": "NULLABLE"
    },
    {
        "name": "last_name",
        "type": "STRING",
        "mode": "NULLABLE"
    },
    {
        "name": "dob",
        "type": "DATE",
        "mode": "NULLABLE"
    },
    {
        "name": "address",
        "type": "JSON",
        "mode": "NULLABLE"
    }
]

O campo address é carregado em uma coluna com o tipo JSON, que permite armazenar os tipos mistos no exemplo. É possível ingerir dados como JSON, independentemente de eles conterem tipos mistos ou não. Por exemplo, é possível especificar JSON em vez de STRING como o tipo do campo first_name. Para mais informações, consulte Como trabalhar com dados JSON no GoogleSQL.

Como anexar ou substituir uma tabela com dados JSON

Carregue mais dados em uma tabela de arquivos de origem ou anexando resultados de consultas.

No console do Google Cloud, use a opção Preferência de gravação para especificar qual ação será executada ao carregar dados de um arquivo de origem ou de um resultado de consulta.

Você tem as seguintes opções ao carregar mais dados em uma tabela:

Opção do console	flag da ferramenta bq	Propriedade da API BigQuery	Descrição
Gravar apenas se a tabela estiver vazia	Sem suporte	WRITE_EMPTY	Grava dados apenas se a tabela estiver vazia.
Anexar à tabela	--noreplace ou --replace=false; se --[no]replace não for especificado, o padrão será anexado	WRITE_APPEND	(Padrão) Anexa os dados ao final da tabela.
Substituir tabela	--replace ou --replace=true	WRITE_TRUNCATE	Apaga todos os dados da tabela antes de gravar os novos. Essa ação também exclui o esquema da tabela e a segurança no nível da linha, além de remover qualquer chave do Cloud KMS.

Se você carregar dados em uma tabela, o job de carregamento os anexará ou substituirá a tabela.

Você pode anexar ou substituir uma tabela usando uma das seguintes opções:

• Console do Google Cloud
• O comando bq load da ferramenta de linha de comando bq
• O método da API jobs.insert e a configuração de um job load
• As bibliotecas de cliente

Observação: nesta página, não é abordado como anexar ou substituir tabelas particionadas. Para informações sobre esse assunto, consulte Como anexar e substituir dados de tabelas particionadas.

Console

1. No Console do Google Cloud, acesse a página BigQuery.

   Acessar o BigQuery

2. No painel Explorer, expanda seu projeto e selecione um conjunto de dados.
3. Na seção Informações do conjunto de dados, clique em Criar tabela.
4. No painel Criar tabela, especifique os seguintes detalhes:
1. Na seção Origem, selecione Google Cloud Storage na lista Criar tabela de. Em seguida, faça o seguinte:
   1. Selecione um arquivo do bucket do Cloud Storage ou insira o URI do Cloud Storage. Não é possível incluir vários URIs no console do Google Cloud, mas caracteres curinga são suportados. O bucket do Cloud Storage precisa estar no mesmo local que o conjunto de dados que contém a tabela que você quer criar, anexar ou substituir.
   2. Em Formato do arquivo, selecione JSONL (JSON delimitado por nova linha).
Observação: é possível modificar o esquema da tabela ao anexá-la ou substituí-la. Para mais informações sobre alterações de esquema compatíveis durante uma operação de carregamento, consulte Como modificar esquemas de tabelas.
2. Na seção Destino, especifique os seguintes campos:
   1. Em Conjunto de dados, selecione o conjunto de dados em que você quer criar a tabela.
   2. No campo Tabela, insira o nome da tabela que você quer criar.
   3. Verifique se o campo Tipo de tabela está definido como Tabela nativa.
3. Na seção Esquema, insira a definição do esquema. Para ativar a detecção automática de um esquema, selecione Detecção automática. É possível inserir as informações do esquema manualmente usando um dos seguintes métodos:
   • Opção 1: clique em Editar como texto e cole o esquema na forma de uma matriz JSON. Com ela, você gera o esquema usando um processo igual ao de criação de um arquivo de esquema JSON. É possível visualizar o esquema de uma tabela existente no formato JSON inserindo o seguinte comando:

         bq show --format=prettyjson dataset.table
         

   • Opção 2: clique em Adicionar campo e insira o esquema da tabela. Especifique o Nome, o Tipo e o Modo de cada campo.
   Observação: é possível modificar o esquema da tabela ao anexá-la ou substituí-la. Para mais informações sobre alterações de esquema compatíveis durante uma operação de carregamento, consulte Como modificar esquemas de tabelas.
4. Opcional: especifique configurações de partição e cluster. Para mais informações, consulte Como criar tabelas particionadas e Como criar e usar tabelas em cluster. Não é possível anexar ou substituir uma tabela para convertê-la em uma particionada ou em cluster. O console do Cloud não é compatível com anexação ou substituição de tabelas particionadas ou em cluster em um job de carregamento.
5. Clique em Opções avançadas e faça o seguinte:
   • Em Preferência de gravação, escolha Anexar à tabela ou Substituir tabela.
   • Em Número de erros permitidos, aceite o valor padrão 0 ou insira o número máximo de linhas com erros que podem ser ignoradas. Se o número de linhas com erros exceder esse valor, o job exibirá uma mensagem invalid e falhará. Essa opção se refere apenas a arquivos CSV e JSON.
   • Se você quiser ignorar valores em uma linha ausentes no esquema da tabela, selecione Valores desconhecidos.
   • Em Criptografia, clique em Chave gerenciada pelo cliente para usar uma chave do Cloud Key Management Service. Se você optar pela configuração Chave gerenciada pelo Google, o BigQuery criptografará os dados em repouso.
6. Selecione Criar tabela.

SQL

Use a instrução DDL LOAD DATA. O exemplo a seguir anexa um arquivo JSON à tabela mytable:

1. No Console do Google Cloud, acesse a página BigQuery.

   Ir para o BigQuery

2. No editor de consultas, digite a seguinte instrução:

   LOAD DATA INTO mydataset.mytable
   FROM FILES (
     format = 'JSON',
     uris = ['gs://bucket/path/file.json']);
   

3. Clique em Executar.

Para mais informações sobre como executar consultas, acesse Executar uma consulta interativa.

bq

Use o comando bq load, especifique NEWLINE_DELIMITED_JSON usando a sinalização --source_format e inclua um URI do Cloud Storage. É possível incluir um único URI, uma lista de URIs separados por vírgulas ou um URI que contém um caractere curinga.

Forneça o esquema in-line em um arquivo de definição de esquema ou use a detecção automática de esquemas.

Especifique a sinalização --replace para substituir a tabela. Use a sinalização --noreplace para anexar dados à tabela. Se nenhuma sinalização for especificada, o padrão será anexar os dados.

É possível modificar o esquema da tabela ao anexá-la ou substituí-la. Para mais informações sobre alterações de esquema compatíveis durante uma operação de carga, consulte Como modificar esquemas de tabela.

Opcional: forneça a sinalização --location e defina o valor do local.

Estas são outras sinalizações opcionais:

• --max_bad_records: um número inteiro que especifica o número máximo de registros inválidos permitidos antes de uma falha em todo o job. O valor padrão é 0. No máximo, cinco erros de qualquer tipo são retornados, seja qual for o valor de --max_bad_records.
• --ignore_unknown_values: quando especificado, permite e ignora valores extras não reconhecidos em dados CSV ou JSON.
• --autodetect: quando especificado, ativa a detecção automática de esquemas em dados CSV e JSON.
• --destination_kms_key: a chave do Cloud KMS para criptografia dos dados da tabela.

bq --location=LOCATION load \
--[no]replace \
--source_format=FORMAT \
DATASET.TABLE \
PATH_TO_SOURCE \
SCHEMA

Substitua:

• LOCATION: Seu local. A sinalização --location é opcional. É possível definir um valor padrão para o local usando o arquivo .bigqueryrc;
• FORMAT: NEWLINE_DELIMITED_JSON.
• DATASET: um conjunto de dados existente
• TABLE: o nome da tabela em que você está carregando dados.
• PATH_TO_SOURCE é um URI do Cloud Storage totalmente qualificado ou uma lista de URIs separados por vírgulas. Caracteres curinga também são aceitos
• SCHEMA: um esquema válido; É possível que ele seja um arquivo JSON local ou inserido in-line como parte do comando. Também é possível usar a sinalização --autodetect em vez de fornecer uma definição de esquema.

Exemplos:

O comando a seguir carrega dados de gs://mybucket/mydata.json e substitui uma tabela chamada mytable em mydataset. O esquema é definido por meio da detecção automática de esquemas.

    bq load \
    --autodetect \
    --replace \
    --source_format=NEWLINE_DELIMITED_JSON \
    mydataset.mytable \
    gs://mybucket/mydata.json

O seguinte comando carrega dados de gs://mybucket/mydata.json e anexa dados a uma tabela chamada mytable em mydataset. O esquema é definido por um arquivo de esquema JSON – myschema.

    bq load \
    --noreplace \
    --source_format=NEWLINE_DELIMITED_JSON \
    mydataset.mytable \
    gs://mybucket/mydata.json \
    ./myschema

API

1. Crie um job load que aponte para os dados de origem no Cloud Storage.

2. (Opcional) Especifique o local na propriedade location da seção jobReference do recurso do job.

3. A propriedade source URIs precisa ser totalmente qualificada no formato gs://BUCKET/OBJECT. É possível incluir vários URIs como uma lista separada por vírgulas. Os caracteres curinga também são suportados.

4. Especifique o formato de dados definindo a propriedade configuration.load.sourceFormat como NEWLINE_DELIMITED_JSON.

5. Especifique a preferência de gravação definindo a propriedade configuration.load.writeDisposition como WRITE_TRUNCATE ou WRITE_APPEND.

Go

Antes de testar esta amostra, siga as instruções de configuração do Go no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery em Go.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

import (
	"context"
	"fmt"

	"cloud.google.com/go/bigquery"
)

// importJSONTruncate demonstrates loading data from newline-delimeted JSON data in Cloud Storage
// and overwriting/truncating data in the existing table.
func importJSONTruncate(projectID, datasetID, tableID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	// tableID := "mytable"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	gcsRef := bigquery.NewGCSReference("gs://cloud-samples-data/bigquery/us-states/us-states.json")
	gcsRef.SourceFormat = bigquery.JSON
	gcsRef.AutoDetect = true
	loader := client.Dataset(datasetID).Table(tableID).LoaderFrom(gcsRef)
	loader.WriteDisposition = bigquery.WriteTruncate

	job, err := loader.Run(ctx)
	if err != nil {
		return err
	}
	status, err := job.Wait(ctx)
	if err != nil {
		return err
	}

	if status.Err() != nil {
		return fmt.Errorf("job completed with error: %v", status.Err())
	}

	return nil
}

Java

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Field;
import com.google.cloud.bigquery.FormatOptions;
import com.google.cloud.bigquery.Job;
import com.google.cloud.bigquery.JobInfo;
import com.google.cloud.bigquery.LoadJobConfiguration;
import com.google.cloud.bigquery.Schema;
import com.google.cloud.bigquery.StandardSQLTypeName;
import com.google.cloud.bigquery.TableId;

// Sample to overwrite the BigQuery table data by loading a JSON file from GCS
public class LoadJsonFromGCSTruncate {

  public static void runLoadJsonFromGCSTruncate() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    String sourceUri = "gs://cloud-samples-data/bigquery/us-states/us-states.json";
    Schema schema =
        Schema.of(
            Field.of("name", StandardSQLTypeName.STRING),
            Field.of("post_abbr", StandardSQLTypeName.STRING));
    loadJsonFromGCSTruncate(datasetName, tableName, sourceUri, schema);
  }

  public static void loadJsonFromGCSTruncate(
      String datasetName, String tableName, String sourceUri, Schema schema) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      TableId tableId = TableId.of(datasetName, tableName);
      LoadJobConfiguration loadConfig =
          LoadJobConfiguration.newBuilder(tableId, sourceUri)
              .setFormatOptions(FormatOptions.json())
              // Set the write disposition to overwrite existing table data
              .setWriteDisposition(JobInfo.WriteDisposition.WRITE_TRUNCATE)
              .setSchema(schema)
              .build();

      // Load data from a GCS JSON file into the table
      Job job = bigquery.create(JobInfo.of(loadConfig));
      // Blocks until this load table job completes its execution, either failing or succeeding.
      job = job.waitFor();
      if (job.isDone()) {
        System.out.println("Table is successfully overwritten by JSON file loaded from GCS");
      } else {
        System.out.println(
            "BigQuery was unable to load into the table due to an error:"
                + job.getStatus().getError());
      }
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Column not added during load append \n" + e.toString());
    }
  }
}

Node.js

Antes de testar esta amostra, siga as instruções de configuração do Node.js no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery em Node.js.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

// Import the Google Cloud client libraries
const {BigQuery} = require('@google-cloud/bigquery');
const {Storage} = require('@google-cloud/storage');

// Instantiate clients
const bigquery = new BigQuery();
const storage = new Storage();

/**
 * This sample loads the JSON file at
 * https://storage.googleapis.com/cloud-samples-data/bigquery/us-states/us-states.json
 *
 * TODO(developer): Replace the following lines with the path to your file.
 */
const bucketName = 'cloud-samples-data';
const filename = 'bigquery/us-states/us-states.json';

async function loadJSONFromGCSTruncate() {
  /**
   * Imports a GCS file into a table and overwrites
   * table data if table already exists.
   */

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const datasetId = "my_dataset";
  // const tableId = "my_table";

  // Configure the load job. For full list of options, see:
  // https://cloud.google.com/bigquery/docs/reference/rest/v2/Job#JobConfigurationLoad
  const metadata = {
    sourceFormat: 'NEWLINE_DELIMITED_JSON',
    schema: {
      fields: [
        {name: 'name', type: 'STRING'},
        {name: 'post_abbr', type: 'STRING'},
      ],
    },
    // Set the write disposition to overwrite existing table data.
    writeDisposition: 'WRITE_TRUNCATE',
  };

  // Load data from a Google Cloud Storage file into the table
  const [job] = await bigquery
    .dataset(datasetId)
    .table(tableId)
    .load(storage.bucket(bucketName).file(filename), metadata);
  // load() waits for the job to finish
  console.log(`Job ${job.id} completed.`);

  // Check the job's status for errors
  const errors = job.status.errors;
  if (errors && errors.length > 0) {
    throw errors;
  }
}

PHP

Antes de testar esta amostra, siga as instruções de configuração do PHP no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery em PHP.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

use Google\Cloud\BigQuery\BigQueryClient;
use Google\Cloud\Core\ExponentialBackoff;

/** Uncomment and populate these variables in your code */
// $projectId = 'The Google project ID';
// $datasetId = 'The BigQuery dataset ID';
// $tableID = 'The BigQuery table ID';

// instantiate the bigquery table service
$bigQuery = new BigQueryClient([
    'projectId' => $projectId,
]);
$table = $bigQuery->dataset($datasetId)->table($tableId);

// create the import job
$gcsUri = 'gs://cloud-samples-data/bigquery/us-states/us-states.json';
$loadConfig = $table->loadFromStorage($gcsUri)->sourceFormat('NEWLINE_DELIMITED_JSON')->writeDisposition('WRITE_TRUNCATE');
$job = $table->runJob($loadConfig);

// poll the job until it is complete
$backoff = new ExponentialBackoff(10);
$backoff->execute(function () use ($job) {
    print('Waiting for job to complete' . PHP_EOL);
    $job->reload();
    if (!$job->isComplete()) {
        throw new Exception('Job has not yet completed', 500);
    }
});

// check if the job has errors
if (isset($job->info()['status']['errorResult'])) {
    $error = $job->info()['status']['errorResult']['message'];
    printf('Error running job: %s' . PHP_EOL, $error);
} else {
    print('Data imported successfully' . PHP_EOL);
}

Python

Para substituir as linhas em uma tabela atual, defina a propriedade LoadJobConfig.write_disposition para a string WRITE_TRUNCATE.

Antes de testar esta amostra, siga as instruções de configuração do Python no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery em Python.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

import io

from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

# TODO(developer): Set table_id to the ID of the table to create.
# table_id = "your-project.your_dataset.your_table_name

job_config = bigquery.LoadJobConfig(
    schema=[
        bigquery.SchemaField("name", "STRING"),
        bigquery.SchemaField("post_abbr", "STRING"),
    ],
)

body = io.BytesIO(b"Washington,WA")
client.load_table_from_file(body, table_id, job_config=job_config).result()
previous_rows = client.get_table(table_id).num_rows
assert previous_rows > 0

job_config = bigquery.LoadJobConfig(
    write_disposition=bigquery.WriteDisposition.WRITE_TRUNCATE,
    source_format=bigquery.SourceFormat.NEWLINE_DELIMITED_JSON,
)

uri = "gs://cloud-samples-data/bigquery/us-states/us-states.json"
load_job = client.load_table_from_uri(
    uri, table_id, job_config=job_config
)  # Make an API request.

load_job.result()  # Waits for the job to complete.

destination_table = client.get_table(table_id)
print("Loaded {} rows.".format(destination_table.num_rows))

Ruby

Para substituir as linhas em uma tabela, defina o parâmetro write de Table.load_job() para "WRITE_TRUNCATE".

Antes de testar esta amostra, siga as instruções de configuração do Ruby no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery em Ruby.

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

require "google/cloud/bigquery"

def load_table_gcs_json_truncate dataset_id = "your_dataset_id",
                                 table_id   = "your_table_id"

  bigquery = Google::Cloud::Bigquery.new
  dataset  = bigquery.dataset dataset_id
  gcs_uri  = "gs://cloud-samples-data/bigquery/us-states/us-states.json"

  load_job = dataset.load_job table_id,
                              gcs_uri,
                              format: "json",
                              write:  "truncate"
  puts "Starting job #{load_job.job_id}"

  load_job.wait_until_done! # Waits for table load to complete.
  puts "Job finished."

  table = dataset.table table_id
  puts "Loaded #{table.rows_count} rows to table #{table.id}"
end

Como carregar dados JSON particionados do Hive

O BigQuery é compatível com o carregamento de dados JSON particionados do Hive armazenados no Cloud Storage e preenche as colunas de particionamento do Hive como colunas na tabela gerenciada de destino do BigQuery. Para mais informações, consulte Como carregar dados particionados externamente.

Detalhes sobre como carregar dados JSON

Nesta seção, descrevemos como o BigQuery analisa vários tipos de dados ao carregar dados JSON.

Tipos de dados

Boolean. O BigQuery pode analisar qualquer um dos seguintes pares de dados booleanos: 1 ou 0, true ou false, t ou f, yes ou no e y ou n (indiferente a maiúsculas). A detecção automática de esquema detecta qualquer um desses elementos automaticamente, exceto 0 e 1.

Bytes. As colunas com tipos BYTES precisam ser codificadas como Base64.

Date. As colunas com tipos DATE precisam estar no formato YYYY-MM-DD.

Datetime. As colunas com tipos DATETIME precisam estar no formato YYYY-MM-DD HH:MM:SS[.SSSSSS].

Geografia. Colunas com tipos GEOGRAPHY precisam conter strings em um dos seguintes formatos:

• Texto conhecido (WKT)
• Binário conhecido (WKB)
• GeoJSON

Se você usar WKB, o valor será codificado em hexadecimal.

A lista a seguir mostra exemplos de dados válidos:

• WKT: POINT(1 2)
• GeoJSON: { "type": "Point", "coordinates": [1, 2] }
• WKB codificado em hexadecimal: 0101000000feffffffffffef3f0000000000000040

Antes de carregar dados GEOGRAPHY, leia também Como carregar dados geoespaciais.

Interval. As colunas com tipos INTERVAL precisam estar no formato ISO 8601 PYMDTHMS, em que:

• P = Designador que indica que o valor representa uma duração. Sempre inclua isso.
• Y: ano
• M: mês
• D: dia
• T = Designador que indica a parte da duração. Sempre inclua isso.
• H: hora
• M: minuto
• S: segundo Os segundos podem ser indicados como um valor inteiro ou como um valor fracionário de até seis dígitos, com precisão de microssegundos.

É possível indicar um valor negativo adicionando um traço (-).

A lista a seguir mostra exemplos de dados válidos:

• P-10000Y0M-3660000DT-87840000H0M0S
• P0Y0M0DT0H0M0.000001S
• P10000Y0M3660000DT87840000H0M0S

Para carregar dados INTERVAL, use o comando bq load e use a sinalização --schema para especificar um esquema. Não é possível fazer upload de dados de INTERVAL usando o console.

Horário. As colunas com tipos TIME precisam estar no formato HH:MM:SS[.SSSSSS].

Timestamp. O BigQuery aceita vários formatos de carimbo de data/hora. O carimbo de data/hora precisa incluir uma parte de data e de hora.

• A parte da data pode ser formatada como YYYY-MM-DD ou YYYY/MM/DD.

• A parte do carimbo de data/hora precisa ser formatada como HH:MM[:SS[.SSSSSS]] (segundos e frações de segundos são opcionais).

• A data e a hora precisam ser separadas por um espaço ou "T".

• Opcionalmente, a data e a hora podem ser seguidas por um deslocamento de UTC ou um regulador de fuso horário do UTC (Z). Para mais informações, consulte Fusos horários.

Por exemplo, qualquer um dos valores de carimbo de data/hora a seguir é válido:

• 2018-08-19 12:11
• 2018-08-19 12:11:35
• 2018-08-19 12:11:35.22
• 2018/08/19 12:11
• 2018-07-05 12:54:00 UTC
• 2018-08-19 07:11:35.220 -05:00
• 2018-08-19T12:11:35.220Z

Se você fornecer um esquema, o BigQuery também aceitará a época Unix para valores de carimbo de data/hora. No entanto, a detecção automática de esquema não detecta esse caso e trata o valor como um tipo numérico ou string.

Exemplos de valores de carimbo de data/hora da época Unix:

• 1534680695
• 1.534680695e11

Array (campo repetido). O valor precisa ser uma matriz JSON ou null. O JSON null é convertido em NULL do SQL. A matriz em si não pode conter valores null.

Detecção automática de esquema

Esta seção descreve o comportamento da detecção automática de esquema ao carregar arquivos JSON.

Campos aninhados e repetidos no JSON

No BigQuery, os campos aninhados e repetidos são inferidos em arquivos JSON. Se um valor de campo for um objeto JSON, o BigQuery carregará a coluna como um tipo RECORD. Se um valor de campo for uma matriz, o BigQuery carregará a coluna como uma coluna repetida. Para um exemplo de dados JSON com dados aninhados e repetidos, consulte Como carregar dados JSON aninhados e repetidos.

Conversão de string

Se você ativar a detecção automática de esquema, o BigQuery converterá strings em tipos booleanos, numéricos ou de data/hora, quando possível. Por exemplo, com os dados JSON a seguir, a detecção automática de esquema converte o campo id em uma coluna INTEGER:

{ "name":"Alice","id":"12"}
{ "name":"Bob","id":"34"}
{ "name":"Charles","id":"45"}

Tipos de codificação

Para o BigQuery, é necessário que os dados JSON estejam codificados em UTF-8. Se você tiver arquivos JSON com outros tipos de codificação compatíveis, será preciso especificar explicitamente a codificação usando a sinalização --encoding para que o BigQuery converta os dados em UTF-8

O BigQuery é compatível com estes tipos de codificação para arquivos JSON:

• UTF-8
• ISO-8859-1
• UTF-16BE (UTF-16 Big Endian)
• UTF-16LE (UTF-16 Little Endian)
• UTF-32BE (UTF-32 Big Endian)
• UTF-32LE (UTF-32 Little Endian)

Opções do JSON

Para alterar a forma como o BigQuery analisa os dados JSON, especifique outras opções no console do Google Cloud, na ferramenta de linha de comando bq, na API ou nas bibliotecas de cliente.

Opção do JSON	Opção do console	flag da ferramenta bq	Propriedade da API BigQuery	Descrição
Número de registros corrompidos permitidos	Número de erros permitidos	--max_bad_records	maxBadRecords (Java, Python)	(Opcional) O número máximo de registros inválidos que o BigQuery pode ignorar ao executar o job. Se o número exceder esse valor, um erro inválido será retornado no resultado do job. O valor padrão é `0`, o que exige que todos os registros sejam válidos.
Valores desconhecidos	Ignorar valores desconhecidos	--ignore_unknown_values	ignoreUnknownValues (Java, Python)	(Opcional) Indica se o BigQuery precisa permitir valores extras que não estão representados no esquema da tabela. Se for verdadeiro, os outros valores serão ignorados. Se for falso, os registros com colunas extras serão tratados como corrompidos e, se houver muitos dessa forma, um erro inválido será retornado no resultado do job. O valor padrão é falso. A propriedade `sourceFormat` determina o que o BigQuery trata como outro valor. CSV: colunas à direita. JSON: valores nomeados que não correspondem a nenhum nome de coluna.
Codificação	Nenhum	-E ou --encoding	encoding (Python)	(Opcional) A codificação de caracteres dos dados. Os valores compatíveis são UTF-8, ISO-8859-1, UTF-16BE, UTF-16LE, UTF-32BE ou UTF-32LE. O valor padrão é UTF-8.

A seguir

• Para mais informações sobre como carregar dados JSON de um arquivo local, consulte Como carregar dados de arquivos locais.
• Para mais informações sobre como criar, ingerir e consultar dados JSON, consulte Como trabalhar com dados JSON no GoogleSQL.