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:

Resumen

Puedes cargar datos desde una fuente de datos legible (como tu máquina local) mediante una de las siguientes opciones:

  • Cloud Console o la IU web clásica de BigQuery
  • El comando bq load de la herramienta de línea de comandos de bq
  • La API
  • Las bibliotecas cliente

Cuando cargas datos mediante Cloud Console, la IU web clásica de BigQuery o la interfaz de línea de comandos, se crea un trabajo de carga de forma automática.

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 para reemplazar los datos de una tabla o adjuntar datos nuevos
  • 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 bigquery.jobs.create:

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

Además, si un usuario tiene permisos bigquery.datasets.create, se le otorga el acceso bigquery.dataOwner cuando crea un conjunto de datos. El acceso bigquery.dataOwner le da al usuario la capacidad de cargar datos a tablas dentro del conjunto de datos.

Si deseas obtener más información sobre las funciones de Cloud IAM y los permisos en BigQuery, consulta la sección sobre el control de acceso.

Carga datos de 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 Cloud Console.
    Ir a Cloud Console

  2. En el panel de navegación, en la sección Recursos, expande tu proyecto de Google Cloud 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 proceso para crear una tabla vacía.

    Crear tabla.

  4. En la sección Fuente (Source) de la página Crear tabla (Create table), 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. Ten en cuenta que los comodines y las listas separadas por comas no son compatibles con archivos locales.

    • En Formato de archivo (File format), selecciona CSV, JSON (delimitado por saltos de línea) (JSON [newline delimited]), 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 la tabla, ingresa el nombre de la tabla que quieres crear en BigQuery.

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

  6. 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 (Automatically detect) a fin de habilitar la detección automática del esquema. La información del esquema se describe de forma automática 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 e ingresa el esquema de la tabla como un arreglo 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 (Advanced options) y haz clic en Crear tabla (Create Table). Si deseas obtener información sobre las opciones disponibles, consulta las opciones de CSV y las 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, coloca el cursor sobre un conjunto de datos, haz clic en el ícono de flecha hacia abajo Ícono de flecha hacia abajo. y en Crear tabla nueva. El proceso de carga de datos es el mismo que el proceso para crear una tabla vacía.

  3. En la página Crear tabla (Create Table), en la sección Datos de origen (Source Data):

    • Para Ubicación (Location), selecciona Carga de archivos (File upload), haz clic en Seleccionar archivo (Choose file), busca el archivo y, a continuación, haz clic en Abrir (Open). Ten en cuenta que los comodines y las listas separadas por comas no son compatibles con archivos locales.
    • En Formato de archivo (File format), selecciona (CSV), JSON (delimitado por saltos de línea) (JSON [newline delimited]), Avro, ORC o Parquet.
  4. En la página Crear tabla (Create Table), 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 la tabla, ingresa el nombre de la tabla que quieres crear en BigQuery.
    • Verifica que Tipo de tabla (Table type) esté establecido en 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 (Automatically detect) a fin de habilitar la detección automática del esquema. La información del esquema se describe de forma automática 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 e ingresa el esquema de la tabla como un arreglo JSON:

        Agregar esquema como arreglo JSON.

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

        Agregar esquema con el botón Agregar campo.

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

bq

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

Proporciona la marca --location y establece el valor de tu ubicación (opcional).

Para cargar datos a un proyecto que no sea el predeterminado, agrega el ID del proyecto al conjunto de datos en el siguiente formato: PROJECT_ID:DATASET.

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

Reemplaza los siguientes elementos:

  • LOCATION: Es tu ubicación. La marca --location es opcional. Por ejemplo, si usas BigQuery en la región de Tokio, establece el valor de la marca en 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 se están cargando los datos.
  • path_to_source: Es la ruta del 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 la marca --autodetect en lugar de proporcionar una definición de esquema.

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

Ejemplos:

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

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

Con el siguiente comando, se carga un archivo CSV (mydata.csv) desde tu máquina local hacia una tabla llamada mytable en mydataset dentro de 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

Con el siguiente comando, se carga un archivo CSV (mydata.csv) desde tu máquina local hacia una tabla llamada mytable en mydataset dentro de tu 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 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. Si deseas obtener más información, consulta la documentación de referencia de la API de BigQuery para C#.

Con el siguiente código, se demuestra cómo cargar un archivo CSV local a 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 para Go que se encuentran en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Si deseas obtener más información, consulta la documentación de referencia de la API de BigQuery para Go.

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

import (
	"context"
	"fmt"
	"os"

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

// importCSVFromFile demonstrates loading data into a BigQuery table using a file on the local filesystem.
func importCSVFromFile(projectID, datasetID, tableID, filename 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()

	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
	}
	return nil
}

Java

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

Con el siguiente código, se demuestra cómo cargar un archivo CSV local a 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 este ejemplo, sigue las instrucciones de configuración para Node.js que se encuentran 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 Node.js de BigQuery.

Con el siguiente código, se 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 subir 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 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. Si deseas obtener más información, consulta la documentación de referencia de la API de BigQuery para PHP.

Con el siguiente código, se demuestra cómo cargar un archivo CSV local a 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 esta muestra, 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. Si deseas obtener más información, consulta la documentación de referencia de la API de BigQuery para Python.

Con el siguiente código, se demuestra cómo cargar un archivo CSV local a 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 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. A fin de obtener más información, consulta la documentación de referencia de la API de BigQuery para Ruby.

Con el siguiente código, se demuestra cómo cargar un archivo CSV local a 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 datos a una tabla o reemplazarla con un archivo local

Puedes cargar datos adicionales a 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 datos o reemplaces los existentes.

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 o en la IU web clásica de BigQuery, usa la opción de Preferencia de escritura (Write preference) para especificar qué acción se debe 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 Marca de la CLI Propiedad de la API de BigQuery Descripción
Escribir si está vacía (Write if empty) Escribir si está vacía (Write if empty) Ninguna 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 está especificado, la opción predeterminada es agregar WRITE_APPEND (Predeterminado) Adjunta los datos al final de la tabla.
Reemplaza una tabla Reemplaza una 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 reemplazar una tabla de BigQuery o agregarle datos, sigue estos pasos:

Console

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

  2. En el panel de navegación, en la sección Recursos, expande tu proyecto de Cloud 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 proceso para crear una tabla vacía.

    Crear tabla.

  4. En la sección Fuente (Source) de la página Crear tabla (Create table), 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. Ten en cuenta que los comodines y las listas separadas por comas no son compatibles con archivos locales.

    • En Formato de archivo (File format), selecciona CSV, JSON (delimitado por saltos de línea) (JSON [newline delimited]), 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 la tabla, ingresa el nombre de la tabla que quieres crear en BigQuery.

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

  6. 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 (Automatically detect) a fin de habilitar la detección automática del esquema. La información del esquema se describe de forma automática 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 e ingresa el esquema de la tabla como un arreglo JSON:

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

  7. En la sección Opciones avanzadas (Advanced 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).

  8. Haz clic en Crear tabla (Create table).

IU clásica

  1. En la página Crear tabla (Create table), en la sección Datos de origen (Source Data), sigue estos pasos:
    • Para Ubicación (Location), selecciona Carga de archivos (File upload), haz clic en Seleccionar archivo (Choose file), busca el archivo y, a continuación, haz clic en Abrir (Open). Ten en cuenta que los comodines y las listas separadas por comas no son compatibles con archivos locales.
    • En Formato de archivo (File format), selecciona (CSV), JSON (delimitado por saltos de línea) (JSON [newline delimited]), Avro, ORC o Parquet.
  2. En la página Crear tabla (Create Table), en la sección Tabla de destino (Destination table), realiza lo siguiente:
    • En Nombre de la tabla (Table name), selecciona el conjunto de datos que corresponda y, en el campo de nombre de la tabla, ingresa el nombre de la tabla a la que quieres agregar datos o reemplazar los existentes.
    • Verifica que Tipo de tabla (Table type) esté establecido en 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 (Automatically detect) a fin de habilitar la detección automática de esquemas.

      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 e ingresa el esquema de la tabla como un arreglo JSON:

        Agregar esquema como arreglo JSON.

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

        Agregar esquema con el botón Agregar campo.

  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).

    Agregar esquema con el botón Agregar campo.

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

bq

Ingresa el comando bq load con la marca --replace para reemplazar los datos de la tabla. Usa la marca --noreplace para agregar datos a la tabla. Si no se especifica ninguna marca, la configuración predeterminada es adjuntar datos.

Proporciona la marca --location y configura el valor de tu ubicación (opcional).

Cuando reemplazas los datos de una tabla o adjuntas datos nuevos, puedes usar la marca --schema_update_option para actualizar el esquema de la tabla de destino según el esquema de la tabla nueva. Las siguientes opciones se pueden usar con la marca --schema_update_option:

  • ALLOW_FIELD_ADDITION: Agrega campos nuevos al esquema. Estos campos 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

Reemplaza los siguientes elementos:

  • LOCATION: Es tu ubicación. La marca --location es opcional. Por ejemplo, si usas BigQuery en la región de Tokio, configura el valor de la marca 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 se están cargando los datos.
  • PATH_TO_SOURCE: Es la ruta del 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 la marca --autodetect en lugar de proporcionar una definición de esquema.

Además, puedes agregar marcas para las opciones de JSON y las opciones de CSV que te permiten controlar la manera en que BigQuery analiza los datos.

Ejemplos:

Con el siguiente comando, se cargan datos de 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 \
    ./mydata.json

Con el siguiente comando, se cargan datos de mydata.json y se adjuntan datos a una tabla llamada 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

Con el siguiente comando, se cargan datos de mydata.json y se adjuntan datos a una tabla llamada mytable en mydataset. Se usa un archivo de esquema JSON local llamado 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

Con el siguiente comando, se cargan datos de mydata.csv y se adjuntan datos a una tabla llamada mytable en mydataset. Se usa un archivo de esquema JSON local llamado myschema.json. La definición del esquema cambia (disminuye) dos campos de 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 contenido multimedia 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 cargar, se incluyen fotos, videos, archivos PDF, archivos ZIP o cualquier otro tipo de datos.

Opciones de carga

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

  • Tamaño máximo de carga de archivos: La cantidad máxima de datos que puedes almacenar con este método.
  • Tipos de MIME multimedia 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 metadatos y archivos pequeños, transfiere el archivo con los metadatos que lo describen en una única solicitud.
  • Carga reanudable: uploadType=resumable. Para una transferencia confiable, es importante en particular 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 subes contenido multimedia, utilizas un URI específico. De hecho, los métodos compatibles con cargas de este tipo de contenido tienen dos extremos de URI:

  • El URI /upload, para elementos multimedia. El formato del extremo de carga es el URI de recurso estándar con el prefijo “/upload”. Usa este URI cuando transfieras los datos del contenido multimedia. 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 usan para almacenar metadatos que describen el archivo subido. Puedes usar este URI cuando creas o actualizas valores de metadatos. 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 única solicitud multipart/related. Esta es una buena opción si los datos que vas a enviar son pequeños como para volver a subirlos 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 búsquedauploadType=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 multiparte, se incluyen los siguientes:

  • Content-Type. Configurado como multiparte/relacionado; incluye la string de límite que usas 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 elementos multimedia 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 dos partes. Las partes se identifican mediante una string de límite, y la última string de límite 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 elementos multimedia: Debe ir en segundo lugar, y Content-Type debe coincidir con uno de los tipos MIME de contenido multimedia aceptados del método.

Consulta la referencia de la API para conocer la lista de tipos MIME de contenido multimedia aceptados de cada 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://bigquery.googleapis.com/bigquery/v2/projects/projectId/jobs

Ejemplo: Carga multiparte

En el ejemplo que se incluye a continuación, se muestra una solicitud de carga multiparte a 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 con éxito, 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 usar el protocolo de carga reanudable. Con este protocolo, puedes reanudar una operación de carga luego de que una falla de comunicación haya interrumpido el flujo de datos. Esto resulta útil cuando transfieres archivos grandes, y existe una probabilidad alta de que se interrumpa la conexión de red o de que se genere alguna otra falla de transmisión, como puede ocurrir, por ejemplo, cuando subes archivos desde una app cliente para dispositivos móviles. Además, se puede reducir tu uso del ancho de banda ante fallas en la red, ya que no necesitas reiniciar la carga de archivos grandes desde el principio.

Entre los pasos para usar 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 eI URI de la sesión reanudable. Guarda el URI de la sesión que se muestra en la respuesta de la solicitud inicial; lo usarás para las solicitudes restantes de esta sesión.
  3. Sube el archivo. Envía el archivo multimedia al URI de la sesión reanudable.

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

Nota: Un URI de carga expira en una semana.

Paso 1: Inicia 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 búsquedauploadType=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 solo los metadatos; transferirás el contenido real del archivo que deseas cargar en solicitudes posteriores.

Usa los siguientes encabezados HTTP con la solicitud inicial:

  • X-Upload-Content-Type. Configurado como el tipo MIME de contenido multimedia 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 que se realiza 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 bytes que se proporcionaron en el cuerpo de esta solicitud inicial. No es necesario si usas la codificación de transferencia fragmentada.

Consulta la referencia de la API para conocer la lista de tipos MIME de contenido multimedia aceptados de cada 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 reanudable inicial 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: Guarda el URI de la sesión reanudable

Si la solicitud de inicio de sesión tiene éxito, 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 búsqueda upload_id que proporciona el ID de carga único que se debe usar 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 sesión que usarás como extremo HTTP para cargar el archivo o consultar el estado de carga.

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

Paso 3: carga 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 usar cuando se realizan solicitudes de carga de archivos reanudables incluyen Content-Length. Configúralo como la cantidad de bytes que cargarás en esta solicitud, que suele ser 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 del 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 tiene éxito, el servidor responde con HTTP 201 Created y con todos los metadatos asociados a ese recurso. Si la solicitud inicial de la sesión reanudable hubiera sido PUT, para actualizar un recurso existente, la respuesta que indica que se realizó con éxito sería 200 OK, junto con todos los metadatos asociados a este recurso.

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


Sube el archivo en partes

Con las cargas reanudables, puedes fragmentar un archivo y enviar diferentes solicitudes para cargar cada parte en secuencia. No se recomienda este enfoque, ya que tiene costos de rendimiento asociados con las solicitudes adicionales y, por lo general, no es necesario. Sin embargo, es posible que necesites usar la fragmentación para reducir la cantidad de datos que se transfieren en una sola solicitud. Esto es útil cuando hay 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 del progreso de una carga a los navegadores heredados que no cuentan con asistencia de progreso de carga de forma predeterminada.


Reanuda una carga interrumpida

Si una solicitud de carga se interrumpe antes de que recibas una respuesta, o si recibes una respuesta HTTP 503 Service Unavailable por parte del servidor, debes reanudar la carga interrumpida. Para ello, sigue estos pasos:

  1. Estado de la solicitud. Consulta el estado actual de la carga mediante una solicitud PUT vacía al URI de carga. En esta solicitud, los encabezados HTTP deben incluir un encabezado Content-Range que indique que se desconoce la posición actual en el archivo. Por ejemplo, configura Content-Range como */2000000 si la longitud total del archivo es 2,000,000. Si desconoces el tamaño original del archivo, configura Content-Range como */*.

    Nota: Puedes solicitar el estado entre partes, no solo 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 usa el encabezado Range en su respuesta para especificar qué bytes recibió hasta el momento. Por ejemplo, un encabezado Range de 0-299999 indica que se recibieron los primeros 300,000 bytes del archivo.
  3. Sube los datos restantes. Por último, ahora que sabes dónde reanudar la solicitud, envía los datos restantes o la parte actual. Ten en cuenta que, en cualquiera de ambos casos, debes tratar a los datos restantes como partes separadas, por lo que necesitarás enviar el encabezado Content-Range cuando reanudes la carga.
Ejemplo: Reanuda una carga interrumpida

1) Solicita el estado de la carga.

En la siguiente solicitud, se usa el encabezado Content-Range para indicar que se desconoce la posición actual en el archivo de 2,000,000 bytes.

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.

En la respuesta del servidor, se usa el encabezado Range para indicar que se recibieron los primeros 43 bytes del archivo hasta el momento. Usa el valor superior del encabezado Range para determinar dónde comenzar la carga reanudada.

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 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

Prácticas recomendadas

Cuando cargues contenido multimedia, es útil conocer algunas de las prácticas recomendadas relacionadas con el manejo de errores:

  • Reanuda o reintenta cargas que no se realizaron de forma correcta debido a interrupciones en la conexión o cualquier error 5xx, incluidos 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 de servidor 5xx cuando reanudas o reintentas 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 y 410 Gone cuando realices cargas reanudables; para ello, vuelve a iniciar toda la carga desde el principio.

Retirada exponencial

La retirada exponencial es una estrategia estándar de manejo de errores para aplicaciones de red en la que el cliente reintenta de forma periódica 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 puede ser una buena estrategia para manejar estos errores. Por el contrario, esta estrategia no se recomienda para lidiar con errores que no estén relacionados con el volumen de la red o los tiempos de respuesta, 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 la capacidad de procesamiento 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, que indica que debes reintentar la solicitud
  3. Esperar 1 segundo + random_number_milliseconds y reintentar la solicitud
  4. Recibir una respuesta HTTP 503, que indica que debes reintentar la solicitud
  5. Esperar 2 segundos + random_number_milliseconds y reintentar la solicitud
  6. Recibir una respuesta HTTP 503, que indica que debes reintentar la solicitud
  7. Esperar 4 segundos + random_number_milliseconds y reintentar la solicitud
  8. Recibir una respuesta HTTP 503, que indica que debes reintentar la solicitud
  9. Esperar 8 segundos + random_number_milliseconds y reintentar la solicitud
  10. Recibir una respuesta HTTP 503, 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 la que n es un número entero, que crece de forma monotónica, definido en un inicio 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 sea 5. Este límite impide que los clientes reintenten las solicitudes de forma infinita y genera una demora total de alrededor de 32 segundos antes de que una solicitud se considere “un error irrecuperable”. Un límite de reintentos mayor es aceptable, sobre todo si hay una carga larga en progreso. Solo asegúrate de limitar la demora de reintentos a un valor razonable, por ejemplo, menos de un minuto.