Datos de carga por lotes

Puedes cargar datos en BigQuery desde Cloud Storage o desde un archivo local como una operación por lotes. Los datos de origen pueden estar en cualquiera de los siguientes formatos:

• Avro
• Valores separados por comas (CSV)
• JSON (delimitado por saltos de línea)
• ORC
• Parquet
• Exportaciones de Firestore almacenadas en Cloud Storage

También puedes usar el Servicio de transferencia de datos de BigQuery para configurar cargas recurrentes de Cloud Storage a BigQuery.

Pruébalo tú mismo

Si eres nuevo en Google Cloud, crea una cuenta para evaluar el rendimiento de BigQuery en situaciones reales. Los clientes nuevos también obtienen $300 en créditos gratuitos para ejecutar, probar y, además, implementar cargas de trabajo.

Probar BigQuery gratis

Antes de comenzar

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

Permisos necesarios

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

Permisos para cargar datos a BigQuery

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

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

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

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

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

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

Permisos para subir datos desde Cloud Storage

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

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

Permisos necesarios

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

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

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

Crea un conjunto de datos

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

Carga datos desde Cloud Storage

BigQuery es compatible con la carga de datos desde cualquiera de las siguientes clases de almacenamiento de Cloud Storage:

• Estándar
• Nearline
• Coldline

• Archivo Si necesitas información para cargar datos en BigQuery, consulta la página de tu formato de datos:

• CSV

• JSON

• Avro

• Parquet

• ORC

• Exportaciones de Datastore

• Exportaciones de Firestore

Si necesitas información para configurar una carga recurrente de Cloud Storage a BigQuery, consulta Transferencias de Cloud Storage.

Consideraciones de ubicación

Cuando cargas datos desde Cloud Storage con una tabla externa de BigLake o una tabla externa que no sea de BigLake, los datos que cargas se deben ubicar con tu conjunto de datos de BigQuery.

• Puedes cargar datos desde un bucket de Cloud Storage en cualquier ubicación si tu conjunto de datos de BigQuery se encuentra en la multirregión US.

• Bucket multirregional: Si el bucket de Cloud Storage desde el que deseas cargar se encuentra en un bucket multirregional, tu conjunto de datos de BigQuery puede estar en el mismo bucket multirregional o en otra región individual que se incluya en el mismo bucket multirregional. Por ejemplo, si el bucket de Cloud Storage está en la región EU, tu conjunto de datos de BigQuery puede estar en la multirregión EU o en cualquier región individual en EU.

• Bucket birregional: Si el bucket de Cloud Storage desde el que deseas cargar se encuentra en un bucket birregional, tu conjunto de datos de BigQuery puede estar ubicado en las regiones que se incluyen en el bucket birregional o en una multirregión que incluya la región doble. Por ejemplo, si tu bucket de Cloud Storage se encuentra en la región EUR4, tu conjunto de datos de BigQuery puede estar ubicado en la región individual de Finlandia (europe-north1), Países Bajos (europe-west4) o en la multirregión EU.

  Para obtener más información, consulta Crea un bucket birregional.

• Bucket de una sola región: Si el bucket de Cloud Storage desde el que deseas cargar está en una sola región, tu conjunto de datos de BigQuery puede estar en la misma región única o en la multirregión que incluya la región única. Por ejemplo, si tu bucket de Cloud Storage está en la región Finlandia (europe-north1), tu conjunto de datos de BigQuery puede estar en Finlandia o en la multirregión EU.

• Una excepción es que, si tu conjunto de datos de BigQuery se encuentra en la región asia-northeast1, tu bucket de Cloud Storage puede estar ubicado en la multirregión EU.

Para obtener más información sobre las ubicaciones de Cloud Storage, consulta Ubicaciones de buckets en la documentación de Cloud Storage.

No puedes cambiar la ubicación de un conjunto de datos después de crearlo, pero puedes hacer una copia de él o moverlo manualmente. Para obtener más información, consulta los siguientes recursos:

• Copia de conjuntos de datos
• Mueve un conjunto de datos

Recupera el URI de Cloud Storage

Para cargar los datos desde la fuente de datos de Cloud Storage, debes proporcionar el URI de Cloud Storage.

La ruta de acceso del recurso de Cloud Storage contiene el nombre del bucket y tu objeto (nombre del archivo). Por ejemplo, si el bucket de Cloud Storage se llama mybucket y el archivo de datos se llama myfile.csv, la ruta a la fuente será gs://mybucket/myfile.csv.

BigQuery no admite rutas de recursos de Cloud Storage que incluyen varias barras consecutivas después de la doble barra inicial. Los nombres de los objetos de Cloud Storage pueden contener varios caracteres de barras consecutivas (“/”). Sin embargo, BigQuery convierte varias barras consecutivas en una sola barra. Por ejemplo, la ruta de acceso al recurso siguiente, aunque es válida en Cloud Storage, no funciona en BigQuery: gs://bucket/my//object//name.

Para recuperar el URI del recurso de Cloud Storage, sigue estos pasos:

1. Abre Cloud Storage Console.

   Consola de Cloud Storage

2. Explora la ubicación del objeto (archivo) que contiene los datos de origen.

3. Haz clic en el nombre del objeto.

   Se abrirá la página Detalles del objeto.

4. Copia el valor proporcionado en el campo URI de gsutil, que inicia con gs://.

Nota: También puedes usar el comando gsutil ls para enumerar objetos o buckets.

Para las exportaciones de Google Datastore, solo se puede especificar un URI, que debe terminar con .backup_info o .export_metadata.

Admisión de comodines para el URI de Cloud Storage

Si los datos se separan en varios archivos, puedes usar un asterisco (*) para elegir varios archivos. El uso del comodín de asterisco debe seguir estas reglas:

• El asterisco puede aparecer dentro del nombre del objeto o al final de este.
• No se admite el uso de varios asteriscos. Por ejemplo, la ruta gs://mybucket/fed-*/temp/*.csv no es válida.
• No se admite el uso de un asterisco con el nombre del bucket.

Ejemplos:

• En el ejemplo siguiente, se muestra cómo elegir todos los archivos en todas las carpetas que inician con el prefijo gs://mybucket/fed-samples/fed-sample:

  gs://mybucket/fed-samples/fed-sample*
  

• En el siguiente ejemplo, se muestra cómo elegir solo los archivos con una extensión .csv en la carpeta llamada fed-samples y cualquier subcarpeta de fed-samples:

  gs://mybucket/fed-samples/*.csv
  

• En el siguiente ejemplo, se muestra cómo elegir archivos con un patrón de nombres de fed-sample*.csv en la carpeta llamada fed-samples. En este ejemplo, no se eligen archivos en subcarpetas de fed-samples.

  gs://mybucket/fed-samples/fed-sample*.csv
  

Cuando usas la herramienta de línea de comandos de bq, es posible que debas descartar el asterisco en algunas plataformas.

No puedes usar un comodín de asterisco cuando cargas datos de exportación de Datastore o Firestore desde Cloud Storage.

Limitaciones

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

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

Según el formato de tus datos de origen de Cloud Storage, puede haber limitaciones adicionales. Para obtener más información, consulta los siguientes recursos:

• Limitaciones de CSV
• Limitaciones de JSON
• Limitaciones de exportación de Datastore
• Limitaciones de exportación de Firestore
• Limitaciones sobre datos anidados y repetidos

Carga datos de archivos locales

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

• La consola de Google Cloud
• El comando bq load de la herramienta de línea de comandos de bq
• La API
• Las bibliotecas cliente

Cuando cargas datos usando la consola de Google Cloud o la herramienta de línea de comandos de bq, se crea automáticamente un trabajo de carga.

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

Console

1. Abre la página BigQuery en la consola de Google Cloud.

   Ir a la página de BigQuery

2. En el panel Explorador, expande tu proyecto y selecciona un conjunto de datos.

3. Expande la opción Acciones y haz clic en Abrir.

4. En el panel de detalles, haz clic en Crear tabla  (Create table).

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

   • Para Crear tabla desde (Create table from), selecciona Subir (Upload).
   • En Seleccionar archivo, haz clic en Explorar.
   • 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.

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

   • En Proyecto, elige el proyecto adecuado.
   • En Conjunto de datos, elige el conjunto de datos apropiado.
   • En el campo Nombre de tabla, ingresa el nombre de la tabla que quieres crear en BigQuery.
   • Verifica que Table type (Tipo de tabla) esté establecido en Native table (Tabla nativa).

7. 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 (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:

       Nota: Para ver el esquema de una tabla existente en formato JSON, ingresa el siguiente comando: bq show --format=prettyjson dataset.table.

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

8. Selecciona los elementos aplicables en la sección Opciones avanzadas. Para obtener información sobre las opciones disponibles, consulta Opciones de CSV y Opciones de JSON.

9. En Opciones avanzadas, elige la disposición de escritura (opcional):

   • Escribir si está vacía: Escribe los datos solo si la tabla está vacía.
   • Agregar a la tabla: agrega los datos al final de la tabla. Esta configuración es la predeterminada.
   • Reemplazar tabla: Borra todos los datos existentes en la tabla antes de escribir los datos nuevos.

10. Haz clic en Crear tabla.

bq

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

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

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 lo siguiente:

• 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 Opciones de CSV y Opciones de JSON.

Ejemplos:

El siguiente comando carga un archivo JSON local delimitado por saltos de línea (mydata.json) en una tabla llamada mytable almacenada en mydataset en 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 local (mydata.csv) en una tabla llamada mytable almacenada 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

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

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

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

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 = job.PollUntilCompleted().ThrowOnAnyError();  // 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 incluidas en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para Go.

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

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.

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 incluidas en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para Java.

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

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

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

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 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. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para PHP.

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

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 para Python incluidas en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para Python.

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

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

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

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

job_config = bigquery.LoadJobConfig(
    source_format=bigquery.SourceFormat.CSV, skip_leading_rows=1, autodetect=True,
)

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

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

table = client.get_table(table_id)  # Make an API request.
print(
    "Loaded {} rows and {} columns to {}".format(
        table.num_rows, len(table.schema), table_id
    )
)

Rita

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

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

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

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 usas la consola de Google Cloud, los archivos cargados desde una fuente de datos local no pueden exceder los 100 MB. Si necesitas cargar archivos más grandes, hazlo desde Cloud Storage.
• De forma predeterminada, los trabajos de carga usan un grupo compartido de ranuras. BigQuery no garantiza la capacidad disponible de este grupo compartido o la capacidad de procesamiento que verás. De manera alternativa, puedes comprar ranuras dedicadas para ejecutar trabajos de carga. Para obtener más información, consulta Precios por transferencia de datos. ## Carga datos comprimidos y sin comprimir

Para los formatos Avro, Parquet y ORC, BigQuery es compatible con la carga de archivos en los que los datos de archivo se comprimen con un códec compatible. Sin embargo, BigQuery no admite la carga de archivos en estos formatos que se comprimieron, por ejemplo, con la utilidad gzip.

Se prefiere el formato binario Avro para cargar datos comprimidos y sin comprimir. Los datos Avro se cargan más rápido, porque pueden leerse en paralelo, incluso cuando los bloques de datos están comprimidos. Para obtener una lista de códecs de compresión compatibles, consulta Compresión de Avro.

El formato binario Parquet también es una buena opción, ya que brinda una codificación eficiente y por columna que suele generar un mejor índice de compresión y archivos más pequeños. Además, los archivos Parquet usan técnicas de compresión que permiten cargar archivos en paralelo. Para obtener una lista de códecs de compresión compatibles, consulta Compresión de Parquet.

El formato binario ORC ofrece beneficios similares a los del formato Parquet. Los datos en los archivos ORC se cargan rápido, ya que las franjas de datos se pueden leer en paralelo. Las filas en cada franja de datos se cargan de manera secuencial. A fin de optimizar el tiempo de carga, usa franjas de datos con un tamaño aproximado de 256 MB o menos. Para obtener una lista de códecs de compresión compatibles, consulta Compresión de ORC.

Para otros formatos de datos, como CSV y JSON, BigQuery puede cargar archivos sin comprimir mucho más rápido que archivos comprimidos, ya que los no comprimidos se pueden leer en paralelo. Debido a que los archivos sin comprimir son más grandes, su uso puede llevar a limitaciones en el ancho de banda y a mayores costos de Cloud Storage para los datos almacenados en Cloud Storage antes de su carga en BigQuery. Ten en cuenta que el orden de las líneas no está garantizado para archivos comprimidos o sin comprimir. Es importante considerar estas cuestiones según tu caso práctico.

En general, si el ancho de banda es limitado, debes comprimir tus archivos CSV y JSON con gzip antes de cargarlos a Cloud Storage. gzip es el único tipo de compresión de archivos compatible con archivos CSV y JSON cuando se cargan datos en BigQuery. Si la velocidad de carga es importante en tu app y tienes mucho ancho de banda para cargar tus datos, no comprimas los archivos.

Anexa o reemplaza una tabla

Puedes cargar datos adicionales en una tabla desde archivos de origen o cuando adjuntas resultados de consultas. 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 de Google Cloud, usa la opción de Preferencia de escritura para especificar qué acción se debe tomar cuando cargues datos desde un archivo de origen o desde el resultado de una consulta. La herramienta de línea de comandos de bq y la API incluyen las siguientes opciones:

Opción de Console	Marca de la herramienta de bq	Propiedad de la API de BigQuery	Descripción
Escribir si está vacía	Ninguna	WRITE_EMPTY	Solo escribe los datos si la tabla está vacía.
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.
Reemplazar tabla	--replace o --replace=true	WRITE_TRUNCATE	Borra todos los datos existentes de una tabla antes de escribir los datos nuevos.

Política de cuotas

Si necesitas información sobre la política de cuotas para cargar datos por lotes, consulta Trabajos de carga en la página Cuotas y límites.

Visualiza el uso actual de la cuota

Puedes ver el uso actual de los trabajos de consulta, carga, extracción o copia mediante la ejecución de una consulta INFORMATION_SCHEMA para ver los metadatos sobre los trabajos que se ejecutaron durante un período específico. Puedes comparar el uso actual con el límite de cuota a fin de determinar el uso de la cuota para un tipo de trabajo en particular. La siguiente consulta de ejemplo usa la vista INFORMATION_SCHEMA.JOBS para enumerar la cantidad de trabajos de consulta, carga, extracción y copia por proyecto:

SELECT
  sum(case  when job_type="QUERY" then 1 else 0 end) as QRY_CNT,
  sum(case  when job_type="LOAD" then 1 else 0 end) as LOAD_CNT,
  sum(case  when job_type="EXTRACT" then 1 else 0 end) as EXT_CNT,
  sum(case  when job_type="COPY" then 1 else 0 end) as CPY_CNT
FROM `region-eu`.INFORMATION_SCHEMA.JOBS_BY_PROJECT
WHERE date(creation_time)= CURRENT_DATE()

Precios

Subir datos en BigQuery no tiene costo. Para obtener más información, consulta Precios por transferencia de datos de BigQuery.

Ejemplo de caso de uso

Supongamos que hay una canalización de procesamiento por lotes nocturna que se debe completar antes de una fecha límite fija. Los datos deben estar disponibles para este plazo a fin de que otro proceso por lotes los procese de modo que genere informes para enviarlos a un regulador. Este caso de uso es común en sectores regulados, como las finanzas.

La carga por lotes de datos con trabajos de carga es el enfoque correcto para este caso de uso, ya que la latencia no es una preocupación, siempre que se cumpla el plazo. Asegúrate de que tus buckets de Cloud Storage cumplan con los requisitos de ubicación para cargar datos en el conjunto de datos de BigQuery.

El resultado de un trabajo de carga de BigQuery es atómico; se insertan todos los registros o no se inserta ninguno. Como práctica recomendada, cuando insertes todos los datos en un solo trabajo de carga, crea una tabla nueva usando la disposición WRITE_TRUNCATE del recurso JobConfigurationLoad. Esto es importante cuando se reintenta un trabajo de carga con errores, ya que es posible que el cliente no pueda distinguir entre los trabajos que fallaron y la falla que causó el error, por ejemplo, cuando se comunica el estado de éxito al cliente.

Si suponemos que los datos que se transferirán ya se copiaron correctamente en Cloud Storage, basta con reintentar con una retirada exponencial para abordar las fallas de transferencia.

Se recomienda que un trabajo por lotes nocturno no alcance la cuota predeterminada de 1,500 cargas por tabla por día, incluso con reintentos. Cuando se cargan datos de forma incremental, la cuota predeterminada es suficiente para ejecutar un trabajo de carga cada 5 minutos, y queda cuota para al menos 1 reintento por trabajo en promedio.