Carga datos JSON desde Cloud Storage

Puedes cargar datos JSON delimitados por saltos de línea (ndJSON) desde Cloud Storage en una tabla o partición nuevas, o puedes agregar o reemplazar una tabla o partición existente. Cuando tus datos se cargan en BigQuery, se convierten en formato de columnas para Capacitor (formato de almacenamiento de BigQuery).

Cuando cargas datos de Cloud Storage en una tabla de BigQuery, el conjunto de datos que contiene la tabla debe estar en la misma ubicación regional o multirregional que el bucket de Cloud Storage.

El formato ndJSON es el mismo que el formato líneas JSON.

Limitaciones

Estás sujeto a las siguientes limitaciones cuando cargas datos en BigQuery desde un bucket de Cloud Storage:

• Si la ubicación de tu conjunto de datos está configurada en un valor diferente a la multirregión US, el bucket de Cloud Storage debe estar en la misma región o multirregión que el conjunto de datos.
• BigQuery no garantiza la coherencia de los datos provenientes de fuentes de datos externas. Los cambios en los datos subyacentes mientras se ejecuta una consulta pueden dar como resultado un comportamiento inesperado.
• BigQuery no es compatible con el control de versiones de objetos de Cloud Storage. Si incluyes un número de generación en el URI de Cloud Storage, el trabajo de carga fallará.

Cuando cargues archivos JSON en BigQuery, ten en cuenta los siguientes factores:

• Los datos JSON deben estar delimitados por saltos de línea o ndJSON. Cada objeto JSON debe estar en una línea separada en el archivo.
• Si usas la compresión gzip, BigQuery no puede leer los datos en paralelo. La carga de datos JSON comprimidos en BigQuery es más lenta que la carga de datos sin comprimir.
• No puedes incluir archivos comprimidos y descomprimidos en el mismo trabajo de carga.
• El tamaño máximo de un archivo gzip es de 4 GB.

• BigQuery admite el tipo JSON incluso si no se conoce la información del esquema en el momento de la transferencia. Un campo que se declara como tipo JSON se carga con los valores JSON sin procesar.

• Si usas la API de BigQuery para cargar un número entero fuera del rango de [-2⁵³+1, 2⁵³-1] (por lo general, esto significa mayor que 9,007,199,254,740,991), en una columna de números enteros (INT64), pásala como una string para evitar la corrupción de los datos. Este problema se debe a una limitación del tamaño de los números enteros en JSON o ECMAScript. Para obtener más información, consulta la sección Números de RFC 7159.

• Cuando cargues datos CSV o JSON, en los valores de las columnas DATE, se debe usar el separador de guion (-), y la fecha debe estar en el siguiente formato: YYYY-MM-DD (año-mes-día).
• Cuando cargues datos JSON o CSV, en los valores de las columnas TIMESTAMP, se debe usar un separador de guion (-) o barra (/) para la parte de fecha de la marca de tiempo, y la fecha debe tener uno de los siguientes formatos: YYYY-MM-DD (año-mes-día) o YYYY/MM/DD (año/mes/día). En la parte de hh:mm:ss (horas-minutos-segundos) de la marca de tiempo, se debe usar un separador de dos puntos (:).

• Tus archivos deben cumplir con los límites de tamaño de archivo JSON descritos en los límites de trabajos de carga.

Antes de comenzar

Otorga roles de Identity and Access Management (IAM) que otorguen a los usuarios los permisos necesarios para hacer cada tarea de este documento y crea un conjunto de datos para almacenar tus datos.

Permisos necesarios

Si deseas cargar datos en BigQuery, necesitas permisos de IAM para ejecutar un trabajo de carga y subir datos en tablas y particiones de BigQuery. Si cargas datos desde Cloud Storage, también necesitas permisos de IAM para acceder al bucket que contiene tus datos.

Permisos para cargar datos a BigQuery

Para cargar datos en una tabla o partición de BigQuery nueva o bien agregar o reemplazar una tabla o partición existente, necesitas los siguientes permisos de IAM:

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

Cada una de las siguientes funciones predefinidas de IAM incluye los permisos que necesitas para cargar datos en una tabla o partición de BigQuery:

• roles/bigquery.dataEditor
• roles/bigquery.dataOwner
• roles/bigquery.admin (incluye el permiso bigquery.jobs.create)
• bigquery.user (incluye el permiso bigquery.jobs.create)
• bigquery.jobUser (incluye el permiso bigquery.jobs.create)

Además, si tienes el permiso bigquery.datasets.create, puedes crear y actualizar tablas con un trabajo de carga en los conjuntos de datos que crees.

Para obtener más información sobre las funciones y los permisos de IAM en BigQuery, consulta Funciones y permisos predefinidos.

Permisos para subir datos desde Cloud Storage

Para obtener los permisos que necesitas para cargar datos desde un bucket de Cloud Storage, pídele a tu administrador que te otorgue el rol de IAM Administrador de almacenamiento (roles/storage.admin) en el bucket. Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

Este rol predefinido contiene los permisos necesarios para cargar datos desde un bucket de Cloud Storage. Para ver los permisos exactos que son necesarios, expande la sección Permisos requeridos:

Permisos necesarios

Los siguientes permisos son necesarios para cargar datos desde un bucket de Cloud Storage:

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

También puedes obtener estos permisos con roles personalizados o con otros roles predefinidos.

Crea un conjunto de datos

Crea un conjunto de datos de BigQuery para almacenar tus datos.

Compresión de archivos JSON

Puedes usar la utilidad gzip para comprimir archivos JSON. Ten en cuenta que gzip realiza la compresión completa de archivos, a diferencia de la compresión de contenido de archivos que realizan los códecs de compresión para otros formatos de archivo, como Avro. El uso de gzip para comprimir los archivos JSON puede tener un impacto en el rendimiento. Para obtener más información sobre las compensaciones, consulta Carga datos comprimidos y sin comprimir.

Carga datos JSON en una tabla nueva

Para cargar datos JSON de Cloud Storage en una tabla nueva de BigQuery, sigue estos pasos:

Console

1. En la consola de Google Cloud, ve a la página de BigQuery.

   Ir a BigQuery

2. En el panel Explorador, expande tu proyecto y, luego, elige un conjunto de datos.
3. En la sección Información del conjunto de datos, haz clic en Crear tabla.
4. En el panel Crear tabla, especifica los siguientes detalles:
1. En la sección Fuente, elige Google Cloud Storage en la lista Crear tabla desde. A continuación, sigue estos pasos:
   1. Elige un archivo del bucket de Cloud Storage o escribe el URI de Cloud Storage. No puedes incluir múltiples URI en la consola de Google Cloud, pero se admiten comodines. El bucket de Cloud Storage debe estar en la misma ubicación que el conjunto de datos que contiene la tabla que deseas crear, agregar o reemplazar.
   2. En Formato de archivo, selecciona JSONL (JSON delimitado por saltos de línea).
2. En la sección Destino, especifica los siguientes detalles:
   1. En Conjunto de datos, elige el conjunto de datos en el que deseas crear la tabla.
   2. En el campo Tabla, escribe el nombre de la tabla que deseas crear.
   3. Verifica que el campo Tipo de tabla esté configurado como Tabla nativa.
3. En la sección Esquema, ingresa la definición del esquema. Para habilitar la detección automática de un esquema, selecciona Detección automática. Puedes ingresar la información del esquema de forma manual mediante uno de los siguientes métodos:
   • Opción 1: Haz clic en Editar como texto y pega el esquema con el formato de un array JSON. Cuando usas un array JSON, generas el esquema mediante el mismo proceso que se usa para crear un archivo de esquema JSON. Puedes ver el esquema de una tabla existente en formato JSON si ingresas el siguiente comando:

         bq show --format=prettyjson dataset.table
         

   • Opción 2: Haz clic en Agregar campo y, luego, ingresa el esquema de la tabla. Especifica el Nombre, el Tipo y el Modo de cada campo.
4. Opcional: Especifica Configuración de particiones y clústeres. Para obtener más información, consulta Crea tablas particionadas y Crea y usa tablas agrupadas en clústeres.
5. Haz clic en Opciones avanzadas y haz lo siguiente:
   • En Preferencia de escritura, deja elegido Escribir si está vacía. Con esta opción, se crea una tabla nueva y se cargan los datos en ella.
   • En Cantidad de errores permitidos, acepta el valor predeterminado de 0 o ingresa la cantidad máxima de filas con errores que pueden ignorarse. Si la cantidad de filas con errores excede este valor, el trabajo generará un mensaje de invalid y fallará. Esta opción se aplica solo a los archivos CSV y JSON.
   • Si deseas ignorar los valores de una fila que no están presentes en el esquema de la tabla, selecciona Valores desconocidos.
   • En Encriptación, haz clic en Clave administrada por el cliente para usar una clave de Cloud Key Management Service. Si dejas establecida la configuración del parámetro Clave administrada por Google, BigQuery encripta los datos en reposo.
6. Haga clic en Create table.

Nota: Cuando se cargan datos en una tabla vacía a través de la consola de Google Cloud, no se puede agregar una etiqueta, descripción ni el vencimiento de una tabla ni partición.

Una vez creada la tabla, con la consola de Google Cloud puedes actualizar el vencimiento, la descripción y las etiquetas de la tabla, pero no se puede agregar un vencimiento de la partición. Para obtener más información, consulta Administra tablas.

SQL

Usa la declaración DDL LOAD DATA. En el siguiente ejemplo, se carga un archivo JSON en la tabla mytable nueva:

1. En la consola de Google Cloud, ve a la página de BigQuery.

   Ir a BigQuery

2. En el editor de consultas, escribe la siguiente sentencia:

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

3. Haz clic en Ejecutar.

Si deseas obtener información sobre cómo ejecutar consultas, visita Ejecuta una consulta interactiva.

bq

Usa el comando bq load, especifica NEWLINE_DELIMITED_JSON con la marca --source_format e incluye un URI de Cloud Storage. Puedes incluir un único URI, una lista de URI separados por comas o un URI que contenga un comodín. Proporciona el esquema intercalado con un archivo de definición de esquema o usa la detección automática de esquemas.

Opcional: Proporciona la marca --location y configura el valor en tu ubicación.

Las siguientes son otras marcas opcionales:

• --max_bad_records: Un número entero que especifica la cantidad máxima de registros incorrectos permitidos antes de que falle todo el trabajo. El valor predeterminado es 0. Como máximo, se muestran cinco errores de cualquier tipo, sin importar el valor --max_bad_records.
• --ignore_unknown_values: Cuando se especifica, permite y también ignora valores extras no reconocidos en datos CSV o JSON.
• --autodetect: Cuando se especifica, se habilita la detección automática de esquemas para los datos de formato CSV y JSON.
• --time_partitioning_type: Habilita las particiones basadas en el tiempo en una tabla y establece el tipo de partición. Los valores posibles son HOUR, DAY, MONTH y YEAR. Esta marca es opcional cuando se crea una tabla particionada en una columna DATE, DATETIME o TIMESTAMP. El tipo de partición predeterminado para la partición basada en el tiempo es DAY. No puedes cambiar la especificación de partición de una tabla existente.
• --time_partitioning_expiration: Un número entero que especifica (en segundos) cuándo se debe borrar una partición basada en el tiempo. La hora de vencimiento se evalúa según la suma de la fecha de la partición en formato UTC más el valor del número entero.
• --time_partitioning_field: La columna DATE o TIMESTAMP que se usa para crear una tabla particionada. Si la partición basada en el tiempo se habilita sin este valor, se creará una tabla particionada por tiempo de transferencia.
• --require_partition_filter: Cuando se habilita esta opción, se solicita a los usuarios que incluyan una cláusula WHERE que especifique las particiones que se desean consultar. Exigir un filtro de partición puede reducir los costos y mejorar el rendimiento. Para obtener más información, consulta Cómo exigir un filtro de partición en las consultas.
• --clustering_fields: Una lista separada por comas de hasta cuatro nombres de columna que se usa para crear una tabla agrupada en clústeres.

• --destination_kms_key: Es la clave de Cloud KMS para la encriptación de los datos de la tabla.

  Para obtener más información sobre tablas particionadas, consulta los siguientes artículos:

  • Crea tablas particionadas

  Para obtener más información sobre tablas agrupadas, consulta el siguiente artículo:

  • Crea y usa tablas agrupadas

  Para obtener más información sobre la encriptación de tablas, consulta el siguiente artículo:

  • Protege datos con claves de Cloud KMS

Para cargar datos JSON en BigQuery, ingresa el siguiente comando:

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

Reemplaza lo siguiente:

• LOCATION: Es tu ubicación. La marca --location es opcional. Por ejemplo, si usas BigQuery en la región de Tokio, puedes configurar el valor de la marca como asia-northeast1. Puedes configurar un valor predeterminado para la ubicación con el archivo .bigqueryrc.
• FORMAT: NEWLINE_DELIMITED_JSON.
• DATASET: Es un conjunto de datos existente.
• TABLE: es el nombre de la tabla en la que se están cargando los datos.
• PATH_TO_SOURCE: Es un URI de Cloud Storage completamente calificado o una lista de URI separados por comas. También se admiten comodines.
• SCHEMA: Es un esquema válido. El esquema puede ser un archivo JSON local o se puede escribir intercalado como parte del comando. Si usas un archivo de esquema, no le pongas una extensión. También puedes usar la marca --autodetect en lugar de proporcionar una definición de esquema.

Ejemplos:

El siguiente comando carga datos de gs://mybucket/mydata.json a una tabla llamada mytable en mydataset. El esquema se define en un archivo de esquema local llamado myschema.

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

Con el siguiente comando, se cargan datos de gs://mybucket/mydata.json a una tabla particionada por tiempo de transferencia nueva llamada mytable en mydataset. El esquema se define en un archivo de esquema local llamado myschema.

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

El siguiente comando carga datos de gs://mybucket/mydata.json a una tabla particionada llamada mytable en mydataset. La tabla está particionada en la columna mytimestamp. El esquema se define en un archivo de esquema local llamado myschema.

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

El siguiente comando carga datos de gs://mybucket/mydata.json a una tabla llamada mytable en mydataset. El esquema se detecta de forma automática.

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

El siguiente comando carga datos de gs://mybucket/mydata.json a una tabla llamada mytable en mydataset. El esquema se define intercalado en el 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

Nota: Cuando especificas el esquema con la herramienta de bq, no puedes incluir un tipo RECORD (STRUCT) ni una descripción de campo, y tampoco puedes especificar el modo de campo. Todos los modos de campo están configurados como NULLABLE de forma predeterminada. Para incluir descripciones de campo, modos y tipos de RECORD, proporciona un archivo de esquema JSON en su lugar.

El siguiente comando carga datos de varios archivos en gs://mybucket/ en una tabla llamada mytable en mydataset. El URI de Cloud Storage usa un comodín. El esquema se detecta de forma automática.

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

El siguiente comando carga datos de varios archivos en gs://mybucket/ en una tabla llamada mytable en mydataset. El comando incluye una lista separada por comas de URI de Cloud Storage con comodines. El esquema se define en un archivo de esquema local llamado myschema.

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

API

1. Crea un trabajo load que apunte a los datos de origen en Cloud Storage.

2. Especifica tu ubicación en la propiedad location de la sección jobReference del recurso de trabajo (opcional).

3. La propiedad source URIs debe estar completamente calificada en el formato gs://BUCKET/OBJECT. Cada URI puede contener un carácter comodín “*”.

4. Para especificar el formato de los datos JSON, establece la propiedad sourceFormat como NEWLINE_DELIMITED_JSON.

5. Para verificar el estado del trabajo, llama a jobs.get(JOB_ID*) y reemplaza JOB_ID por el ID del trabajo que muestra la solicitud inicial.

   • Si se muestra status.state = DONE, el trabajo se completó de forma correcta.
   • Si la propiedad status.errorResult está presente, la solicitud falló y ese objeto incluye información que describe lo que salió mal. Cuando una solicitud falla, no se crea ninguna tabla ni se cargan datos.
   • Si status.errorResult está ausente, el trabajo se completó con éxito, aunque puede haber algunos errores recuperables, como problemas cuando se importan algunas filas. Se enumeran los errores recuperables en la propiedad status.errors del objeto de trabajo que se muestra.

Notas de API:

• Los trabajos de carga son atómicos y coherentes. Es decir, si falla uno, ninguno de los datos estará disponible y si uno se hace con éxito, todos los datos estarán disponibles.

• Como práctica recomendada, genera un ID único y pásalo como jobReference.jobId cuando llames a jobs.insert para crear un trabajo de carga. Este enfoque es más resistente al fallo de la red porque el cliente puede sondear o reintentar con el ID de trabajo conocido.

• Llamar a jobs.insert con un ID de trabajo dado es idempotente. En otras palabras, puedes volver a intentarlo tantas veces como desees con el mismo ID de trabajo y al menos una de las operaciones será correcta.

C#

Antes de probar este ejemplo, sigue las instrucciones de configuración para C# incluidas en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para C#.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

Usa el método BigQueryClient.CreateLoadJob() para iniciar un trabajo de carga desde Cloud Storage. Para usar JSONL, crea un objeto CreateLoadJobOptions y establece su propiedad 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 probar este ejemplo, sigue las instrucciones de configuración para Go incluidas en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para Go.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas 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 probar este ejemplo, sigue las instrucciones de configuración para Java incluidas en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para Java.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

Usa el método LoadJobConfiguration.builder(tableId, sourceUri) para iniciar un trabajo de carga desde Cloud Storage. Para usar JSON delimitado por saltos de línea usa 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 probar este ejemplo, sigue las instrucciones de configuración para Node.js incluidas en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para Node.js.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas 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 probar este ejemplo, sigue las instrucciones de configuración para PHP incluidas en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para PHP.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas 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 probar este ejemplo, sigue las instrucciones de configuración para Python incluidas en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para Python.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

Usa el método Client.load_table_from_uri() para iniciar un trabajo de carga desde Cloud Storage. Para usar JSONL, configura la propiedad LoadJobConfig.source_format en la cadena NEWLINE_DELIMITED_JSON y pasa la configuración del trabajo como el argumento job_config para el 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 probar este ejemplo, sigue las instrucciones de configuración para Ruby incluidas en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para Ruby.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

Usa el método Dataset.load_job() para iniciar un trabajo de carga desde Cloud Storage. Para usar JSONL, establece el 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

Carga datos JSON anidados y repetidos

BigQuery admite la carga de datos anidados y repetidos de formatos de origen que admiten esquemas basados en objetos, como JSON, Avro, ORC, Parquet, Firestore y Datastore.

Debe aparecer un objeto JSON, lo que incluye los campos anidados o repetidos en cada línea.

En el siguiente ejemplo, se muestran datos anidados o repetidos de muestra. Esta tabla contiene información sobre las personas. Consta de los siguientes campos:

• id
• first_name
• last_name
• dob (fecha de nacimiento)
• addresses (un campo repetido y anidado)
  • addresses.status (actual o anterior)
  • addresses.address
  • addresses.city
  • addresses.state
  • addresses.zip
  • addresses.numberOfYears (años en la dirección)

El archivo de datos JSON debería ser similar a lo que se muestra a continuación. Observa que el campo de dirección contiene un arreglo de valores (indicado 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"}]}

El esquema para esta tabla se vería como el siguiente:

[
    {
        "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 obtener más información sobre cómo especificar un esquema anidado y repetido, consulta Especifica columnas anidadas y repetidas.

Carga datos JSON semiestructurados

BigQuery admite la carga de datos semiestructurados, en los que un campo puede tomar valores de diferentes tipos. En el siguiente ejemplo, se muestran datos similares al ejemplo anterior de datos JSON anidados y repetidos, excepto que el campo address puede ser una STRING, un STRUCT o un 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"]}

Puedes cargar estos datos en BigQuery mediante el siguiente 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"
    }
]

El campo address se carga en una columna con el tipo JSON que le permite contener los tipos mixtos en el ejemplo. Puedes transferir datos como JSON sin importar si contienen tipos mixtos o no. Por ejemplo, puedes especificar JSON en lugar de STRING como el tipo para el campo first_name. Para obtener más información, consulta Trabaja con datos JSON en GoogleSQL.

Anexa o reemplaza una tabla con datos JSON

Puedes cargar datos adicionales en una tabla desde archivos de origen o cuando adjuntas resultados de consultas.

En la consola de Google Cloud, usa la opción de Preferencia de escritura para especificar qué acción se debe tomar cuando cargues datos desde un archivo de origen o desde el resultado de una consulta.

Cuando cargas datos adicionales en una tabla, tienes las siguientes opciones:

Opción de Console	Marca de la herramienta de bq	Propiedad de la API de BigQuery	Descripción
Realiza la operación de escritura si la tabla está vacía.	No compatible	WRITE_EMPTY	Solo escribe los datos si la tabla está vacía.
Adjuntar a la tabla	--noreplace o --replace=false; si no se especifica --[no]replace, la opción predeterminada es agregar	WRITE_APPEND	Agrega los datos al final de la tabla (predeterminado).
Reemplazar tabla	--replace o --replace=true.	WRITE_TRUNCATE	Borra todos los datos existentes de una tabla antes de escribir los datos nuevos. Esta acción también borra el esquema de la tabla, la seguridad a nivel de las filas y quita cualquier clave de Cloud KMS.

Si cargas datos en una tabla existente, el trabajo de carga puede agregar los datos o reemplazar la tabla.

Puedes agregar o reemplazar una tabla con una de las siguientes opciones:

• La consola de Google Cloud
• El comando bq load de la herramienta de línea de comandos de bq
• El método de API jobs.insert y la configuración de un trabajo load
• Las bibliotecas cliente

Nota: En esta página, no se explica cómo reemplazar tablas particionadas ni cómo agregarles datos. Para obtener información sobre cómo agregar y reemplazar tablas particionadas, consulta Anexa y reemplaza datos de tablas particionadas.

Console

1. En la consola de Google Cloud, ve a la página de BigQuery.

   Ir a BigQuery

2. En el panel Explorador, expande tu proyecto y, luego, elige un conjunto de datos.
3. En la sección Información del conjunto de datos, haz clic en Crear tabla.
4. En el panel Crear tabla, especifica los siguientes detalles:
1. En la sección Fuente, elige Google Cloud Storage en la lista Crear tabla desde. A continuación, sigue estos pasos:
   1. Elige un archivo del bucket de Cloud Storage o escribe el URI de Cloud Storage. No puedes incluir múltiples URI en la consola de Google Cloud, pero se admiten comodines. El bucket de Cloud Storage debe estar en la misma ubicación que el conjunto de datos que contiene la tabla que deseas crear, agregar o reemplazar.
   2. En Formato de archivo, selecciona JSONL (JSON delimitado por saltos de línea).
Nota: Es posible modificar el esquema de la tabla cuando le agregas datos o la reemplazas. Para obtener más información sobre los cambios de esquema admitidos durante una operación de carga, consulta Modifica esquemas de tablas.
2. En la sección Destino, especifica los siguientes detalles:
   1. En Conjunto de datos, elige el conjunto de datos en el que deseas crear la tabla.
   2. En el campo Tabla, escribe el nombre de la tabla que deseas crear.
   3. Verifica que el campo Tipo de tabla esté configurado como Tabla nativa.
3. En la sección Esquema, ingresa la definición del esquema. Para habilitar la detección automática de un esquema, selecciona Detección automática. Puedes ingresar la información del esquema de forma manual mediante uno de los siguientes métodos:
   • Opción 1: Haz clic en Editar como texto y pega el esquema con el formato de un array JSON. Cuando usas un array JSON, generas el esquema mediante el mismo proceso que se usa para crear un archivo de esquema JSON. Puedes ver el esquema de una tabla existente en formato JSON si ingresas el siguiente comando:

         bq show --format=prettyjson dataset.table
         

   • Opción 2: Haz clic en Agregar campo y, luego, ingresa el esquema de la tabla. Especifica el Nombre, el Tipo y el Modo de cada campo.
   Nota: Es posible modificar el esquema de la tabla cuando le agregas datos o la reemplazas. Para obtener más información sobre los cambios de esquema admitidos durante una operación de carga, consulta Modifica esquemas de tablas.
4. Opcional: Especifica Configuración de particiones y clústeres. Para obtener más información, consulta Crea tablas particionadas y Crea y usa tablas agrupadas en clústeres. No puedes agregar datos a una tabla ni reemplazarla para convertirla en una tabla particionada o agrupada en clústeres. La consola de Google Cloud no admite agregar datos a tablas particionadas o agrupadas en clústeres ni reemplazarlas en un trabajo de carga.
5. Haz clic en Opciones avanzadas y haz lo siguiente:
   • En Preferencia de escritura, elige Agregar a la tabla o Reemplazar tabla.
   • En Cantidad de errores permitidos, acepta el valor predeterminado de 0 o ingresa la cantidad máxima de filas con errores que pueden ignorarse. Si la cantidad de filas con errores excede este valor, el trabajo generará un mensaje de invalid y fallará. Esta opción se aplica solo a los archivos CSV y JSON.
   • Si deseas ignorar los valores de una fila que no están presentes en el esquema de la tabla, selecciona Valores desconocidos.
   • En Encriptación, haz clic en Clave administrada por el cliente para usar una clave de Cloud Key Management Service. Si dejas establecida la configuración del parámetro Clave administrada por Google, BigQuery encripta los datos en reposo.
6. Haga clic en Create table.

SQL

Usa la declaración DDL LOAD DATA. En el siguiente ejemplo, se agrega un archivo JSON a la tabla mytable:

1. En la consola de Google Cloud, ve a la página de BigQuery.

   Ir a BigQuery

2. En el editor de consultas, escribe la siguiente sentencia:

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

3. Haz clic en Ejecutar.

Si deseas obtener información sobre cómo ejecutar consultas, visita Ejecuta una consulta interactiva.

bq

Usa el comando bq load, especifica NEWLINE_DELIMITED_JSON con la marca --source_format e incluye un URI de Cloud Storage. Puedes incluir un único URI, una lista de URI separados por comas o un URI que contenga un comodín.

Proporciona el esquema intercalado con un archivo de definición de esquema o usa la detección automática de esquemas.

Especifica la marca --replace para reemplazar la tabla. Usa la marca --noreplace para adjuntar datos a la tabla. Si no se especifica ninguna marca, se agregan datos de manera predeterminada.

Es posible modificar el esquema de la tabla cuando adjuntas datos a ella o la reemplazas. Para obtener más información sobre los cambios de esquema admitidos durante una operación de carga, consulta Modifica esquemas de tablas.

Opcional: Proporciona la marca --location y configura el valor en tu ubicación.

Las siguientes son otras marcas opcionales:

• --max_bad_records: Un número entero que especifica la cantidad máxima de registros incorrectos permitidos antes de que falle todo el trabajo. El valor predeterminado es 0. Como máximo, se muestran cinco errores de cualquier tipo, sin importar el valor --max_bad_records.
• --ignore_unknown_values: Cuando se especifica, permite y también ignora valores extras no reconocidos en datos CSV o JSON.
• --autodetect: Cuando se especifica, se habilita la detección automática de esquemas para los datos de formato CSV y JSON.
• --destination_kms_key: Es la clave de Cloud KMS para la encriptación de los datos de la tabla.

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

Reemplaza lo siguiente:

• LOCATION: Es tu ubicación. La marca --location es opcional. Puedes configurar un valor predeterminado para la ubicación mediante el archivo .bigqueryrc.
• FORMAT: NEWLINE_DELIMITED_JSON.
• DATASET: Es un conjunto de datos existente.
• TABLE: es el nombre de la tabla en la que se están cargando los datos.
• PATH_TO_SOURCE: Es un URI de Cloud Storage completamente calificado o una lista de URI separados por comas. También se admiten comodines.
• SCHEMA: Es un esquema válido. El esquema puede ser un archivo JSON local o se puede escribir intercalado como parte del comando. También puedes usar la marca --autodetect en lugar de proporcionar una definición de esquema.

Ejemplos:

Con el siguiente comando, se cargan datos de gs://mybucket/mydata.json y se reemplazan los datos de una tabla llamada mytable en mydataset. El esquema se define mediante la detección automática de esquemas.

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

Con el siguiente comando, se cargan datos de gs://mybucket/mydata.json y se adjuntan datos a una tabla llamada mytable en mydataset. El esquema se define mediante un archivo de esquema JSON: myschema.

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

API

1. Crea un trabajo load que apunte a los datos de origen en Cloud Storage.

2. Especifica tu ubicación en la propiedad location de la sección jobReference del recurso de trabajo (opcional).

3. La propiedad source URIs debe estar completamente calificada en el formato gs://BUCKET/OBJECT. Puedes incluir varios URI en una lista separada por comas. También se admiten los comodines.

4. Para especificar el formato de los datos, establece la propiedad configuration.load.sourceFormat en NEWLINE_DELIMITED_JSON.

5. Para especificar la preferencia de escritura, establece la propiedad configuration.load.writeDisposition en WRITE_TRUNCATE o WRITE_APPEND.

Go

Antes de probar este ejemplo, sigue las instrucciones de configuración para Go incluidas en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para Go.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas 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 probar este ejemplo, sigue las instrucciones de configuración para Node.js incluidas en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para Node.js.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas 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 probar este ejemplo, sigue las instrucciones de configuración para PHP incluidas en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para PHP.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas 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 reemplazar las filas de una tabla existente, configura la propiedad LoadJobConfig.write_disposition en la string WRITE_TRUNCATE.

Antes de probar este ejemplo, sigue las instrucciones de configuración para Python incluidas en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para Python.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas 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 reemplazar las filas de una tabla existente, establece el parámetro write de Table.load_job() como "WRITE_TRUNCATE".

Antes de probar este ejemplo, sigue las instrucciones de configuración para Ruby incluidas en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para Ruby.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas 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

Carga datos JSON con partición de subárbol

BigQuery admite la carga de datos JSON con partición de subárbol almacenados en Cloud Storage y propaga las columnas con partición de subárbol en la tabla administrada de destino de BigQuery. Para obtener más información, consulta Carga datos con particiones externas.

Detalles de la carga de datos JSON

En esta sección, se describe cómo BigQuery analiza varios tipos de datos cuando se cargan datos JSON.

Tipos de datos

Booleano. BigQuery puede analizar cualquiera de los siguientes pares para datos booleanos: 1 o 0, true o false, t o f, yes o no, y o n (todos distinguen entre mayúsculas y minúsculas). La detección automática de esquemas detecta de forma automática cualquiera de estas opciones, excepto 0 y 1.

Bytes. Las columnas con tipos BYTES deben codificarse como Base64.

Fecha. Las columnas con tipos DATE deben tener el formato YYYY-MM-DD.

Fecha y hora. Las columnas con tipos DATETIME deben tener el formato YYYY-MM-DD HH:MM:SS[.SSSSSS].

Geográficos. Las columnas con tipos GEOGRAPHY deben contener strings en uno de los siguientes formatos:

• Texto conocido (WKT)
• Objeto binario conocido (WKB)
• GeoJSON

Si usas WKB, el valor debe estar codificado en hexadecimal.

En la siguiente lista, se muestran ejemplos de datos válidos:

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

Antes de cargar datos de GEOGRAPHY, también consulta Carga datos geoespaciales.

Intervalo. Las columnas con tipos INTERVAL deben estar en formato PYMDTHMS ISO 8601, de la siguiente manera:

• P = Designador que indica que el valor representa una duración. Siempre debes incluir esto.
• Y = Año
• M = Mes
• D = Día
• T = Designador que denota la parte del tiempo de la duración. Siempre debes incluir esto.
• H = Hora
• M = Minuto
• S = Segundo. Los segundos se pueden denotar como un valor completo o como un valor fraccionario de hasta seis dígitos, con precisión de microsegundos.

Puedes indicar un valor negativo si antepones un guion (-).

En la siguiente lista, se muestran ejemplos de datos válidos:

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

Para cargar datos de INTERVAL, debes usar el comando bq load y la marca --schema a fin de especificar un esquema. No puedes subir datos de INTERVAL con la consola.

Hora. Las columnas con tipos TIME deben tener el formato HH:MM:SS[.SSSSSS].

Timestamp. BigQuery acepta varios formatos de marca de tiempo. La marca de tiempo debe incluir una parte de la fecha y una de la hora.

• La parte de la fecha puede tener el formato YYYY-MM-DD o YYYY/MM/DD.

• La parte de la marca de tiempo debe tener el formato HH:MM[:SS[.SSSSSS]] (los segundos y las fracciones de segundos son opcionales).

• La fecha y la hora deben estar separadas por un espacio o “T”.

• De forma opcional, la fecha y la hora pueden estar seguidas por una compensación UTC o el designador de zona UTC (Z). Para obtener más información, consulta Zonas horarias.

Por ejemplo, cualquiera de los siguientes son valores de marca de tiempo válidos:

• 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

Si proporcionas un esquema, BigQuery también acepta el tiempo Unix para los valores de marca de tiempo. Sin embargo, la detección automática de esquemas no detecta este caso y trata el valor como un tipo numérico o de string.

Ejemplos de valores de marca de tiempo de hora de Unix:

• 1534680695
• 1.534680695e11

Array (campo repetido). El valor debe ser un array JSON o null. JSON null se convierte en SQL NULL. El array no puede contener valores null.

Detección automática de esquemas

En esta sección, se describe el comportamiento de la detección automática de esquema cuando se cargan archivos JSON.

Campos repetidos y anidados en JSON

BigQuery infiere los campos anidados y repetidos en archivos JSON. Si el valor de un campo es un objeto JSON, BigQuery carga la columna como un tipo RECORD. Si el valor de un campo es un array, BigQuery carga la columna como una columna repetida. Para ver un ejemplo de datos JSON con datos anidados y repetidos, consulta Carga datos JSON anidados y repetidos.

Conversión de strings

Si habilitas la detección automática de esquemas, BigQuery convierte las strings en tipos booleanos, numéricos o de fecha y hora cuando sea posible. Por ejemplo, con los siguientes datos de JSON, la detección automática de esquemas convierte el campo id en una columna INTEGER:

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

Tipos de codificación

BigQuery espera que los datos JSON estén codificados en UTF-8. Si tienes archivos JSON con otros tipos de codificación compatibles, debes especificar la codificación de forma explícita mediante la marca --encoding para que BigQuery convierta los datos en UTF-8.

BigQuery es compatible con los siguientes tipos de codificación para los archivos 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)

Opciones JSON

Para cambiar la forma en la que BigQuery analiza los datos JSON, especifica opciones adicionales en la consola de Google Cloud, la herramienta de línea de comandos de bq, la API o las bibliotecas cliente.

Opción JSON	Opción de Console	Marca de la herramienta de bq	Propiedad de la API de BigQuery	Descripción
Cantidad de registros incorrectos permitidos	Cantidad de errores permitidos	--max_bad_records	maxBadRecords (Java, Python)	La cantidad máxima de registros erróneos que BigQuery puede ignorar cuando ejecuta el trabajo (opcional). Si la cantidad de registros erróneos excede este valor, se muestra un error no válido en el resultado del trabajo. El valor predeterminado es 0, por lo que es obligatorio que todos los registros sean válidos.
Valores desconocidos	Ignorar valores desconocidos	--ignore_unknown_values	ignoreUnknownValues (Java, Python)	Indica si BigQuery debe permitir valores adicionales que no estén representados en el esquema de la tabla (opcional). Si es verdadero, los valores adicionales se ignoran. Si es falso, los registros con columnas adicionales se tratan como registros incorrectos, y si hay demasiados, se muestra un error no válido en el resultado del trabajo. El valor predeterminado es falso. La propiedad “sourceFormat” determina qué trata BigQuery como un valor adicional; CSV: columnas finales, JSON: valores con nombres que no coinciden con ningún nombre de columna.
Codificación	Ninguno	-E o --encoding	encoding (Python)	La codificación de caracteres de los datos (opcional). Los valores admitidos son UTF-8, ISO-8859-1, UTF-16BE, UTF-16LE, UTF-32BE o UTF-32LE. El valor predeterminado es UTF-8.

¿Qué sigue?

• Para obtener información sobre cómo cargar datos JSON desde un archivo local, consulta Carga datos desde archivos locales.
• Para obtener más información sobre cómo crear, transferir y consultar datos JSON, consulta Trabaja con datos JSON en GoogleSQL.