Carga de datos ORC desde Cloud Storage

En esta página, se proporciona una descripción general de la carga de datos ORC de Cloud Storage en BigQuery.

ORC es un formato de datos orientado a columnas de código abierto que se usa ampliamente en el ecosistema Apache Hadoop.

Cuando cargas datos ORC de Cloud Storage, puedes cargar datos en una tabla o una partición nuevas, o puedes agregarlos a una tabla o una partición existente o reemplazarla con estos. Cuando tus datos se cargan en BigQuery, se convierten en formato de columnas para Capacitor (formato de almacenamiento de BigQuery).

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

Para obtener información sobre cómo cargar datos ORC de un archivo local, consulta Carga datos desde una fuente de datos local.

Esquemas de ORC

Cuando cargas archivos ORC en BigQuery, el esquema de tabla se recupera de forma automática a partir de los datos de origen autodescriptivos. Cuando BigQuery recupera el esquema de los datos de origen, se usa el último archivo en orden alfabético.

Por ejemplo, supongamos que tienes los siguientes archivos ORC en Cloud Storage:

gs://mybucket/00/
  a.orc
  z.orc
gs://mybucket/01/
  b.orc

Con este comando se cargan todos los archivos en un solo comando de la CLI (como una lista separada por comas), y el esquema se deriva de mybucket/01/b.orc:

bq load \
--source_format=ORC \
dataset.table \
"gs://mybucket/00/*.orc","gs://mybucket/01/*.orc"

Cuando BigQuery detecta el esquema, algunos tipos de datos ORC se convierten en tipos de datos de BigQuery para hacerlos compatibles con la sintaxis SQL de BigQuery. Todos los campos en el esquema detectado son NULLABLE. Para obtener más información, consulta la sección Conversiones de ORC.

Cuando cargas varios archivos ORC con diferentes esquemas, los campos idénticos (con el mismo nombre y mismo nivel de anidamiento) especificados en múltiples esquemas deben asignarse al mismo tipo de datos convertido de BigQuery en cada definición de esquema.

Compresión de ORC

Los archivos ORC comprimidos no son compatibles, pero las rayas y el pie de página del archivo comprimido lo son. Los tipos de compresión compatibles son Zlib, Snappy, LZO y LZ4.

Permisos necesarios

Cuando cargas datos en BigQuery, necesitas permisos para ejecutar un trabajo de carga y cargar datos en tablas y particiones nuevas o existentes de BigQuery. Si cargas datos desde Cloud Storage, también necesitas permisos para acceder al depósito que contiene tus datos.

Permisos de BigQuery

Para cargar datos en BigQuery, se requieren, como mínimo, los siguientes permisos. Estos permisos son obligatorios si los datos se cargan en una tabla o partición nueva, o si se reemplaza una tabla o partición o se agregan datos a esta.

bigquery.tables.create
bigquery.tables.updateData
bigquery.jobs.create

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 permite que el usuario cree y actualice tablas en el conjunto de datos a través de un trabajo de carga.

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

Permisos de Cloud Storage

Para cargar datos desde un depósito de Cloud Storage, debes tener permisos storage.objects.get. Si usas un comodín de URI, también debes tener permisos storage.objects.list.

La función de Cloud IAM predefinida storage.objectViewer puede otorgarse para proporcionar los permisos storage.objects.get y storage.objects.list.

Carga datos ORC en una tabla nueva

Tienes las siguientes opciones para cargar datos ORC en una tabla nueva:

Usar Cloud Console o la IU web clásica
Usar el comando bq load de la CLI
Realizar una llamada al método jobs.insert de la API y configurar un trabajo de load
Usar bibliotecas cliente

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

Console

Abre la IU web de BigQuery en Cloud Console.
Ir a Cloud Console
En el panel de navegación, en la sección Recursos (Resources), expande tu proyecto y selecciona un conjunto de datos.
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.
En la sección Fuente (Source) de la página Crear tabla (Create table), haz lo siguiente:
- En Crear tabla desde (Create table from), selecciona Cloud Storage.
- En el campo de origen, busca o ingresa el URI de Cloud Storage. Ten en cuenta que no puedes incluir varios URI en Cloud Console, pero se admiten comodines. El depósito de Cloud Storage debe estar en la misma ubicación que el conjunto de datos que contiene la tabla que quieres crear.
- En Formato del archivo: (File format), selecciona ORC.
En la sección Destino (Destination) de la página Crear tabla (Create table), haz lo siguiente:
- En Nombre del conjunto de datos (Dataset name), selecciona el conjunto de datos que corresponda.
- Verifica que Tipo de tabla (Table type) esté establecido en Tabla nativa (Native table).
- En el campo Nombre de la tabla (Table name), ingresa el nombre de la tabla que quieres crear en BigQuery.
En la sección Esquema (Schema), no es necesaria ninguna acción. El esquema se describe de forma automática en los archivos ORC.
Para particionar la tabla, elige las opciones en la Configuración de partición y agrupamiento en clústeres (Partition and cluster settings) (opcional):
- Para crear una tabla particionada, haz clic en Sin particionar (No partitioning), selecciona Particionar por campo (Partition by field) y elige una columna DATE o TIMESTAMP. Esta opción no estará disponible si el esquema no incluye una columna DATE o TIMESTAMP.
- Para crear una tabla particionada por tiempo de transferencia, haz clic en Sin particionar (No partitioning) y selecciona Particionar por tiempo de transferencia (Partition by ingestion time).
Para el Filtro de partición (Partitioning filter), haz clic en la casilla Exigir filtro de partición (Require partition filter) a fin de solicitar a los usuarios que incluyan una cláusula WHERE que especifique las particiones que deben consultarse (opcional). Exigir un filtro de partición puede reducir los costos y mejorar el rendimiento. Para obtener más información, lee la sección Consulta tablas particionadas. Esta opción no está disponible si se selecciona Sin particionar (No partitioning).
Para agrupar la tabla, en la casilla Orden de agrupamiento en clústeres (Clustering order), ingresa entre uno y cuatro nombres de campo (opcional). Por el momento, el agrupamiento en clústeres solo es compatible con tablas particionadas.
Haz clic en Opciones avanzadas (opcional).
- En Preferencia de escritura (Write preference), deja seleccionado Escribir si está vacía (Write if empty). Esta opción crea una tabla nueva y carga los datos en ella.
- En Cantidad de errores permitidos: (Number of errors allowed), acepta el valor predeterminado de 0 o ingresa la cantidad máxima de filas con errores que pueden ignorarse. Si la cantidad de filas con errores excede este valor, el trabajo generará un mensaje invalid y fallará.
- En Valores desconocidos (Unknown values), desmarca la opción Ignorar valores desconocidos (Ignore unknown values). Esta opción se aplica solo a los archivos CSV y JSON.
- En Encriptación (Encryption), haz clic en Clave administrada por el cliente (Customer-managed key) para usar una clave de Cloud Key Management Service. Si dejas establecida la configuración Clave administrada por Google (Google-managed key), BigQuery encripta los datos en reposo.
Haz clic en Crear tabla (Create table).

IU clásica

Ve a la IU web de BigQuery.
Ir a la IU web de BigQuery
En el panel de navegación, coloca el cursor sobre un conjunto de datos, haz clic en el ícono de flecha hacia abajo y, luego, en Crear tabla nueva (Create new table). El proceso de carga de datos es el mismo que el proceso para crear una tabla vacía.
En la sección Datos de origen (Source Data) de la página Crear tabla (Create Table), sigue estos pasos:
- Haz clic en Crear desde el origen (Create from source).
- En Ubicación (Location), selecciona Cloud Storage y, en el campo de origen, ingresa el URI de Cloud Storage. Ten en cuenta que no puedes incluir varios URI en la IU web de BigQuery, pero sí se admiten comodines. El depósito de Cloud Storage debe estar en la misma ubicación que el conjunto de datos que contiene la tabla que quieres crear.
- En Formato de archivo: (File format), selecciona ORC.
En la sección Tabla de destino (Destination Table), realiza lo siguiente:
- En Nombre de tabla (Table name), selecciona el conjunto de datos que corresponda y, en el campo de nombre de tabla, ingresa el nombre de la tabla que quieres crear en BigQuery.
- Verifica que Tipo de tabla (Table type) esté establecido en Tabla nativa (Native table).
En la sección Esquema (Schema), no es necesaria ninguna acción. El esquema se describe de forma automática en los archivos ORC.
En la sección Opciones (Options), realiza los siguientes pasos (opcional):
- En Cantidad de errores permitidos: (Number of errors allowed), acepta el valor predeterminado de 0 o ingresa la cantidad máxima de filas con errores que pueden ignorarse. Si la cantidad de filas con errores excede este valor, el trabajo generará un mensaje invalid y fallará.
- En Preferencia de escritura (Write preference), deja seleccionado Escribir si está vacía (Write if empty). Esta opción crea una tabla nueva y carga los datos en ella.
- Para particionar la tabla, realiza las siguientes acciones:
  - Para Tipo de partición (Partitioning Type), haz clic en Ninguna (None) y elige Día (Day).
  - En Campo de partición (Partitioning Field), haz lo siguiente:
  - Para crear una tabla particionada, elige una columna DATE o TIMESTAMP. Esta opción no estará disponible si el esquema no incluye una columna DATE o TIMESTAMP.
  - Para crear una tabla particionada por tiempo de transferencia, deja el valor predeterminado: _PARTITIONTIME.
  - Haz clic en la casilla Exigir filtro de partición (Require partition filter) para solicitar a los usuarios que incluyan una cláusula WHERE que especifique las particiones que desean consultar. Exigir un filtro de partición puede reducir los costos y mejorar el rendimiento. Para obtener más información, lee la sección Consulta tablas particionadas. Esta opción no estará disponible si el Tipo de partición (Partitioning type) está configurado como Ninguna (None).
- Para agrupar en clústeres la tabla, en la casilla Campos de agrupamiento en clústeres (Clustering fields), ingresa entre uno y cuatro nombres de campo.
- En Encriptación de destino (Destination encryption), elige Encriptación administrada por el cliente (Customer-managed encryption) para encriptar la tabla con una clave de Cloud Key Management Service. Si dejas la configuración Default, BigQuery encripta los datos en reposo con una clave administrada por Google.
Haz clic en Crear tabla (Create Table).

CLI

Usa el comando bq load, especifica ORC como el source_format y, además, incluye un URI de Cloud Storage. Puedes incluir un único URI, una lista de URI separados por comas o un URI que contenga un comodín.

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

Las siguientes son otras marcas opcionales:

--max_bad_records: Un número entero que especifica la cantidad máxima de registros incorrectos permitidos antes de que falle todo el trabajo. El valor predeterminado es 0. Como máximo, se muestran cinco errores de cualquier tipo, sin importar el valor --max_bad_records.
--time_partitioning_type: Habilita las particiones basadas en el tiempo en una tabla y establece el tipo de partición. Por el momento el único valor posible es DAY, que genera una partición por día. Esta marca es opcional cuando se crea una tabla particionada en una columna DATE o TIMESTAMP.
--time_partitioning_expiration: Un número entero que especifica (en segundos) cuándo se debe borrar una partición basada en el tiempo. La hora de vencimiento se evalúa según la suma de la fecha de la partición en formato UTC más el valor del número entero.
--time_partitioning_field: La columna DATE o TIMESTAMP que se usa para crear una tabla particionada. Si la partición basada en el tiempo se habilita sin este valor, se creará una tabla particionada por tiempo de transferencia.
--require_partition_filter: Cuando se habilita esta opción, se solicita a los usuarios que incluyan una cláusula WHERE que especifique las particiones que se desean consultar. Exigir un filtro de partición puede reducir los costos y mejorar el rendimiento. Para obtener más información, lee la sección Consulta tablas particionadas.
--clustering_fields: Una lista separada por comas de hasta cuatro nombres de columna que se usa para crear una tabla agrupada en clústeres. Esta marca solo se puede usar con tablas particionadas.
--destination_kms_key: La clave de Cloud KMS para la encriptación de los datos de la tabla.

Para obtener más información sobre las tablas particionadas, consulta los siguientes artículos:
- Crea y usa tablas particionadas por fecha o marca de tiempo
- Crea y usa tablas particionadas por tiempo de transferencia
Para obtener más información sobre tablas agrupadas en clústeres, consulta el siguiente artículo:
- Crea y usa tablas agrupadas
Para obtener más información sobre la encriptación de tablas, consulta el siguiente artículo:
- Protege datos con claves de Cloud KMS

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

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

Donde:

location es tu ubicación. La marca --location es opcional. Por ejemplo, si usas BigQuery en la región de Tokio, puedes establecer el valor de la marca como asia-northeast1. Puedes configurar un valor predeterminado para la ubicación con el archivo .bigqueryrc.
format es ORC.
dataset es un conjunto de datos existente.
table es el nombre de la tabla en la que cargas los datos.
path_to_source es un URI de Cloud Storage completamente calificado o una lista de URI separados por comas. También se admiten comodines.

Ejemplos:

Con el siguiente comando, se cargan datos de gs://mybucket/mydata.orc en una tabla llamada mytable en mydataset.

    bq load \
    --source_format=ORC \
    mydataset.mytable \
    gs://mybucket/mydata.orc

Con el siguiente comando, se cargan datos de gs://mybucket/mydata.orc en una tabla particionada por tiempo de transferencia llamada mytable en mydataset.

    bq load \
    --source_format=ORC \
    --time_partitioning_type=DAY \
    mydataset.mytable \
    gs://mybucket/mydata.orc

Con el siguiente comando, se cargan datos de gs://mybucket/mydata.orc en una tabla particionada llamada mytable en mydataset. La tabla está particionada en la columna mytimestamp.

    bq load \
    --source_format=ORC \
    --time_partitioning_field mytimestamp \
    mydataset.mytable \
    gs://mybucket/mydata.orc

Con el siguiente comando, se cargan datos de varios archivos de gs://mybucket/ en una tabla llamada mytable en mydataset. El URI de Cloud Storage usa un comodín.

    bq load \
    --source_format=ORC \
    mydataset.mytable \
    gs://mybucket/mydata*.orc

Con el siguiente comando, se cargan datos de varios archivos de gs://mybucket/ en una tabla llamada mytable en mydataset. El comando incluye una lista separada por comas de URI de Cloud Storage con comodines.

    bq load --autodetect \
    --source_format=ORC \
    mydataset.mytable \
    "gs://mybucket/00/*.orc","gs://mybucket/01/*.orc"

API

Crea un trabajo load que apunte a los datos de origen en Cloud Storage.
Especifica tu ubicación en la propiedad location de la sección jobReference del recurso de trabajo (opcional).
La propiedad source URIs debe estar completamente calificada en el formato gs://bucket/object. Cada URI puede contener un carácter comodín “*”.
Establece la propiedad sourceFormat en ORC para especificar el formato de datos ORC.
Para verificar el estado del trabajo, llama a jobs.get(job_id*), donde job_id es el ID del trabajo que muestra la solicitud inicial.
- Si se muestra status.state = DONE, el trabajo se completó de forma correcta.
- Si la propiedad status.errorResult está presente, la solicitud falló, y ese objeto incluirá información que describirá qué salió mal. Cuando una solicitud falla, no se crea ninguna tabla ni se cargan datos.
- Si status.errorResult está ausente, el trabajo se completó con éxito, aunque puede haber algunos errores recuperables, como problemas cuando se importan algunas filas. Los errores recuperables se enumeran en la propiedad status.errors del objeto de trabajo que se muestra.

Notas sobre la API:

Los trabajos de carga son atómicos y coherentes. Si un trabajo de carga falla, ninguno de los datos estará disponible, y si un trabajo de carga se realiza con éxito, todos los datos estarán disponibles.
Como práctica recomendada, genera un ID único y pásalo como jobReference.jobId cuando llames a jobs.insert para crear un trabajo de carga. Este enfoque es más resistente al fallo de la red porque el cliente puede sondear o reintentar con el ID de trabajo conocido.
Llamar a jobs.insert en un ID de trabajo determinado es idempotente. Puedes intentar tantas veces como desees en el mismo ID de trabajo y, como máximo, una de esas operaciones tendrá éxito.

C#

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

Ver en GitHub Comentarios


using Google.Apis.Bigquery.v2.Data;
using Google.Cloud.BigQuery.V2;
using System;

public class BigQueryLoadTableGcsOrc
{
    public void LoadTableGcsOrc(
        string projectId = "your-project-id",
        string datasetId = "your_dataset_id"
    )
    {
        BigQueryClient client = BigQueryClient.Create(projectId);
        var gcsURI = "gs://cloud-samples-data/bigquery/us-states/us-states.orc";
        var dataset = client.GetDataset(datasetId);
        TableReference destinationTableRef = dataset.GetTableReference(
            tableId: "us_states");
        // Create job configuration
        var jobOptions = new CreateLoadJobOptions()
        {
            SourceFormat = FileFormat.Orc
        };
        // Create and run job
        var loadJob = client.CreateLoadJob(
            sourceUri: gcsURI,
            destination: destinationTableRef,
            // Pass null as the schema because the schema is inferred when
            // loading Orc data
            schema: null,
            options: jobOptions
        );
        loadJob.PollUntilCompleted();  // Waits for the job to complete.
        // Display the number of rows uploaded
        BigQueryTable table = client.GetTable(destinationTableRef);
        Console.WriteLine(
            $"Loaded {table.Resource.NumRows} rows to {table.FullyQualifiedId}");
    }
}

Go

Antes de probar este ejemplo, sigue las instrucciones de configuración para Go incluidas en la Guía de inicio rápido: usa bibliotecas cliente. A fin de obtener más información, consulta la documentación de referencia de la API de BigQuery para Go.

Ver en GitHub Comentarios

import (
	"context"
	"fmt"

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

// importORCTruncate demonstrates loading Apache ORC data from Cloud Storage into a table.
func importORC(projectID, datasetID, tableID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	// tableID := "mytable"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}

	gcsRef := bigquery.NewGCSReference("gs://cloud-samples-data/bigquery/us-states/us-states.orc")
	gcsRef.SourceFormat = bigquery.ORC
	loader := client.Dataset(datasetID).Table(tableID).LoaderFrom(gcsRef)

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

	if status.Err() != nil {
		return fmt.Errorf("job completed with error: %v", status.Err())
	}
	return nil
}

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: usa bibliotecas cliente. A fin de obtener más información, consulta la documentación de referencia de la API de BigQuery para Node.js.

Ver en GitHub Comentarios

// Import the Google Cloud client libraries
const {BigQuery} = require('@google-cloud/bigquery');
const {Storage} = require('@google-cloud/storage');

// Instantiate clients
const bigquery = new BigQuery();
const storage = new Storage();

/**
 * This sample loads the ORC file at
 * https://storage.googleapis.com/cloud-samples-data/bigquery/us-states/us-states.orc
 *
 * TODO(developer): Replace the following lines with the path to your file.
 */
const bucketName = 'cloud-samples-data';
const filename = 'bigquery/us-states/us-states.orc';

async function loadTableGCSORC() {
  // Imports a GCS file into a table with ORC source format.

  /**
   * TODO(developer): Uncomment the following line before running the sample.
   */
  // const datasetId = 'my_dataset';
  // const tableId = 'my_table'

  // Configure the load job. For full list of options, see:
  // https://cloud.google.com/bigquery/docs/reference/rest/v2/Job#JobConfigurationLoad
  const metadata = {
    sourceFormat: 'ORC',
    location: 'US',
  };

  // Load data from a Google Cloud Storage file into the table
  const [job] = await bigquery
    .dataset(datasetId)
    .table(tableId)
    .load(storage.bucket(bucketName).file(filename), metadata);

  // load() waits for the job to finish
  console.log(`Job ${job.id} completed.`);

  // Check the job's status for errors
  const errors = job.status.errors;
  if (errors && errors.length > 0) {
    throw errors;
  }
}

PHP

Antes de probar este ejemplo, sigue las instrucciones de configuración para PHP incluidas en la Guía de inicio rápido: usa bibliotecas cliente. A fin de obtener más información, consulta la documentación de referencia de la API de BigQuery para PHP.

Ver en GitHub Comentarios

use Google\Cloud\BigQuery\BigQueryClient;
use Google\Cloud\Core\ExponentialBackoff;

/** Uncomment and populate these variables in your code */
// $projectId  = 'The Google project ID';
// $datasetId  = 'The BigQuery dataset ID';

// instantiate the bigquery table service
$bigQuery = new BigQueryClient([
    'projectId' => $projectId,
]);
$dataset = $bigQuery->dataset($datasetId);
$table = $dataset->table('us_states');

// create the import job
$gcsUri = 'gs://cloud-samples-data/bigquery/us-states/us-states.orc';
$loadConfig = $table->loadFromStorage($gcsUri)->sourceFormat('ORC');
$job = $table->runJob($loadConfig);
// poll the job until it is complete
$backoff = new ExponentialBackoff(10);
$backoff->execute(function () use ($job) {
    print('Waiting for job to complete' . PHP_EOL);
    $job->reload();
    if (!$job->isComplete()) {
        throw new Exception('Job has not yet completed', 500);
    }
});
// check if the job has errors
if (isset($job->info()['status']['errorResult'])) {
    $error = $job->info()['status']['errorResult']['message'];
    printf('Error running job: %s' . PHP_EOL, $error);
} else {
    print('Data imported successfully' . PHP_EOL);
}

Python

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

Ver en GitHub Comentarios

# from google.cloud import bigquery
# client = bigquery.Client()
# dataset_id = 'my_dataset'

dataset_ref = client.dataset(dataset_id)
job_config = bigquery.LoadJobConfig()
job_config.source_format = bigquery.SourceFormat.ORC
uri = "gs://cloud-samples-data/bigquery/us-states/us-states.orc"

load_job = client.load_table_from_uri(
    uri, dataset_ref.table("us_states"), job_config=job_config
)  # API request
print("Starting job {}".format(load_job.job_id))

load_job.result()  # Waits for table load to complete.
print("Job finished.")

destination_table = client.get_table(dataset_ref.table("us_states"))
print("Loaded {} rows.".format(destination_table.num_rows))

Ruby

Antes de probar este ejemplo, sigue las instrucciones de configuración para Ruby incluidas en la Guía de inicio rápido: usa bibliotecas cliente. A fin de obtener más información, consulta la documentación de referencia de la API de BigQuery para Ruby.

Ver en GitHub Comentarios

require "google/cloud/bigquery"

def load_table_gcs_orc dataset_id = "your_dataset_id"
  bigquery = Google::Cloud::Bigquery.new
  dataset  = bigquery.dataset dataset_id
  gcs_uri  = "gs://cloud-samples-data/bigquery/us-states/us-states.orc"
  table_id = "us_states"

  load_job = dataset.load_job table_id, gcs_uri, format: "orc"
  puts "Starting job #{load_job.job_id}"

  load_job.wait_until_done!  # Waits for table load to complete.
  puts "Job finished."

  table = dataset.table(table_id)
  puts "Loaded #{table.rows_count} rows to table #{table.id}"
end

Adjunta datos ORC a una tabla o reemplaza sus datos

Puedes cargar datos adicionales en una tabla desde los archivos de origen o cuando agregas los resultados de la consulta.

En la consola y en la IU web clásica de BigQuery, usa la opción de Preferencia de escritura (Write preference) para especificar qué acción tomar cuando cargues datos desde un archivo de origen o desde un resultado de consulta.

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

Opción de Console	Opción de IU web clásica	Marca 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 (Append to table)	Agregar a la tabla	`--noreplace` o `--replace=false`; si no se especifica `--[no]replace`, la opción predeterminada es agregar	`WRITE_APPEND`	Agrega los datos al final de la tabla (predeterminado).
Reemplazar tabla (Overwrite table)	Reemplazar tabla	`--replace` o `--replace=true`	`WRITE_TRUNCATE`	Borra todos los datos existentes de una tabla antes de escribir los datos nuevos.

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

Tienes las siguientes opciones para reemplazar una tabla o agregarle datos:

Usar Cloud Console o la IU web clásica
Usar el comando bq load de la CLI
Realizar una llamada al método jobs.insert de la API y configurar un trabajo de load
Usar bibliotecas cliente

Para agregar datos ORC a una tabla o reemplazar sus valores con estos, sigue los pasos a continuación:

Console

Abre la IU web de BigQuery en Cloud Console.
Ir a Cloud Console
En el panel de navegación, en la sección Recursos (Resources), expande tu proyecto y selecciona un conjunto de datos.
En el lado derecho de la ventana, en el panel de detalles, haz clic en Crear tabla (Create table). El proceso para agregar y reemplazar datos en un trabajo de carga es el mismo que el de crear una tabla en un trabajo de carga.
En la sección Fuente (Source) de la página Crear tabla (Create table), haz lo siguiente:
- En Crear tabla desde (Create table from), selecciona Cloud Storage.
- En el campo de origen, busca o ingresa el URI de Cloud Storage. Ten en cuenta que no puedes incluir varios URI en la IU web de BigQuery, pero sí se admiten comodines. El depósito de Cloud Storage debe encontrarse en la misma ubicación que el conjunto de datos que contiene la tabla a la que agregas datos o que reemplazas.
- En Formato de archivo (File format), selecciona ORC.
En la sección Destino (Destination) de la página Crear tabla (Create table), haz lo siguiente:
- En Nombre del conjunto de datos (Dataset name), selecciona el conjunto de datos que corresponda.
- En el campo Nombre de la tabla (Table name), ingresa el nombre de la tabla a la que quieres agregar datos o que quieres reemplazar en BigQuery.
- Verifica que Tipo de tabla (Table type) esté establecido en Tabla nativa (Native table).
En la sección Esquema (Schema), no es necesaria ninguna acción. El esquema se describe de forma automática en los archivos ORC.

Nota: Es posible modificar el esquema de la tabla cuando la reemplazas o le agregas datos. Para obtener más información sobre los cambios de esquema compatibles durante una operación de carga, consulta Modifica esquemas de tablas.
En Configuración de partición y agrupamiento en clústeres (Partition and cluster settings), deja los valores predeterminados. No puedes agregar datos a una tabla ni reemplazarla para convertirla en una tabla particionada o agrupada en clústeres; Cloud Console no admite agregar datos a tablas particionadas o agrupadas en clústeres ni reemplazarlas en un trabajo de carga.
Haz clic en Opciones avanzadas (Advanced options).
- En Preferencia de escritura (Write preference), elige Agregar a la tabla (Append to table) o Reemplazar tabla (Overwrite table).
- En Cantidad de errores permitidos: (Number of errors allowed), acepta el valor predeterminado de 0 o ingresa la cantidad máxima de filas con errores que pueden ignorarse. Si la cantidad de filas con errores excede este valor, el trabajo generará un mensaje invalid y fallará.
- En Valores desconocidos (Unknown values), desmarca la opción Ignorar valores desconocidos (Ignore unknown values). Esta opción se aplica solo a los archivos CSV y JSON.
- En Encriptación (Encryption), haz clic en Clave administrada por el cliente (Customer-managed key) para usar una clave de Cloud Key Management Service. Si dejas establecida la configuración Clave administrada por Google (Google-managed key), BigQuery encripta los datos en reposo.
Haz clic en Crear tabla (Create table).

IU clásica

Ve a la IU web de BigQuery.
Ir a la IU web de BigQuery
En el panel de navegación, coloca el cursor sobre un conjunto de datos, haz clic en el ícono de flecha hacia abajo y, luego, en Crear tabla nueva (Create new table). El proceso para agregar y reemplazar datos en un trabajo de carga es el mismo que el de crear una tabla en un trabajo de carga.
En la sección Datos de origen (Source Data) de la página Crear tabla (Create Table), sigue estos pasos:
- En Ubicación (Location), selecciona Cloud Storage y, en el campo de origen, ingresa el URI de Cloud Storage. Ten en cuenta que no puedes incluir varios URI en la IU, pero sí se admiten comodines. El depósito de Cloud Storage debe encontrarse en la misma ubicación que el conjunto de datos que contiene la tabla que reemplazas o a la que le agregas datos.
- En Formato de archivo (File format), selecciona ORC.
En la página Crear tabla (Create Table), en la sección Tabla de destino (Destination Table), haz 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 agregarle datos o que quieres reemplazar.
- Verifica que Tipo de tabla (Table type) esté establecido en Tabla nativa (Native table).
En la sección Esquema (Schema), no es necesaria ninguna acción. La información del esquema se describe de forma automática en los archivos ORC.

Nota: Es posible modificar el esquema de la tabla cuando la reemplazas o le agregas datos. Para obtener más información sobre los cambios de esquema compatibles durante una operación de carga, consulta Modifica esquemas de tablas.
En la sección Opciones (Options), sigue estos pasos:
- En Cantidad de errores permitidos: (Number of errors allowed), acepta el valor predeterminado de 0 o ingresa la cantidad máxima de filas con errores que pueden ignorarse. Si la cantidad de filas con errores excede este valor, el trabajo generará un mensaje invalid y fallará.
- En Preferencia de escritura (Write preference), elige Agregar a la tabla (Append to table) o Reemplazar tabla (Overwrite table).
- Deja los valores predeterminados en Tipo de partición (Partitioning Type), Campo de partición (Partitioning Field), Exigir filtro de partición (Require partition filter) y Campos de agrupamiento en clústeres (Clustering Fields). No puedes agregar datos a una tabla ni reemplazarla para convertirla en una tabla particionada o agrupada en clústeres; la IU web no admite agregar datos a tablas particionadas o agrupadas en clústeres ni reemplazarlas en un trabajo de carga.
- En Encriptación de destino (Destination encryption), elige Encriptación administrada por el cliente (Customer-managed encryption) para encriptar la tabla con una clave de Cloud Key Management Service. Si dejas la configuración Default, BigQuery encripta los datos en reposo con una clave administrada por Google.
Haz clic en Crear tabla (Create Table).

CLI

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, se agregan datos de manera predeterminada. Proporciona la marca --source_format y configúrala en ORC. Debido a que los esquemas ORC se recuperan de manera automática de los datos de origen autodescriptivos, no necesitas proporcionar una definición de esquema.

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

Las siguientes son otras marcas opcionales:

--max_bad_records: Un número entero que especifica la cantidad máxima de registros incorrectos permitidos antes de que falle todo el trabajo. El valor predeterminado es 0. Como máximo, se muestran cinco errores de cualquier tipo, sin importar el valor --max_bad_records.
--destination_kms_key: La clave de Cloud KMS para la encriptación de los datos de la tabla.

bq --location=location load \
--[no]replace \
--source_format=format \
dataset.table \
path_to_source

Donde:

location es tu ubicación. La marca --location es opcional. Puedes configurar un valor predeterminado para la ubicación con el archivo .bigqueryrc.
format es ORC.
dataset es un conjunto de datos existente.
table es el nombre de la tabla en la que cargas los datos.
path_to_source es un URI de Cloud Storage completamente calificado o una lista de URI separados por comas. También se admiten comodines.

Ejemplos:

Con el siguiente comando, se cargan datos de gs://mybucket/mydata.orc y se reemplazan los datos de una tabla llamada mytable en mydataset.

    bq load \
    --replace \
    --source_format=ORC \
    mydataset.mytable \
    gs://mybucket/mydata.orc

Con el siguiente comando, se cargan datos de gs://mybucket/mydata.orc y se adjuntan datos a una tabla llamada mytable en mydataset.

    bq load \
    --noreplace \
    --source_format=ORC \
    mydataset.mytable \
    gs://mybucket/mydata.orc

Para obtener información sobre cómo agregar datos a tablas particionadas o reemplazarlos con la CLI, consulta la sección sobre cómo reemplazar tablas particionadas o agregarles datos.

API

Crea un trabajo load que apunte a los datos de origen en Cloud Storage.
Especifica tu ubicación en la propiedad location de la sección jobReference del recurso de trabajo (opcional).
La propiedad source URIs debe estar completamente calificada en el formato gs://bucket/object. Puedes incluir varios URI en una lista separada por comas. Ten en cuenta que también se admiten comodines.
Para especificar el formato de los datos, establece la propiedad configuration.load.sourceFormat en ORC.
Para especificar la preferencia de escritura, configura la propiedad configuration.load.writeDisposition como WRITE_TRUNCATE o WRITE_APPEND.

C#

Ver en GitHub Comentarios


using Google.Apis.Bigquery.v2.Data;
using Google.Cloud.BigQuery.V2;
using System;

public class BigQueryLoadTableGcsOrcTruncate
{
    public void LoadTableGcsOrcTruncate(
        string projectId = "your-project-id",
        string datasetId = "your_dataset_id",
        string tableId = "your_table_id"
    )
    {
        BigQueryClient client = BigQueryClient.Create(projectId);
        var gcsURI = "gs://cloud-samples-data/bigquery/us-states/us-states.orc";
        var dataset = client.GetDataset(datasetId);
        TableReference destinationTableRef = dataset.GetTableReference(
            tableId: "us_states");
        // Create job configuration
        var jobOptions = new CreateLoadJobOptions()
        {
            SourceFormat = FileFormat.Orc,
            WriteDisposition = WriteDisposition.WriteTruncate
        };
        // Create and run job
        var loadJob = client.CreateLoadJob(
            sourceUri: gcsURI,
            destination: destinationTableRef,
            // Pass null as the schema because the schema is inferred when
            // loading Orc data
            schema: null, options: jobOptions);
        loadJob.PollUntilCompleted();  // Waits for the job to complete.
        // Display the number of rows uploaded
        BigQueryTable table = client.GetTable(destinationTableRef);
        Console.WriteLine(
            $"Loaded {table.Resource.NumRows} rows to {table.FullyQualifiedId}");
    }
}

Go

Ver en GitHub Comentarios

import (
	"context"
	"fmt"

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

// importORCTruncate demonstrates loading Apache ORC data from Cloud Storage into a table
// and overwriting/truncating existing data in the table.
func importORCTruncate(projectID, datasetID, tableID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	// tableID := "mytable"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}

	gcsRef := bigquery.NewGCSReference("gs://cloud-samples-data/bigquery/us-states/us-states.orc")
	gcsRef.SourceFormat = bigquery.ORC
	loader := client.Dataset(datasetID).Table(tableID).LoaderFrom(gcsRef)
	// Default for import jobs is to append data to a table.  WriteTruncate
	// specifies that existing data should instead be replaced/overwritten.
	loader.WriteDisposition = bigquery.WriteTruncate

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

	if status.Err() != nil {
		return fmt.Errorf("job completed with error: %v", status.Err())
	}
	return nil
}

Node.js

Ver en GitHub Comentarios

// Import the Google Cloud client libraries
const {BigQuery} = require('@google-cloud/bigquery');
const {Storage} = require('@google-cloud/storage');

// Instantiate the clients
const bigquery = new BigQuery();
const storage = new Storage();

/**
 * This sample loads the CSV file at
 * https://storage.googleapis.com/cloud-samples-data/bigquery/us-states/us-states.csv
 *
 * TODO(developer): Replace the following lines with the path to your file.
 */
const bucketName = 'cloud-samples-data';
const filename = 'bigquery/us-states/us-states.orc';

async function loadORCFromGCSTruncate() {
  /**
   * Imports a GCS file into a table and overwrites
   * table data if table already exists.
   */

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const datasetId = "my_dataset";
  // const tableId = "my_table";

  // Configure the load job. For full list of options, see:
  // https://cloud.google.com/bigquery/docs/reference/rest/v2/Job#JobConfigurationLoad
  const metadata = {
    sourceFormat: 'ORC',
    // Set the write disposition to overwrite existing table data.
    writeDisposition: 'WRITE_TRUNCATE',
    location: 'US',
  };

  // Load data from a Google Cloud Storage file into the table
  const [job] = await bigquery
    .dataset(datasetId)
    .table(tableId)
    .load(storage.bucket(bucketName).file(filename), metadata);
  // load() waits for the job to finish
  console.log(`Job ${job.id} completed.`);

  // Check the job's status for errors
  const errors = job.status.errors;
  if (errors && errors.length > 0) {
    throw errors;
  }
}

PHP

Ver en GitHub Comentarios

use Google\Cloud\BigQuery\BigQueryClient;
use Google\Cloud\Core\ExponentialBackoff;

/** Uncomment and populate these variables in your code */
// $projectId = 'The Google project ID';
// $datasetId = 'The BigQuery dataset ID';
// $tableID = 'The BigQuery table ID';

// instantiate the bigquery table service
$bigQuery = new BigQueryClient([
    'projectId' => $projectId,
]);
$table = $bigQuery->dataset($datasetId)->table($tableId);

// create the import job
$gcsUri = 'gs://cloud-samples-data/bigquery/us-states/us-states.orc';
$loadConfig = $table->loadFromStorage($gcsUri)->sourceFormat('ORC')->writeDisposition('WRITE_TRUNCATE');
$job = $table->runJob($loadConfig);

// poll the job until it is complete
$backoff = new ExponentialBackoff(10);
$backoff->execute(function () use ($job) {
    print('Waiting for job to complete' . PHP_EOL);
    $job->reload();
    if (!$job->isComplete()) {
        throw new Exception('Job has not yet completed', 500);
    }
});

// check if the job has errors
if (isset($job->info()['status']['errorResult'])) {
    $error = $job->info()['status']['errorResult']['message'];
    printf('Error running job: %s' . PHP_EOL, $error);
} else {
    print('Data imported successfully' . PHP_EOL);
}

Python

Para reemplazar las filas de una tabla existente, configura la propiedad LoadJobConfig.write_disposition como WRITE_TRUNCATE.

Ver en GitHub Comentarios

# from google.cloud import bigquery
# client = bigquery.Client()
# table_ref = client.dataset('my_dataset').table('existing_table')

job_config = bigquery.LoadJobConfig()
job_config.write_disposition = bigquery.WriteDisposition.WRITE_TRUNCATE
job_config.source_format = bigquery.SourceFormat.ORC
uri = "gs://cloud-samples-data/bigquery/us-states/us-states.orc"
load_job = client.load_table_from_uri(
    uri, table_ref, job_config=job_config
)  # API request
print("Starting job {}".format(load_job.job_id))

load_job.result()  # Waits for table load to complete.
print("Job finished.")

destination_table = client.get_table(table_ref)
print("Loaded {} rows.".format(destination_table.num_rows))

Ruby

Ver en GitHub Comentarios

require "google/cloud/bigquery"

def load_table_gcs_orc_truncate(
    dataset_id = "your_dataset_id",
    table_id   = "your_table_id"
  )
  bigquery = Google::Cloud::Bigquery.new
  dataset  = bigquery.dataset dataset_id
  gcs_uri  = "gs://cloud-samples-data/bigquery/us-states/us-states.orc"

  load_job = dataset.load_job table_id,
                              gcs_uri,
                              format: "orc",
                              write:  "truncate"
  puts "Starting job #{load_job.job_id}"

  load_job.wait_until_done!  # Waits for table load to complete.
  puts "Job finished."

  table = dataset.table(table_id)
  puts "Loaded #{table.rows_count} rows to table #{table.id}"
end

Carga datos ORC con partición de subárbol

BigQuery admite la carga de datos ORC con partición de subárbol almacenados en Cloud Storage y propagará las columnas con partición de subárbol como columnas en la tabla administrada de destino de BigQuery. Para obtener más información, consulta la página sobre cómo cargar datos particionados de forma externa de Cloud Storage.

Conversiones de ORC

BigQuery convierte los tipos de datos ORC en los siguientes tipos de datos de BigQuery:

Tipos básicos

Tipo de datos ORC	Tipo de datos de BigQuery	Notas
boolean	BOOLEAN
byte	INTEGER
short	INTEGER
int	INTEGER
long	INTEGER
float	FLOAT
double	FLOAT
string	STRING	Solo UTF-8
varchar	STRING	Solo UTF-8
char	STRING	Solo UTF-8
binary	BYTES
date	DATE
timestamp	TIMESTAMP	ORC admite la precisión de nanosegundos, pero BigQuery convierte los valores inferiores a microsegundos en microsegundos cuando se leen los datos.
decimal	NUMERIC o STRING	Los tipos NUMERIC consisten en valores numéricos exactos con 38 dígitos de precisión y 9 dígitos decimales de escala. Consulta Tipo NUMERIC para ver más detalles. Si un tipo decimal en un esquema ORC tiene su escala a no más de 9 y su precisión/escala a no más de 29, se convierte en NUMERIC. De lo contrario, se convierte en STRING. Si un tipo decimal se convierte en STRING, se muestra un mensaje de advertencia.

Tipos complejos

Tipo de datos ORC	Tipo de datos de BigQuery	Notas
struct	RECORD	Todos los campos son NULLABLE. Se ignora el orden de los campos. El nombre de un campo debe ser un nombre de columna válido.
map<K,V>	RECORD	Un campo map<K,V> de ORC se convierte en un RECORD repetido que contiene dos campos: una clave con el mismo tipo de datos que K y un valor con el mismo tipo de datos que V. Ambos campos son NULLABLE.
list	repeated fields	Las listas anidadas y de mapas no son compatibles.
union	RECORD	Cuando union solo tiene una variante, se convierte en un campo NULLABLE. De lo contrario, un union se convierte en un RECORD con una lista de campos NULLABLE. Los campos NULLABLE tienen sufijos como field_0, field_1, etcétera. Solo se asigna un valor a uno de estos campos cuando se leen los datos.

Nombres de columnas

Un nombre de columna solo debe contener letras (a-z, A-Z), números (0-9) o guiones bajos (_), y deben comenzar con una letra o un guion bajo. La longitud máxima del nombre de la columna es de 128 caracteres. No se puede usar ninguno de los siguientes prefijos para el nombre de una columna:

_TABLE_
_FILE_
_PARTITION

No se permiten nombres de columna duplicados, incluso si tienen diferencias de mayúsculas y minúsculas. Por ejemplo, una columna llamada Column1 se considera idéntica a una columna con el nombre column1.

Valores `NULL`

Ten en cuenta que en los trabajos de carga, BigQuery ignora los elementos NULL para el tipo compuesto list, ya que de lo contrario se traducirían a elementos ARRAY que no pueden persistir en una tabla (consulta Tipos de datos de SQL estándar para obtener más información).

Para obtener más información sobre los tipos de datos ORC, consulta la página sobre la especificación v1 de Apache ORC™.

Esquemas de ORC

Compresión de ORC

Permisos necesarios

Permisos de BigQuery

Permisos de Cloud Storage

Carga datos ORC en una tabla nueva

Console

IU clásica

CLI

API

C#

Go

Node.js

PHP

Python

Ruby

Adjunta datos ORC a una tabla o reemplaza sus datos

Console

IU clásica

CLI

API

C#

Go

Node.js

PHP

Python

Ruby

Carga datos ORC con partición de subárbol

Conversiones de ORC

Tipos básicos

Tipos complejos

Nombres de columnas

Valores NULL

Enviar comentarios sobre...

Valores `NULL`