Carga de datos 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 líneas nuevas)
• ORC
• Parquet
• Exportaciones de Datastore almacenadas en Cloud Storage
• Exportaciones de Firestore almacenadas en Cloud Storage

También puedes usar BigQuery Data Transfer Service para configurar cargas periódicas de Cloud Storage a BigQuery.

Antes de empezar

Asigna roles de gestión de identidades y accesos (IAM) que proporcionen a los usuarios los permisos necesarios para realizar cada tarea de este documento y crea un conjunto de datos para almacenar tus datos.

Permisos obligatorios

Para cargar datos en BigQuery, necesitas permisos de gestión de identidades y accesos para ejecutar un trabajo de carga y cargar datos en tablas y particiones de BigQuery. Si cargas datos desde Cloud Storage, también necesitas permisos de IAM para acceder al segmento que contiene tus datos.

Permisos para cargar datos en BigQuery

Para cargar datos en una tabla o partición de BigQuery, o bien para añadir o sobrescribir una tabla o partición, necesitas los siguientes permisos de gestión de identidades y accesos:

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

Cada uno de los siguientes roles de gestión de identidades y accesos predefinidos 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 mediante un trabajo de carga en los conjuntos de datos que crees.

Para obtener más información sobre los roles y permisos de IAM en BigQuery, consulta el artículo sobre funciones y permisos predefinidos.

Permisos para cargar datos desde Cloud Storage

Para obtener los permisos que necesitas para cargar datos desde un segmento de Cloud Storage, pide a tu administrador que te conceda el rol de gestión de identidades y accesos Administrador de Storage (roles/storage.admin) en el segmento. Para obtener más información sobre cómo conceder roles, consulta el artículo Gestionar el acceso a proyectos, carpetas y organizaciones.

Este rol predefinido contiene los permisos necesarios para cargar datos desde un segmento de Cloud Storage. Para ver los permisos exactos que se necesitan, despliega la sección Permisos necesarios:

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

Crear conjunto de datos

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

Cargar datos desde Cloud Storage

BigQuery permite cargar datos de cualquiera de las siguientes clases de almacenamiento de Cloud Storage:

• Estándar
• Nearline
• Coldline
• Archivar

Para saber cómo cargar datos en BigQuery, consulta la página correspondiente a tu formato de datos:

• CSV
• JSON
• Avro
• Parqué
• ORC
• Exportaciones de Datastore
• Exportaciones de Firestore

Para saber cómo configurar una carga periódica de Cloud Storage en BigQuery, consulta Transferencias de Cloud Storage.

Consideraciones de ubicación

No puede cambiar la ubicación de un conjunto de datos después de crearlo, pero puede hacer una copia o moverlo manualmente. Para obtener más información, consulta estos artículos:

• Copiar conjuntos de datos
• Mover un conjunto de datos

Obtener el URI de Cloud Storage

Para cargar datos de una fuente de datos de Cloud Storage, debe proporcionar el URI de Cloud Storage.

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

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

Para obtener la ruta del recurso de Cloud Storage, sigue estos pasos:

1. Abre la consola de Cloud Storage.

   Consola de Cloud Storage

2. Desplázate hasta 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 empieza por gs://.

En el caso de las exportaciones de Google Datastore, solo se puede especificar un URI, que debe terminar en .backup_info o .export_metadata.

Compatibilidad con comodines en URIs de Cloud Storage

Si los datos están separados en varios archivos, puede usar un asterisco (*) como comodín para seleccionar varios archivos. El uso del carácter comodín asterisco debe seguir estas reglas:

• El asterisco puede aparecer dentro del nombre del objeto o al final del nombre del objeto.
• 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 segmento.

Ejemplos:

• En el siguiente ejemplo se muestra cómo seleccionar todos los archivos de todas las carpetas que empiezan por el prefijo gs://mybucket/fed-samples/fed-sample:

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

• En el siguiente ejemplo se muestra cómo seleccionar solo los archivos con la extensión .csv de la carpeta fed-samples y de sus subcarpetas:fed-samples

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

• En el siguiente ejemplo se muestra cómo seleccionar archivos con un patrón de nomenclatura de fed-sample*.csv en la carpeta llamada fed-samples. En este ejemplo no se seleccionan archivos de las subcarpetas de fed-samples.

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

Cuando uses la herramienta de línea de comandos bq, es posible que tengas que usar la barra inversa para 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

Cuando cargas datos en BigQuery desde un segmento de Cloud Storage, estás sujeto a las siguientes limitaciones:

• BigQuery no garantiza la coherencia de los datos de las fuentes de datos externas. Si se modifican los datos subyacentes mientras se ejecuta una consulta, se pueden producir comportamientos inesperados.
• BigQuery no admite la gestión 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á.

En función del formato de los datos de origen de Cloud Storage, puede haber limitaciones adicionales. Para obtener más información, consulta estos artículos:

• Limitaciones de los archivos CSV
• Limitaciones de JSON
• Limitaciones de la exportación del almacén de datos
• Limitaciones de la exportación de Firestore
• Limitaciones en los datos anidados y repetidos

Cargar datos de archivos locales

Puede cargar datos de una fuente de datos legible (como su máquina local) mediante una de las siguientes opciones:

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

Cuando cargas datos con la consola de Google Cloud o la herramienta de línea de comandos bq, se crea automáticamente una tarea de carga.

Para cargar datos de una fuente de datos local, sigue estos pasos:

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

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

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

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

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}");
        }
    }
}

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
}

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();

// 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;
  }
}

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);
}

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

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:

• No se admiten comodines ni listas separadas por comas cuando se cargan archivos de una fuente de datos local. Los archivos deben cargarse individualmente.
• Cuando se usa la consola Google Cloud , los archivos cargados desde una fuente de datos local no pueden superar los 100 MB. En el caso de archivos más grandes, carga el archivo desde Cloud Storage.

Capacidad de carga de trabajos

Al igual que en el modo bajo demanda de las consultas, las tareas de carga utilizan de forma predeterminada un grupo compartido de ranuras. BigQuery no garantiza la disponibilidad de este grupo compartido ni el rendimiento de las tareas de carga.

Para aumentar el rendimiento o controlar de forma predecible la capacidad de tus tareas de carga, puedes crear una reserva de ranuras y asignar ranuras PIPELINE dedicadas para ejecutar tareas de carga. Para obtener más información, consulta Asignaciones de reservas.

Cargar datos comprimidos y sin comprimir

En el caso de los formatos Avro, Parquet y ORC, BigQuery admite la carga de archivos en los que los datos se han comprimido con un códec compatible. Sin embargo, BigQuery no admite la carga de archivos en estos formatos que se hayan comprimido, por ejemplo, con la utilidad gzip.

El formato binario Avro es el formato preferido para cargar datos comprimidos y sin comprimir. Los datos Avro se cargan más rápido porque se pueden leer en paralelo, incluso cuando los bloques de datos están comprimidos. Para ver una lista de los códecs de compresión admitidos, consulta Compresión Avro.

El formato binario Parquet también es una buena opción, ya que la codificación eficiente por columna de Parquet suele dar como resultado una mejor relación de compresión y archivos más pequeños. Los archivos Parquet también aprovechan las técnicas de compresión que permiten cargar archivos en paralelo. Para ver una lista de los códecs de compresión admitidos, consulta Compresión de Parquet.

El formato binario ORC ofrece ventajas similares a las del formato Parquet. Los datos de los archivos ORC se cargan rápidamente porque las franjas de datos se pueden leer en paralelo. Las filas de cada franja de datos se cargan de forma secuencial. Para optimizar el tiempo de carga, utilice un tamaño de franja de datos de aproximadamente 256 MB o menos. Para ver una lista de los códecs de compresión admitidos, consulta Compresión ORC.

En el caso de 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 archivos sin comprimir se pueden leer en paralelo. Como los archivos sin comprimir son más grandes, su uso puede provocar limitaciones de ancho de banda y un aumento de los costes de Cloud Storage para los datos almacenados en Cloud Storage antes de cargarse en BigQuery. Ten en cuenta que el orden de las líneas no está garantizado en los archivos comprimidos o sin comprimir. Es importante sopesar estas ventajas e inconvenientes en función de tu caso práctico.

Por lo general, si el ancho de banda es limitado, comprima los archivos CSV y JSON con gzip antes de subirlos a Cloud Storage. gzip es el único tipo de compresión de archivos admitido para archivos CSV y JSON al cargar datos en BigQuery. Si la velocidad de carga es importante para tu aplicación y tienes mucho ancho de banda para cargar tus datos, deja los archivos sin comprimir.

Añadir datos a una tabla o sobrescribirla

Puedes cargar datos adicionales en una tabla desde archivos de origen o añadiendo resultados de consultas. Si el esquema de los datos no coincide con el esquema de la tabla o la partición de destino, puede actualizar el esquema cuando añada datos o los sobrescriba.

Si actualiza el esquema al añadir datos, BigQuery le permite hacer lo siguiente:

• Añadir campos
• Relajar los campos REQUIRED a NULLABLE

Si sobrescribes una tabla, el esquema siempre se sobrescribe. Las actualizaciones de esquemas no están restringidas cuando sobrescribes una tabla.

En la Google Cloud consola, usa la opción Preferencia de escritura para especificar qué acción se debe llevar a cabo cuando cargues datos de un archivo de origen o de un resultado de consulta. La herramienta de línea de comandos bq y la API incluyen las siguientes opciones:

Política de cuotas

Para obtener información sobre la política de cuotas para la carga por lotes de datos, consulta Tareas de carga en la página Cuotas y límites.

Ver la cuota de uso actual

Para ver el uso actual de las tareas de consulta, carga, extracción o copia, puedes ejecutar una INFORMATION_SCHEMA consulta para ver los metadatos de las tareas que se han ejecutado durante un periodo específico. Puedes comparar tu uso actual con el límite de cuota para determinar el uso de la cuota de un tipo de trabajo concreto. La siguiente consulta de ejemplo usa la vista INFORMATION_SCHEMA.JOBS para enumerar el número de tareas 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-REGION_NAME`.INFORMATION_SCHEMA.JOBS_BY_PROJECT
WHERE date(creation_time)= CURRENT_DATE()

Precios

No se aplican cargos por cargar datos por lotes en BigQuery con el grupo de ranuras compartido. Para obtener más información, consulta los precios de la ingestión de datos de BigQuery.

Caso práctico de ejemplo

Supongamos que hay una canalización de procesamiento por lotes nocturno que debe completarse antes de una fecha límite fija. Los datos deben estar disponibles antes de esta fecha límite para que otro proceso por lotes pueda tratarlos y generar los informes que se enviarán a un organismo regulador. Este caso práctico es habitual en sectores regulados, como el financiero.

Cargar datos por lotes con trabajos de carga es la opción adecuada para este caso de uso, ya que la latencia no es un problema siempre que se pueda cumplir el plazo. Asegúrate de que tus segmentos de Cloud Storage cumplen 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: o 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 con la WRITE_TRUNCATE de JobConfigurationLoad. Esto es importante cuando se vuelve a intentar un trabajo de carga fallido, ya que es posible que el cliente no pueda distinguir entre los trabajos que han fallado y el fallo causado, por ejemplo, al comunicar el estado correcto al cliente.

Si los datos que se van a ingerir ya se han copiado correctamente en Cloud Storage, basta con reintentar la operación con un retroceso exponencial para solucionar los errores de ingesta.

Se recomienda que una tarea por lotes nocturna no alcance la cuota predeterminada de 1500 cargas por tabla y 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 tener cuota sin consumir para al menos un reintento por trabajo de media.