Carga datos desde una fuente de datos local

En esta página, se describe el proceso de carga de datos desde una fuente de datos local.

Para ver los instructivos sobre cómo cargar datos desde una fuente de datos local, consulta la siguiente información:

Descripción general

Puedes cargar datos desde una fuente de datos legible (como tu máquina local) de la siguiente manera:

  • Con GCP Console o la IU web clásica de BigQuery
  • Con el comando bq load de la CLI
  • Con la API
  • Con las bibliotecas cliente

Cuando cargas datos con GCP Console, la IU web clásica de BigQuery o la CLI, se crea de manera automática un trabajo de carga.

Limitaciones

La carga de datos desde una fuente de datos local está sujeta a las siguientes limitaciones:

  • Los comodines y las listas separadas por comas no son compatibles cuando cargas archivos desde una fuente de datos local. Los archivos se deben cargar por separado.
  • Cuando utilizas la IU web clásica de BigQuery, los archivos que se cargan desde una fuente de datos local deben pesar 10 MB o menos, y contener menos de 16,000 filas.

Permisos necesarios

Como mínimo, debes tener los siguientes permisos para cargar datos en BigQuery:

  • bigquery.tables.create para crear una tabla nueva
  • bigquery.tables.updateData si reemplazas o agregas una tabla
  • bigquery.jobs.create para ejecutar el trabajo de carga

Las siguientes funciones predefinidas de Cloud IAM incluyen los permisos bigquery.tables.create y bigquery.tables.updateData:

  • bigquery.dataEditor
  • bigquery.dataOwner
  • bigquery.admin

Las siguientes funciones predefinidas de Cloud IAM incluyen los permisos de bigquery.jobs.create:

  • bigquery.user
  • bigquery.jobUser
  • bigquery.admin

Además, si un usuario tiene permisos de bigquery.datasets.create, cuando crea un conjunto de datos, se le otorga el acceso de bigquery.dataOwner a él. El acceso de bigquery.dataOwner permite al usuario crear y actualizar tablas en el conjunto de datos a través de un trabajo de carga.

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

Carga datos desde una fuente de datos local

Para cargar datos desde una fuente de datos local, sigue los pasos que se detallan a continuación:

Console

  1. Abre la IU web de BigQuery en GCP Console.
    Ir a GCP Console

  2. En el panel de navegación, en la sección Recursos, expande tu proyecto y selecciona un conjunto de datos.

  3. En el lado derecho de la ventana, en el panel de detalles, haz clic en Crear tabla (Create table). El proceso de carga de datos es el mismo que el que se usa para crear una tabla vacía.

    Crear tabla

  4. En la página Crear tabla (Create table), en la sección Origen (Source) haz lo siguiente:

    • Para Crear tabla desde (Create table from), selecciona Subir (Upload).

      Subir tabla

    • En Seleccionar archivo (Select file), haz clic en Navegar (Browse).

      Explorar archivos

    • Busca el archivo y haz clic en Abrir (Open). Ten en cuenta que los comodines y las listas separadas por comas no son compatibles con archivos locales.

    • Para el Formato del archivo, selecciona CSV, JSON (delimitado por saltos de línea), Avro, ORC o Parquet.

  5. En la página Crear tabla (Create table), en la sección Destino (Destination) haz lo siguiente:

    • En Nombre del conjunto de datos (Dataset name), selecciona el conjunto de datos que corresponda.

      Ver conjunto de datos

    • En el campo Nombre de tabla, ingresa el nombre de la tabla que quieres crear en BigQuery.

    • Verifica que Tipo de tabla (Table type) esté configurado como Tabla nativa (Native table).

  6. En la sección Esquema, ingresa la definición del esquema.

    • Para los archivos CSV y JSON, puedes marcar la opción Detección automática a fin de habilitar la detección automática del esquema. La información del esquema se describe en sí en los datos de origen para otros tipos de archivos compatibles.

    • También puedes ingresar la información del esquema de forma manual, como se indica a continuación:

      • Haz clic en Editar como texto y, luego, ingresa el esquema de la tabla como un arreglo de JSON:

      • Usa la opción Agregar campo para ingresar el esquema de forma manual.

  7. Selecciona los elementos aplicables en la sección Opciones avanzadas y, luego, haz clic en Crear tabla. Si deseas obtener información sobre las opciones disponibles, consulta Opciones de CSV y Opciones de JSON.

IU clásica

  1. Ve a la IU web de BigQuery.
    Ir a la IU web de BigQuery

  2. En el panel de navegación, desplaza el cursor sobre un conjunto de datos, haz clic en el ícono de flecha hacia abajo imagen del ícono de flecha hacia abajo y, luego, en Crear tabla nueva. El proceso de carga de datos es el mismo que el que se usa para crear una tabla vacía.

  3. En la página Crear tabla, en la sección Datos de origen:

    • Para Ubicación, selecciona Carga de archivos, haz clic en Seleccionar archivo, busca el archivo y, a continuación, haz clic en Abrir. Ten en cuenta que los comodines y las listas separadas por comas no son compatibles con archivos locales.
    • Para Formato de archivo, selecciona (CSV), JSON (delimitado por saltos de línea), Avro, ORC o Parquet.
  4. En la página Crear tabla, en la sección Tabla de destino (Destination Table), realiza los siguientes pasos:

    • En Nombre de tabla (Table name), selecciona el conjunto de datos que corresponda y, en el campo de nombre de tabla, ingresa el nombre de la tabla que quieres crear en BigQuery.
    • Verifica que Tipo de tabla (Table type) esté configurado como Tabla nativa (Native table).
  5. En la sección Esquema (Schema), ingresa la definición del esquema.

    • Para los archivos CSV y JSON, puedes marcar la opción Detección automática a fin de habilitar la detección automática del esquema. La información del esquema se describe en sí en los datos de origen para otros tipos de archivos compatibles.

      vínculo de detección automática

    • También puedes ingresar la información del esquema de forma manual, como se indica a continuación:

      • Haz clic en Editar como texto (Edit as text) y, luego, ingresa el esquema de la tabla como un arreglo de JSON:

        Agregar un esquema como arreglo de JSON

      • Usa la opción Agregar campo (Add Field) para ingresar el esquema de forma manual:

        Incorporar un esquema mediante agregar campos

  6. Selecciona los elementos aplicables en la sección Opciones y haz clic en Crear tabla. Si deseas obtener información sobre las opciones disponibles, consulta Opciones de CSV y Opciones de JSON.

CLI

Usa el comando bq load, especifica el source_format y, luego, incluye la ruta de acceso al archivo local.

Proporciona el marcador --location y configura el valor como tu ubicación (opcional).

Si quieres cargar datos en un proyecto que no es el predeterminado, agrega el ID del proyecto al conjunto de datos con el siguiente formato: project_id:dataset.

bq --location=location load \
--source_format=format \
project_id:dataset.table \
path_to_source \
schema

Donde:

  • location es tu ubicación. El marcador --location es opcional. Por ejemplo, si usas BigQuery en la región de Tokio, configura el valor del marcador como asia-northeast1. Puedes configurar un valor predeterminado para la ubicación con el archivo .bigqueryrc.
  • format es CSV, AVRO, PARQUET, ORC o NEWLINE_DELIMITED_JSON.
  • project_id es el ID del proyecto.
  • dataset es un conjunto de datos existente.
  • table es el nombre de la tabla en la que cargas los datos.
  • path_to_source es la ruta de acceso al archivo local.
  • 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 el marcador --autodetect en lugar de proporcionar una definición de esquema.

Además, puedes agregar marcas para opciones que te permiten controlar cómo BigQuery analiza tus datos. Por ejemplo, puedes utilizar la marca --skip_leading_rows a fin de ignorar filas de encabezados en un archivo CSV. Si deseas obtener más información, consulta Opciones de CSV y Opciones de JSON.

Ejemplos:

El siguiente comando carga un archivo JSON delimitado por saltos de línea (mydata.json) desde tu máquina local a una tabla denominada mytable en mydataset en el proyecto predeterminado. El esquema se define en un archivo de esquema local denominado myschema.json.

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

El siguiente comando carga un archivo CSV (mydata.csv) desde tu máquina local a una tabla denominada mytable en mydataset en myotherproject. El esquema se define intercalado en el formato field:data_type, field:data_type.

    bq load \
    --source_format=CSV \
    myotherproject:mydataset.mytable \
    ./mydata.csv \
    qtr:STRING,sales:FLOAT,year:STRING

El siguiente comando carga un archivo CSV (mydata.csv) desde tu máquina local a una tabla denominada mytable en mydataset en el proyecto predeterminado. El esquema se define mediante la detección automática de esquemas.

    bq load \
    --autodetect \
    --source_format=CSV \
    mydataset.mytable \
    ./mydata.csv

C#

Antes de probar esta muestra, sigue las instrucciones de configuración para C# que se encuentran en la Guía de inicio rápido de BigQuery con bibliotecas cliente. Si deseas obtener más información, consulta la Documentación de referencia de la API de C# de BigQuery.

El siguiente código demuestra cómo cargar un archivo CSV local en una tabla de BigQuery nueva. Si deseas cargar un archivo local con otro formato, usa la clase de opciones de actualización para el formato adecuado desde la clase de base JobCreationOptions en vez de UploadCsvOptions.


using Google.Cloud.BigQuery.V2;
using System;
using System.IO;

public class BigQueryLoadFromFile
{
    public void LoadFromFile(
        string projectId = "your-project-id",
        string datasetId = "your_dataset_id",
        string tableId = "your_table_id",
        string filePath = "path/to/file.csv"
    )
    {
        BigQueryClient client = BigQueryClient.Create(projectId);
        // Create job configuration
        var uploadCsvOptions = new UploadCsvOptions()
        {
            SkipLeadingRows = 1,  // Skips the file headers
            Autodetect = true
        };
        using (FileStream stream = File.Open(filePath, FileMode.Open))
        {
            // Create and run job
            // Note that there are methods available for formats other than CSV
            BigQueryJob job = client.UploadCsv(
                datasetId, tableId, null, stream, uploadCsvOptions);
            job.PollUntilCompleted();  // Waits for the job to complete.
            // Display the number of rows uploaded
            BigQueryTable table = client.GetTable(datasetId, tableId);
            Console.WriteLine(
                $"Loaded {table.Resource.NumRows} rows to {table.FullyQualifiedId}");
        }
    }
}

Go

Antes de probar este ejemplo, sigue las instrucciones de configuración de Go incluidas en la Guía de inicio rápido de BigQuery con bibliotecas cliente. Si deseas obtener más información, consulta la Documentación de referencia de la API de Go de BigQuery.

El siguiente código demuestra cómo cargar un archivo CSV local en una tabla de BigQuery nueva. Para cargar un archivo local con otro formato, configura la propiedad DataFormat de NewReaderSource con el formato adecuado.

// To run this sample, you will need to create (or reuse) a context and
// an instance of the bigquery client.  For example:
// import "cloud.google.com/go/bigquery"
// ctx := context.Background()
// client, err := bigquery.NewClient(ctx, "your-project-id")
f, err := os.Open(filename)
if err != nil {
	return err
}
source := bigquery.NewReaderSource(f)
source.AutoDetect = true   // Allow BigQuery to determine schema.
source.SkipLeadingRows = 1 // CSV has a single header line.

loader := client.Dataset(datasetID).Table(tableID).LoaderFrom(source)

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

Java

Antes de probar este ejemplo, sigue las instrucciones de configuración de Java incluidas en la Guía de inicio rápido de BigQuery con bibliotecas cliente. Si deseas obtener más información, consulta la Documentación de referencia de la API de Java de BigQuery.

El siguiente código demuestra cómo cargar un archivo CSV local en una tabla de BigQuery nueva. Para cargar un archivo local con otro formato, configura la propiedad FormatOptions con el formato adecuado.

TableId tableId = TableId.of(datasetName, tableName);
WriteChannelConfiguration writeChannelConfiguration =
    WriteChannelConfiguration.newBuilder(tableId).setFormatOptions(FormatOptions.csv()).build();
// The location must be specified; other fields can be auto-detected.
JobId jobId = JobId.newBuilder().setLocation(location).build();
TableDataWriteChannel writer = bigquery.writer(jobId, writeChannelConfiguration);
// Write data to writer
try (OutputStream stream = Channels.newOutputStream(writer)) {
  Files.copy(csvPath, stream);
}
// Get load job
Job job = writer.getJob();
job = job.waitFor();
LoadStatistics stats = job.getStatistics();
return stats.getOutputRows();

Node.js

Antes de probar esta muestra, sigue las instrucciones de configuración para Node.js que se encuentran en la Guía de inicio rápido de BigQuery con bibliotecas cliente. Si deseas obtener más información, consulta la Documentación de referencia de la API de Node.js de BigQuery.

El siguiente código demuestra cómo cargar un archivo CSV local en una tabla de BigQuery nueva. Para cargar un archivo local con otro formato, configura el parámetro metadata de la función cargar con el formato adecuado.

// Imports the Google Cloud client library
const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new BigQuery();

async function loadLocalFile() {
  // Imports a local file into a table.

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const filename = '/path/to/file.csv';
  // const datasetId = 'my_dataset';
  // const tableId = 'my_table';

  // Load data from a local file into the table
  const [job] = await bigquery
    .dataset(datasetId)
    .table(tableId)
    .load(filename);

  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 esta muestra, sigue las instrucciones de configuración de PHP que se encuentran en la Guía de inicio rápido de BigQuery con bibliotecas cliente. Si deseas obtener más información, consulta la Documentación de referencia de la API de PHP de BigQuery.

El siguiente código demuestra cómo cargar un archivo CSV local en una tabla de BigQuery nueva. Para cargar un archivo local con otro formato, configura la propiedad sourceFormat con el formato adecuado.

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';
// $source     = 'The path to the CSV source file to import';

// instantiate the bigquery table service
$bigQuery = new BigQueryClient([
    'projectId' => $projectId,
]);
$dataset = $bigQuery->dataset($datasetId);
$table = $dataset->table($tableId);
// create the import job
$loadConfig = $table->load(fopen($source, 'r'))->sourceFormat('CSV');

$job = $table->runJob($loadConfig);
// poll the job until it is complete
$backoff = new ExponentialBackoff(10);
$backoff->execute(function () use ($job) {
    printf('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 de Python incluidas en la Guía de inicio rápido de BigQuery con bibliotecas cliente. Si deseas obtener más información, consulta la Documentación de referencia de la API de Python de BigQuery.

El siguiente código demuestra cómo cargar un archivo CSV local en una tabla de BigQuery nueva. Para cargar un archivo local con otro formato, configura la propiedad LoadJobConfig.source_format con el formato adecuado.

# from google.cloud import bigquery
# client = bigquery.Client()
# filename = '/path/to/file.csv'
# dataset_id = 'my_dataset'
# table_id = 'my_table'

dataset_ref = client.dataset(dataset_id)
table_ref = dataset_ref.table(table_id)
job_config = bigquery.LoadJobConfig()
job_config.source_format = bigquery.SourceFormat.CSV
job_config.skip_leading_rows = 1
job_config.autodetect = True

with open(filename, "rb") as source_file:
    job = client.load_table_from_file(source_file, table_ref, job_config=job_config)

job.result()  # Waits for table load to complete.

print("Loaded {} rows into {}:{}.".format(job.output_rows, dataset_id, table_id))

Ruby

Antes de probar esta muestra, sigue las instrucciones de configuración para Ruby que se encuentran en la Guía de inicio rápido de BigQuery con bibliotecas cliente. Si deseas obtener más información, consulta la Documentación de referencia de la API de Ruby de BigQuery.

El siguiente código demuestra cómo cargar un archivo CSV local en una tabla de BigQuery nueva. Para cargar un archivo local con otro formato, configura el parámetro format del método Table#load_job con el formato adecuado.

require "google/cloud/bigquery"

def load_from_file(dataset_id = "your_dataset_id",
                   file_path  = "path/to/file.csv")

  bigquery = Google::Cloud::Bigquery.new
  dataset  = bigquery.dataset dataset_id
  table_id = "new_table_id"

  # Infer the config.location based on the location of the referenced dataset.
  load_job = dataset.load_job table_id, file_path do |config|
    config.skip_leading = 1
    config.autodetect   = true
  end
  load_job.wait_until_done! # Waits for table load to complete.

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

Cómo agregar o reemplazar una tabla con un archivo local

Puedes cargar datos adicionales en una tabla desde los archivos de origen o mediante la incorporación de resultados de consulta. Si el esquema de los datos no coincide con el esquema de la tabla o partición de destino, puedes actualizar el esquema cuando agregues o reemplaces los datos.

Si actualizas el esquema cuando agregas datos, BigQuery te permitirá realizar las siguientes acciones:

  • Agregar campos nuevos
  • Cambiar los campos REQUIRED por NULLABLE

Si reemplazas una tabla, el esquema siempre se reemplaza. Las actualizaciones de esquema no están restringidas cuando reemplazas una tabla.

En la consola y en la IU web clásica de BigQuery, usa la opción de Write preference (Preferencia de escritura) para especificar qué acción realizar cuando cargues datos desde un archivo de origen o desde un resultado de consulta. La CLI y la API incluyen las siguientes opciones:

Opción de Console Opción de la IU clásica Marcador CLI Propiedad de la API de BigQuery Descripción
Escribir si está vacía Escribir si está vacía Ninguno WRITE_EMPTY Solo escribe los datos si la tabla está vacía.
Agregar a la tabla Agregar a la tabla --noreplace o --replace=false; si --replace no se especifica, la opción predeterminada es agregar WRITE_APPEND (Predeterminado) Adjunta los datos al final de la tabla.
Reemplazar tabla Reemplazar tabla --replace o --replace=true WRITE_TRUNCATE Borra todos los datos existentes en una tabla antes de escribir los datos nuevos.

Para cargar datos de CSV, JSON, Avro, ORC o Parquet desde un archivo local, y para agregar o reemplazar una tabla de BigQuery, sigue estos pasos:

Console

  1. Abre la IU web de BigQuery en GCP Console.
    Ir a GCP Console

  2. En el panel de navegación, en la sección Recursos, expande tu proyecto y selecciona un conjunto de datos.

  3. En el lado derecho de la ventana, en el panel de detalles, haz clic en Crear tabla (Create table). El proceso de carga de datos es el mismo que el que se usa para crear una tabla vacía.

    Crear tabla

  4. En la página Crear tabla (Create table), en la sección Origen (Source) haz lo siguiente:

    • Para Crear tabla desde (Create table from), selecciona Subir (Upload).

      Subir tabla

    • En Seleccionar archivo (Select file), haz clic en Navegar (Browse).

      Explorar archivos

    • Busca el archivo y haz clic en Abrir (Open). Ten en cuenta que los comodines y las listas separadas por comas no son compatibles con archivos locales.

    • Para el Formato del archivo, selecciona CSV, JSON (delimitado por saltos de línea), Avro, ORC o Parquet.

  5. En la página Crear tabla (Create table), en la sección Destino (Destination) haz lo siguiente:

    • En Nombre del conjunto de datos (Dataset name), selecciona el conjunto de datos que corresponda.

      Seleccionar conjunto de datos

    • En el campo Nombre de tabla, ingresa el nombre de la tabla que quieres crear en BigQuery.

    • Verifica que Tipo de tabla (Table type) esté configurado como Tabla nativa (Native table).

  6. En la sección Esquema, ingresa la definición del esquema.

    • Para los archivos CSV y JSON, puedes marcar la opción Detección automática a fin de habilitar la detección automática del esquema. La información del esquema se describe en sí en los datos de origen para otros tipos de archivos compatibles.

    • También puedes ingresar la información del esquema de forma manual, como se indica a continuación:

      • Haz clic en Editar como texto y, luego, ingresa el esquema de la tabla como un arreglo de JSON:

      • Usa la opción Agregar campo para ingresar el esquema de forma manual.

  7. En la sección Opciones avanzadas, en Preferencia de escritura, selecciona Escribir si está vacía, Agregar a la tabla o Reemplazar tabla.

  8. Haz clic en Crear tabla.

IU clásica

  1. En la página Crear tabla (Create Table), en la sección Datos de origen (Source Data), realiza lo siguiente:
    • Para Ubicación, selecciona Carga de archivos, haz clic en Seleccionar archivo, busca el archivo y, a continuación, haz clic en Abrir. Ten en cuenta que los comodines y las listas separadas por comas no son compatibles con archivos locales.
    • Para Formato de archivo, selecciona (CSV), JSON (delimitado por saltos de línea), Avro, ORC o Parquet.
  2. En la página Crear tabla, en la sección Tabla de destino (Destination Table), realiza los siguientes pasos:
    • En Nombre de la tabla (Table name), selecciona el conjunto de datos que corresponda y, en el campo de nombre de tabla, ingresa el nombre de la tabla que quieres agregar o reemplazar.
    • Verifica que Tipo de tabla (Table type) esté configurado como Tabla nativa (Native table).
  3. En la sección Esquema (Schema), ingresa la definición del esquema. Para actualizar el esquema, puedes agregar campos nuevos o cambiar (disminuir) campos de REQUIRED a NULLABLE.

    • Para los archivos JSON, puedes marcar la opción Detección automática a fin de habilitar la detección automática del esquema.

      vínculo de detección automática

    • También puedes ingresar la información del esquema de forma manual, como se indica a continuación:

      • Haz clic en Editar como texto (Edit as text) y, luego, ingresa el esquema de la tabla como un arreglo de JSON:

        Agregar un esquema como arreglo de JSON

      • Usa la opción Agregar campo (Add Field) para ingresar el esquema de forma manual:

        Agregar esquema con agregar campos

  4. En la sección Opciones (Options), en Preferencia de escritura (Write preference), selecciona Escribir si está vacía (Write if empty), Agregar a la tabla (Append to table) o Reemplazar tabla (Overwrite table).

    Incorporar un esquema mediante agregar campos

  5. Haz clic en Crear tabla (Create Table).

CLI

Ingresa el comando bq load con el marcador --replace para reemplazar la tabla. Usa el marcador --noreplace para agregar datos a la tabla. Si no se especifica ningún marcador, se agregan datos de manera predeterminada.

Proporciona el marcador --location y configura el valor como tu ubicación (opcional).

Cuando agregas o reemplazas una tabla, puedes usar el marcador --schema_update_option para actualizar el esquema de la tabla de destino como el esquema de los datos nuevos. Se pueden usar las siguientes opciones con el marcador --schema_update_option:

  • ALLOW_FIELD_ADDITION: agrega campos nuevos al esquema. Los campos nuevos no pueden ser REQUIRED.
  • ALLOW_FIELD_RELAXATION: cambia los campos obligatorios a nulos. Repite esta opción para especificar una lista de valores.
bq --location=location load \
--[no]replace \
dataset.table \
path_to_source \
schema

Donde:

  • location es tu ubicación. El marcador --location es opcional. Por ejemplo, si usas BigQuery en la región de Tokio, configura el valor del marcador como asia-northeast1. Puedes configurar un valor predeterminado para la ubicación con el archivo .bigqueryrc.
  • dataset es un conjunto de datos existente.
  • table es el nombre de la tabla en la que cargas los datos.
  • path_to_source es la ruta de acceso al archivo local. Ten en cuenta que los comodines y las listas separadas por comas no son compatibles con archivos locales.
  • 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 el marcador --autodetect en lugar de proporcionar una definición de esquema.

Además, puedes agregar marcadores para las opciones JSON y opciones CSV que te permiten controlar cómo BigQuery analiza tus datos.

Ejemplos:

El siguiente comando carga datos desde mydata.json y reemplaza una tabla denominada 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 \
    ./mydata.json

El siguiente comando carga datos desde mydata.json y agrega los datos a una tabla denominada mytable en mydataset. El esquema se define mediante un archivo de esquema JSON: myschema.json.

    bq load \
    --autodetect \
    --noreplace \
    --source_format=NEWLINE_DELIMITED_JSON \
    mydataset.mytable \
    ./mydata.json \
    ./myschema.json

El siguiente comando carga datos desde mydata.json y agrega los datos a una tabla denominada mytable en mydataset. Se usa un archivo de esquema JSON local denominado myschema.json. La definición del esquema contiene campos nuevos que no están presentes en la tabla de destino.

    bq load \
    --noreplace \
    --schema_update_option=ALLOW_FIELD_ADDITION \
    --source_format=NEWLINE_DELIMITED_JSON \
    mydataset.mytable \
    ./mydata.json \
    ./myschema.json

El siguiente comando carga datos desde mydata.csv y agrega los datos a una tabla denominada mytable en mydataset. Se usa un archivo de esquema JSON local denominado myschema.json. La definición del esquema cambia (disminuye) dos campos REQUIRED a NULLABLE.

    bq load \
    --noreplace \
    --schema_update_option=ALLOW_FIELD_RELAXATION \
    --source_format=NEWLINE_DELIMITED_JSON \
    mydataset.mytable \
    ./mydata.csv \
    ./myschema.json

Cargas de la API

La función de carga de medios permite que la API de BigQuery guarde los datos en la nube y los ponga a disposición del servidor. Entre los tipos de datos que uno podría querer subir se incluyen fotos, videos, archivos PDF, archivos ZIP o cualquier otro tipo de datos.

Opciones de carga

La API de BigQuery te permite subir ciertos tipos de datos binarios o medios. Las características específicas de los datos que puedes subir se describen en la página de referencia de cualquier método compatible con cargas de medios:

  • Tamaño máximo de carga de archivos: La cantidad máxima de datos que puedes almacenar con este método.
  • Tipos de MIME de medios aceptados: Los tipos de datos binarios que puedes almacenar con este método.

Puedes realizar solicitudes de carga de cualquiera de las siguientes formas. Especifica el método que estás usando con el parámetro de solicitud uploadType.

  • Carga multiparte: uploadType=multipart. Para una transferencia rápida de archivos pequeños y metadatos, transfiere el archivo con los metadatos que lo describen, en una única solicitud.
  • Carga reanudable: uploadType=resumable. Para una transferencia confiable, especialmente importante para archivos más grandes. Con este método, utilizas una solicitud de inicio de sesión, que puede incluir metadatos. Esta es una buena estrategia para la mayoría de las aplicaciones, ya que también funciona para archivos más pequeños al costo de una solicitud HTTP adicional por carga.

Cuando cargas medios, utilizas un URI específico. De hecho, los métodos compatibles con cargas de medios tienen dos extremos de URI:

  • El URI /upload, para los medios. El formato del extremo de carga es el URI de recurso estándar con el prefijo "/upload". Usa este URI cuando transfieras los datos de los medios. Por ejemplo: POST /upload/bigquery/v2/projects/projectId/jobs.
  • El URI de recurso estándar, para los metadatos. Si el recurso contiene campos de datos, esos campos se utilizan para almacenar metadatos que describen el archivo cargado. Puedes usar este URI cuando creas o actualizas valores de metadatos. Por ejemplo: POST /bigquery/v2/projects/projectId/jobs.

Carga multiparte

Si tienes metadatos que deseas enviar junto con los datos que vas a cargar, puedes realizar una solicitud única multipart/related. Esta es una buena opción si los datos que vas a enviar son lo suficientemente pequeños para volver a cargarlos en su totalidad si la conexión falla.

Para usar la carga multiparte, realiza una solicitud POST al URI /upload del método y agrega el parámetro de consulta uploadType=multipart, por ejemplo:

POST https://www.googleapis.com/upload/bigquery/v2/projects/projectId/jobs?uploadType=multipart

Entre los encabezados HTTP de nivel superior que se deben usar cuando se realiza una solicitud de carga, se incluyen los siguientes:

  • Content-Type. Configurado como multiparte/relacionado; incluye la string de límite que estás utilizando para identificar las partes de la solicitud.
  • Content-Length. Configurado como la cantidad total de bytes en el cuerpo de la solicitud. La parte de medios de la solicitud debe ser menor que el tamaño máximo del archivo especificado para este método.

El cuerpo de la solicitud tiene el formato de un tipo de contenido multipart/related [RFC2387] y contiene exactamente dos partes. Las partes se identifican mediante una string de límite, y la string de límite final está seguida por dos guiones.

Cada parte de la solicitud multiparte necesita un encabezado Content-Type adicional:

  1. Parte de metadatos: debe ir primero y Content-Type debe coincidir con uno de los formatos de metadatos aceptados.
  2. Parte de medios: debe ir segundo y Content-Type debe coincidir con uno de los tipos MIME de medios aceptados del método.

Consulta la referencia de la API para conocer la lista de tipos MIME de medios aceptados del método y los límites de tamaño de los archivos subidos.

Nota: Para crear o actualizar solo la parte de metadatos, sin subir los datos relacionados, envía una solicitud POST o PUT al extremo de recurso estándar: https://www.googleapis.com/bigquery/v2/projects/projectId/jobs

Ejemplo: carga multiparte

En el ejemplo que aparece a continuación, se muestra una solicitud de carga multiparte para la API de BigQuery.

POST /upload/bigquery/v2/projects/projectId/jobs?uploadType=multipart HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer your_auth_token
Content-Type: multipart/related; boundary=foo_bar_baz
Content-Length: number_of_bytes_in_entire_request_body

--foo_bar_baz
Content-Type: application/json; charset=UTF-8

{
  "configuration": {
    "load": {
      "sourceFormat": "NEWLINE_DELIMITED_JSON",
      "schema": {
        "fields": [
          {"name": "f1", "type": "STRING"},
          {"name": "f2", "type": "INTEGER"}
        ]
      },
      "destinationTable": {
        "projectId": "projectId",
        "datasetId": "datasetId",
        "tableId": "tableId"
      }
    }
  }
}

--foo_bar_baz
Content-Type: */*

CSV, JSON, AVRO, PARQUET, or ORC data
--foo_bar_baz--

Si la solicitud se realiza correctamente, el servidor muestra el código de estado HTTP 200 OK junto con los metadatos:

HTTP/1.1 200
Content-Type: application/json

{
  "configuration": {
    "load": {
      "sourceFormat": "NEWLINE_DELIMITED_JSON",
      "schema": {
        "fields": [
          {"name": "f1", "type": "STRING"},
          {"name": "f2", "type": "INTEGER"}
        ]
      },
      "destinationTable": {
        "projectId": "projectId",
        "datasetId": "datasetId",
        "tableId": "tableId"
      }
    }
  }
}

Carga reanudable

Para cargar archivos de datos de manera más confiable, puedes utilizar el protocolo de carga reanudable. Este protocolo te permite reanudar una operación de carga luego de que una falla de comunicación haya interrumpido el flujo de datos. Es especialmente útil si estás transfiriendo archivos grandes y cuando la probabilidad de una interrupción en la red o algún otro problema con la transmisión es alta; por ejemplo, cuando realizas la carga desde una aplicación cliente móvil. Además, puede reducir el uso de ancho de banda en caso de fallas en la red, ya que no necesitas reiniciar las cargas de archivos grandes desde el comienzo.

Entre los pasos para utilizar cargas reanudables se incluyen los siguientes:

  1. Inicia una sesión reanudable. Realiza una solicitud inicial al URI de carga que incluya los metadatos, si corresponde.
  2. Guarda el URI de la sesión reanudable. Guarda el URI de la sesión que se muestra en la respuesta de la solicitud inicial; lo utilizarás para las solicitudes restantes en esta sesión.
  3. Carga el archivo. Envía el archivo de medios al URI de la sesión reanudable.

Además, las aplicaciones que usan carga reanudable deben tener un código para reanudar una carga interrumpida. Si se interrumpe una carga, averigua cuántos datos se recibieron correctamente y, a continuación, reanuda la carga desde ese punto.

Nota: Un URI de carga expira después de una semana.

Paso 1: Iniciar una sesión reanudable

Para iniciar una carga reanudable, realiza una solicitud POST al URI /upload del método y agrega el parámetro de consulta uploadType=resumable, por ejemplo:

POST https://www.googleapis.com/upload/bigquery/v2/projects/projectId/jobs?uploadType=resumable

Para esta solicitud de inicio, el cuerpo está vacío o contiene solamente los metadatos; transferirás el contenido real del archivo que deseas cargar en solicitudes posteriores.

Utiliza los siguientes encabezados HTTP con la solicitud inicial:

  • X-Upload-Content-Type. Configurado como el tipo MIME de medios de los datos de carga que se transferirán en solicitudes posteriores.
  • X-Upload-Content-Length. Configurado como la cantidad de bytes de datos de carga que se transferirán en solicitudes posteriores.  Si no se conoce la longitud en el momento de esta solicitud, puedes omitir este encabezado.
  • Si se proporcionan metadatos: Content-Type. Configurado de acuerdo con el tipo de datos de los metadatos.
  • Content-Length. Configurado como la cantidad de byte proporcionados en el cuerpo de esta solicitud inicial. No se necesita si estás utilizando codificación de transferencia fragmentada.

Consulta la referencia de la API para conocer la lista de tipos MIME de medios aceptados del método y los límites de tamaño de los archivos subidos.

Ejemplo: solicitud de inicio de sesión reanudable

En el siguiente ejemplo, se muestra cómo iniciar una sesión reanudable para la API de BigQuery.

POST /upload/bigquery/v2/projects/projectId/jobs?uploadType=resumable HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer your_auth_token
Content-Length: 38
Content-Type: application/json; charset=UTF-8
X-Upload-Content-Type: */*
X-Upload-Content-Length: 2000000

{
  "configuration": {
    "load": {
      "sourceFormat": "NEWLINE_DELIMITED_JSON",
      "schema": {
        "fields": [
          {"name": "f1", "type": "STRING"},
          {"name": "f2", "type": "INTEGER"}
        ]
      },
      "destinationTable": {
        "projectId": "projectId",
        "datasetId": "datasetId",
        "tableId": "tableId"
      }
    }
  }
}

Nota: En una solicitud de actualización inicial reanudable sin metadatos, deja el cuerpo de la solicitud vacío y configura el encabezado Content-Length como 0.

En la próxima sección, se describe cómo manejar la respuesta.

Paso 2: Guardar el URI de la sesión reanudable

Si la solicitud de inicio de sesión se realiza correctamente, el servidor de la API responde con un código de estado HTTP 200 OK. Además, proporciona un encabezado Location que especifica el URI de la sesión reanudable. El encabezado Location, que se muestra a continuación, incluye una parte del parámetro de consulta upload_id que proporciona el ID de carga único que se debe utilizar en esta sesión.

Ejemplo: Respuesta de inicio de sesión reanudable

A continuación, se muestra la respuesta a la solicitud presentada en el paso 1:

HTTP/1.1 200 OK
Location: https://www.googleapis.com/upload/bigquery/v2/projects/projectId/jobs?uploadType=resumable&upload_id=xa298sd_sdlkj2
Content-Length: 0

El valor del encabezado Location, como se muestra en la respuesta de ejemplo anterior, es el URI de la sesión que utilizarás como el extremo HTTP para realizar la carga de archivos o para consultar el estado de la carga.

Copia y guarda el URI de la sesión para poder utilizarlo en solicitudes posteriores.

Paso 3: Cargar el archivo

Para cargar el archivo, envía una solicitud PUT al URI de carga que obtuviste en el paso anterior. El formato de la solicitud de carga es el siguiente:

PUT session_uri

Los encabezados HTTP que se deben utilizar cuando realizas solicitudes de carga de archivos reanudables incluyen Content-Length. Configura la cantidad de bytes que estás cargando en esta solicitud, que, por lo general, es el tamaño del archivo que se carga.

Ejemplo: Solicitud de carga de archivo reanudable

Esta es una solicitud reanudable para cargar el archivo CSV, JSON, AVRO, ORC o PARQUET de 2,000,000 bytes para el ejemplo actual.

PUT https://www.googleapis.com/upload/bigquery/v2/projects/projectId/jobs?uploadType=resumable&upload_id=xa298sd_sdlkj2 HTTP/1.1
Content-Length: 2000000
Content-Type: */*

bytes 0-1999999

Si la solicitud se realiza correctamente, el servidor responde con un HTTP 201 Created, junto con todos los metadatos asociados con este recurso. Si la solicitud inicial de la sesión reanudable hubiera sido PUT, para actualizar un recurso existente, la respuesta de que se realizó correctamente sería 200 OK, junto con todos los metadatos asociados con este recurso.

Si se interrumpe la solicitud de carga o si recibes una respuesta HTTP 503 Service Unavailable o cualquier otro tipo de respuesta 5xx de parte del servidor, sigue el procedimiento que se describe en la documentación sobre cómo reanudar una carga interrumpida.  


Cargar el archivo en partes

Con las cargas reanudables, puedes separar un archivo en partes y enviar diferentes solicitudes para cargar cada parte en secuencia. Este no es el enfoque predilecto, ya que tiene costos de rendimiento asociados con las solicitudes adicionales y, generalmente, no es necesario. Sin embargo, es posible que necesites utilizar la separación en partes para reducir la cantidad de datos que se transfieren en una sola solicitud. Esto es útil en caso de que haya un límite de tiempo fijo para las solicitudes individuales, como ocurre con ciertas clases de solicitudes de Google App Engine. Además, te permite realizar acciones como proporcionar indicaciones de progreso de carga para los navegadores heredados que no tienen asistencia de progreso de carga en la configuración predeterminada.


Reanudar una carga interrumpida

Si una solicitud de carga se finaliza antes de recibir una respuesta o si recibes una respuesta 503 Service Unavailable HTTP del servidor, deberás reanudar la carga interrumpida. Para ello, sigue estos pasos:

  1. Estado de la solicitud. Consulta el estado actual de la carga; para ello, emite una solicitud PUT vacía al URI de carga. Para esta solicitud, los encabezados HTTP deberían incluir un encabezado Content-Range en el que se indique que no se conoce la posición actual en el archivo.  Por ejemplo, establece Content-Range como */2000000 si la longitud total del archivo es 2,000,000. Si no sabes la longitud total del archivo, configura Content-Range como */*.

    Nota: Puedes solicitar el estado entre partes, no solamente si se interrumpe la carga. Eso es útil, por ejemplo, si deseas mostrar indicaciones de progreso de carga para los navegadores heredados.

  2. Obtén la cantidad de bytes cargados. Procesa la respuesta de la consulta de estado. El servidor utiliza el encabezado Range en su respuesta para especificar qué bytes recibió hasta el momento.  Por ejemplo, un encabezado Range de 0-299999 indica que los primeros 300,000 bytes del archivo ya se recibieron.
  3. Carga los datos restantes. Finalmente, ahora que sabes dónde reanudar la solicitud, envía los datos restantes o la parte actual. Ten en cuenta que debes tratar los datos restantes como una parte separada en ambos casos, por lo que debes enviar el encabezado Content-Range cuando reanudas la carga.
Ejemplo: Reanuda una carga interrumpida

1) Solicita el estado de la carga.

La siguiente solicitud utiliza el encabezado Content-Range para indicar que la posición actual en el archivo de 2,000,000 bytes es desconocida.

PUT {session_uri} HTTP/1.1
Content-Length: 0
Content-Range: bytes */2000000

2) Extrae de la respuesta la cantidad de bytes cargados hasta el momento.

La respuesta del servidor utiliza el encabezado Range para indicar que recibió los primeros 43 bytes del archivo hasta el momento. Utiliza el valor superior del encabezado Range a fin de determinar dónde comenzar la carga reanundada.

HTTP/1.1 308 Resume Incomplete
Content-Length: 0
Range: 0-42

Nota: Es posible que la respuesta de estado sea 201 Created o 200 OK si ya se completó la carga. Esto podría suceder si la conexión falló después de que se hayan cargado todos los bytes, pero antes de que el cliente haya recibido una respuesta del servidor.

3) Reanuda la carga desde el punto en que se detuvo.

La siguiente solicitud reanuda la carga; para ello, envía los bytes restantes del archivo a partir del byte 43.

PUT {session_uri} HTTP/1.1
Content-Length: 1999957
Content-Range: bytes 43-1999999/2000000

bytes 43-1999999

Recomendaciones

Cuando cargues medios, es útil conocer algunas de las recomendaciones relacionadas con el manejo de errores:

  • Reanuda o vuelve a intentar cargas que no se realizaron correctamente debido a interrupciones en la conexión o cualquier error 5xx, entre los que se incluyen los siguientes:
    • 500 Internal Server Error
    • 502 Bad Gateway
    • 503 Service Unavailable
    • 504 Gateway Timeout
  • Usa una estrategia de retirada exponencial si se muestra cualquier error del servidor 5xx cuando reanudas o vuelves a intentar las solicitudes de carga. Estos errores pueden ocurrir si un servidor se está sobrecargando. La retirada exponencial puede ayudarte a aliviar este tipo de problemas durante períodos de gran volumen de solicitudes o de tráfico de red intenso.
  • No deben manejarse otros tipos de solicitudes mediante retirada exponencial, pero igual puedes reintentar varias de ellas. Cuando reintentes estas solicitudes, limita la cantidad de veces que lo haces. Por ejemplo, tu código podría limitarse a diez reintentos o menos antes de informar un error.
  • Maneja los errores 404 Not Found cuando realices cargas reanudables; para ello, vuelve a iniciar toda la carga desde el comienzo.

Retirada exponencial

La retirada exponencial es una estrategia estándar de manejo de errores para aplicaciones de red en las que el cliente reintenta periódicamente una solicitud con errores durante un período creciente. Si el servidor presenta errores debido a un gran volumen de solicitudes o tráfico de red, la retirada exponencial podría ser una buena estrategia para manejar estos errores. Por el contrario, no es una estrategia recomendada para lidiar con errores que no estén relacionados con el volumen de la red o los tiempos de espera, como credenciales de autorización no válidas o errores de archivos no encontrados.

Si se la utiliza de forma correcta, la retirada exponencial aumenta la eficiencia del uso del ancho de banda, reduce la cantidad de solicitudes que se requieren para obtener una respuesta correcta y maximiza el rendimiento de las solicitudes en entornos simultáneos.

A continuación, se muestra el flujo para implementar una retirada exponencial simple:

  1. Realizar una solicitud a la API.
  2. Recibir una respuesta HTTP 503, lo que indica que debes reintentar la solicitud.
  3. Esperar 1 segundo + random_number_milliseconds y reintentar la solicitud.
  4. Recibir una respuesta HTTP 503, lo que indica que debes reintentar la solicitud.
  5. Esperar 2 segundos + random_number_milliseconds y reintentar la solicitud.
  6. Recibir una respuesta HTTP 503, lo que indica que debes reintentar la solicitud.
  7. Esperar 4 segundos + random_number_milliseconds y reintentar la solicitud.
  8. Recibir una respuesta HTTP 503, lo que indica que debes reintentar la solicitud.
  9. Esperar 8 segundos + random_number_milliseconds y reintentar la solicitud.
  10. Recibir una respuesta HTTP 503, lo que indica que debes reintentar la solicitud.
  11. Esperar 16 segundos + random_number_milliseconds y reintentar la solicitud.
  12. Detenerse. Informar o registrar un error.

En el flujo anterior, random_number_milliseconds es una cantidad aleatoria de milisegundos menor o igual que 1,000. Esta es necesaria, ya que agregar un pequeño retraso aleatorio ayuda a distribuir la carga de manera más uniforme y a evitar la posibilidad de marcar el servidor. El valor de random_number_milliseconds se debe volver a definir tras cada espera.

Nota: La espera siempre es (2 ^ n) + random_number_milliseconds, en que n es un número entero, que crece de forma monotónica, inicialmente definido como 0. El número entero n aumenta de a 1 por cada iteración (cada solicitud).

El algoritmo está configurado para terminar cuando n es 5. El límite impide que los clientes vuelvan a intentar solicitudes de forma infinita y genera un retraso total de aproximadamente 32 segundos antes de que una solicitud se considere “un error irrecuperable”. Un número máximo de reintentos es aceptable, sobre todo si se realiza una carga larga. Solo asegúrate de limitar el retraso de reintentos en un valor razonable, por ejemplo, menos de un minuto.

¿Te sirvió esta página? Envíanos tu opinión:

Enviar comentarios sobre…

¿Necesitas ayuda? Visita nuestra página de asistencia.