Carga 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 de código abierto orientado a columnas cuyo uso está generalizado en el ecosistema de Apache Hadoop.

Cuando cargas datos ORC de Cloud Storage, puedes cargar datos en una tabla o partición nuevas, o puedes adjuntar o reemplazar una tabla o partición existentes. 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 acerca de cómo cargar datos ORC de un archivo local, consulta la página sobre cómo carga datos en BigQuery de 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

Este comando carga todos los archivos en un solo comando de 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 del esquema detectado son NULLABLE. Para obtener más información, consulta 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 de BigQuery nuevas o existentes. Si cargas datos desde Cloud Storage, también necesitas permisos para acceder al depósito que contiene tus datos.

Permisos de BigQuery

Como mínimo, se requieren los siguientes permisos para cargar datos en BigQuery. Estos permisos son necesarios si cargas datos en una tabla o partición nueva, si reemplazas una tabla o partición o si adjuntas datos a ellas.

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 de bigquery.jobs.create:

bigquery.user
bigquery.jobUser
bigquery.admin

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

Para obtener más información sobre las funciones de Cloud IAM y los permisos en BigQuery, consulta 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 storage.objectViewer predefinida de Cloud IAM se puede otorgar para proporcionar los permisos storage.objects.get y storage.objects.list.

Carga datos ORC en una tabla nueva

Puedes cargar datos ORC en una tabla nueva:

Mediante GCP Console o la IU web clásica
Mediante el comando bq load de la CLI
Mediante una llamada al método jobs.insert de la API y la configuración de un trabajo load
Mediante las 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 GCP Console.
Ir a GCP Console
En el panel de navegación, en la sección Recursos, 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 página Crear tabla (Create table), en la sección Origen (Source), realiza lo siguiente:
- En Crear una tabla desde (Create table from), selecciona Cloud Storage.
- En el campo de fuente, busca o ingresa el URI de Cloud Storage. Ten en cuenta que no puedes incluir múltiples URI en GCP 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 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.
- Verifica que Tipo de tabla (Table type) esté configurado como Tabla nativa (Native table).
- En el campo Nombre de tabla, ingresa el nombre de la tabla que quieres crear en BigQuery.
En la sección Esquema, no es necesaria ninguna acción. El esquema se describe de forma automática en los archivos ORC.
Para particionar la tabla, elige tus opciones en la Configuración de la partición y el clúster (opcional):
- Para crear una tabla particionada, haz clic en Sin particiones, selecciona Particionar por campo y elige una columna DATE o TIMESTAMP. Esta opción no está disponible si tu esquema no incluye una columna DATE o TIMESTAMP.
- Para crear una tabla particionada por tiempo de transferencia, haz clic en Sin particiones y selecciona Particionar por tiempo de transferencia.
En Filtro de partición, haz clic en el cuadro Requerir filtro de partición para solicitar a los usuarios que incluyan una cláusula WHERE que especifique las particiones que deben consultarse (opcional). Requerir un filtro de partición puede reducir el costo y mejorar el rendimiento. Para obtener más información, visita Consulta tablas particionadas. Esta opción no está disponible si se selecciona Sin particiones.
Para agrupar la tabla en clústeres, en el cuadro Orden de agrupamiento en clústeres, ingresa entre uno y cuatro nombres de campo (opcional). En la actualidad, el agrupamiento en clústeres solo es compatible con tablas particionadas.
Haz clic en Opciones avanzadas (opcional).
- En Preferencia de escritura, deja seleccionado Escribir si está vacío. Con esta opción, se crea una tabla nueva y se cargan tus 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 se producirá un error.
- En Valores desconocidos, deja la opción Ignorar valores desconocidos desmarcada. Esta opción se aplica solo a los archivos CSV y JSON.
- En Encriptación, haz clic en Clave administrada por el cliente para usar una clave de Cloud Key Management Service. Si dejas establecida la configuración Clave administrada por Google, BigQuery encripta los datos en reposo.
Haz clic en Crear tabla.

IU clásica

Ve a la IU web de BigQuery.
Ir a la IU web de BigQuery
En el panel de navegación, pasa el cursor sobre un conjunto de datos, haz clic en el ícono de flecha hacia abajo y, luego, en Crear tabla nueva. El proceso de carga de datos es el mismo que el proceso para crear una tabla vacía.
En la página Crear tabla, en la sección Datos fuente, haz lo siguiente:
- Haz clic en Crear desde fuente.
- En Ubicación, selecciona Cloud Storage y, en el campo de fuente, ingresa el URI de Cloud Storage. Ten en cuenta que no puedes incluir múltiples URI en la IU web de BigQuery, 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 de archivo (File format), selecciona ORC.
En la sección Tabla de destino, realiza lo siguiente:
- En Nombre de tabla, selecciona el conjunto de datos apropiado y, en el campo de nombre de tabla, ingresa el nombre de la tabla que quieres crear en BigQuery.
- Verifica que Tipo de tabla (Table type) esté configurado como Tabla nativa (Native table).
En la sección Esquema, no es necesaria ninguna acción. El esquema se describe de forma automática en los archivos ORC.
En la sección Opciones, sigue estos 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 se producirá un error.
- En Preferencia de escritura, deja seleccionado Escribir si está vacío. Con esta opción, se crea una tabla nueva y se cargan tus datos en ella.
- Para particionar la tabla, haz lo siguiente:
  - En Tipo de partición, haz clic en Ninguno y elige Día.
  - En Campo de partición, realiza las siguientes acciones:
  - Para crear una tabla particionada, elige una columna DATE o TIMESTAMP. Esta opción no está disponible si tu 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 el cuadro Requerir filtro de partición para solicitar a los usuarios que incluyan una cláusula WHERE que especifique las particiones que deben consultarse. Requerir un filtro de partición puede reducir el costo y mejorar el rendimiento. Para obtener más información, visita Consulta tablas particionadas. Esta opción no está disponible si Tipo de partición está configurado como Ninguno.
- Para agrupar la tabla en clústeres, en el cuadro Campos de agrupamiento en clústeres, ingresa entre uno y cuatro nombres de campo.
- En Encriptación de destino, elige Encriptación administrada por el cliente a fin de usar una clave de Cloud Key Management Service para encriptar la tabla. Si dejas la configuración Default, BigQuery encripta los datos en reposo con una clave administrada por Google.
Haz clic en Crear tabla.

CLI

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

Proporciona la marca --location y configura el valor como 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 la partición por 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 creas una tabla particionada en función de una columna DATE o TIMESTAMP.
--time_partitioning_expiration: un número entero que especifica (en segundos) cuándo se debe borrar una partición por tiempo. El momento 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: las columnas DATE o TIMESTAMP que se usan para crear una tabla particionada. Si la partición por tiempo está habilitada sin este valor, se crea una tabla particionada por tiempo de transferencia.
--require_partition_filter: cuando se habilita esta opción, se requiere que los usuarios incluyan una cláusula WHERE que especifique las particiones que deben consultarse. Requerir un filtro de partición puede reducir el costo y mejorar el rendimiento. Para obtener más información, visita Consulta tablas particionadas.
--clustering_fields: una lista separada por comas de hasta cuatro nombres de columnas que se usan 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 enlaces:
- Cómo crear y usar tablas particionadas
- Cómo crear y usar tablas particionadas por tiempo de transferencia
Para obtener más información sobre las tablas agrupadas en clústeres, consulta el siguiente enlace:
- Cómo crear y usar tablas agrupadas
Para obtener más información sobre la encriptación de tablas, consulta el siguiente enlace:
- 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

En el que:

location es tu ubicación. La marca --location es opcional. Por ejemplo, si usas BigQuery en la región de Tokio, puedes configurar el valor de las marcas en 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 calificado por completo 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 denominada mytable de 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 de 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 denominada mytable de mydataset. La tabla se particiona según 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 en gs://mybucket/ en una tabla llamada mytable de 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 en gs://mybucket/ en una tabla llamada mytable de 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, en la sección jobReference del recurso de trabajo (opcional).
La propiedad de los source URIs debe estar calificada por completo, con el formato gs://bucket/object. Cada URI puede contener un carácter comodín “*”.
Especifica el formato de datos ORC mediante la configuración de la propiedad sourceFormat como ORC.
Para verificar el estado del trabajo, llama a jobs.get(job_id*), en el que job_id es el ID del trabajo que la solicitud inicial muestra.
- Si aparece status.state = DONE, significa que el trabajo se completó con éxito.
- Si la propiedad status.errorResult está presente, la solicitud falló y ese objeto incluirá información que describe qué salió mal. Cuando las solicitudes fallan, 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 no fatales, como problemas cuando se importan algunas filas. Los errores no fatales se enumeran en la propiedad status.errors del objeto de trabajo mostrado.

Notas de API:

Los trabajos de carga son atómicos y coherentes; si un trabajo de carga falla, ninguno de los datos estará disponible, mientras que, si se completa con éxito, todos los datos estarán disponibles.
Se recomienda que generes un ID único y lo pases como jobReference.jobId cuando llames a jobs.insert para crear un trabajo de carga. Este enfoque es más resistente a fallos de la red porque el cliente puede realizar consultas o reintentos con el ID de trabajo conocido.
Una llamada a jobs.insert en un ID de trabajo determinado es idempotente. Puedes reintentar tantas veces como desees en el mismo ID de trabajo y, como máximo, una de esas operaciones tendrá éxito.

C#

Antes de probar esta muestra, sigue las instrucciones de configuración para C# que se encuentran en la Guía de inicio rápido de BigQuery con bibliotecas cliente. Si necesitas 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 de Go incluidas en la Guía de inicio rápido de BigQuery con 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

// To run this sample, you will need to create (or reuse) a context and
// an instance of the bigquery client.  For example:
// import "cloud.google.com/go/bigquery"
// ctx := context.Background()
// client, err := bigquery.NewClient(ctx, "your-project-id")
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())
}

Node.js

Antes de probar esta muestra, sigue las instrucciones de configuración para Node.js que se encuentran en la Guía de inicio rápido de BigQuery con bibliotecas cliente. 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 esta muestra, sigue las instrucciones de configuración de PHP que se encuentran en la Guía de inicio rápido de BigQuery con bibliotecas cliente. 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 de Python incluidas en la Guía de inicio rápido de BigQuery con bibliotecas cliente. A fin de 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 esta muestra, sigue las instrucciones de configuración para Ruby que se encuentran en la Guía de inicio rápido de BigQuery con bibliotecas cliente. 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

Anexa o reemplaza una tabla con datos ORC

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 Write preference (Preferencia de escritura) 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 la IU web clásica	Marcador CLI	Propiedad de la API de BigQuery	Descripción
Escribir si está vacía	Escribir si está vacía	Ninguna	`WRITE_EMPTY`	Solo escribe los datos si la tabla está vacía.
Adjuntar a la tabla	Adjuntar a la tabla	`--noreplace` o `--replace=false`; si no se especifica `--[no]replace`, la opción predeterminada es la de adjuntar	`WRITE_APPEND`	Adjunta los datos al final de la tabla (predeterminado).
Reemplazar tabla	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 adjuntar los datos o reemplazar la tabla.

Puedes adjuntar datos a una tabla o reemplazarla de la siguiente manera:

Mediante GCP Console o la IU web clásica
Mediante el comando bq load de la CLI
Mediante una llamada al método jobs.insert de la API y la configuración de un trabajo load
Mediante las 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 GCP Console.
Ir a GCP Console
En el panel de navegación, en la sección Recursos, 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 adjuntar y reemplazar datos en un trabajo de carga es el mismo que se usa en la creación de tablas en un trabajo de carga.
En la página Crear tabla (Create table), en la sección Origen (Source), realiza lo siguiente:
- En Crear una tabla desde (Create table from), selecciona Cloud Storage.
- En el campo de fuente, busca o ingresa el URI de Cloud Storage. Ten en cuenta que no puedes incluir múltiples URI en la IU web de BigQuery, 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 a la que quieres adjuntar datos o de la que quieres reemplazarlos.
- 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 tabla, ingresa el nombre de la tabla en BigQuery a la que quieres adjuntar datos o reemplazarlos.
- Verifica que Tipo de tabla (Table type) esté configurado como Tabla nativa (Native table).
En la sección Esquema, 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 adjuntas datos a ella o los reemplazas. Para obtener más información sobre los cambios de esquema admitidos durante una operación de carga, consulta Modifica esquemas de tablas.
En Configuración de clústeres y particiones, deja establecidos los valores predeterminados. No puedes convertir una tabla en una tabla particionada o agrupada en clústeres mediante una operación de agregado o reemplazo, y GCP Console no admite adjuntar datos a tablas particionadas o agrupadas en clústeres ni reemplazarlos en un trabajo de carga.
Haz clic en Opciones avanzadas (Advanced options).
- En Preferencia de escritura (Write preference), selecciona 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 se producirá un error.
- En Valores desconocidos, deja la opción Ignorar valores desconocidos desmarcada. Esta opción se aplica solo a los archivos CSV y JSON.
- En Encriptación, haz clic en Clave administrada por el cliente para usar una clave de Cloud Key Management Service. Si dejas establecida la configuración Clave administrada por Google, BigQuery encripta los datos en reposo.
Haz clic en Crear tabla.

IU clásica

Ve a la IU web de BigQuery.
Ir a la IU web de BigQuery
En el panel de navegación, pasa el cursor sobre un conjunto de datos, haz clic en el ícono de flecha hacia abajo y, luego, en Crear tabla nueva. El proceso para adjuntar y reemplazar datos en un trabajo de carga es el mismo que se usa en la creación de tablas en un trabajo de carga.
En la página Crear tabla, en la sección Datos fuente, haz lo siguiente:
- En Ubicación, selecciona Cloud Storage y, en el campo de fuente, ingresa el URI de Cloud Storage. Ten en cuenta que no puedes ingresar múltiples un URI en la IU, 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 a la que quieres adjuntar datos o de la que quieres reemplazarlos.
- En Formato de archivo (File format), selecciona ORC.
En la página Crear tabla, en la sección Tabla de destino, haz lo siguiente:
- En Nombre de tabla, elige el conjunto de datos adecuado y, en el campo de nombre de tabla, ingresa el nombre de la tabla a la que quieres adjuntar datos o de la que quieres reemplazarlos.
- Verifica que Tipo de tabla (Table type) esté configurado como Tabla nativa (Native table).
En la sección Esquema, 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 adjuntas datos a ella o los reemplazas. Para obtener más información sobre los cambios de esquema admitidos durante una operación de carga, consulta Modifica esquemas de tablas.
En la sección Opciones, haz lo siguiente:
- 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 se producirá un error.
- En Preferencia de escritura (Write preference), selecciona Agregar a la tabla (Append to table) o Reemplazar tabla (Overwrite table).
- Deja los valores predeterminados en Tipo de partición, Campo de partición, Requerir filtro de partición y Campos de agrupamiento en clústeres. No se puede convertir una tabla en una tabla particionada o agrupada en clústeres mediante una operación de agregado ni de reemplazo, y la IU web no admite agregar datos a tablas particionadas o agrupadas en clústeres ni reemplazarlos en un trabajo de carga.
- En Encriptación de destino, elige Encriptación administrada por el cliente a fin de usar una clave de Cloud Key Management Service para encriptar la tabla. Si dejas la configuración Default, BigQuery encripta los datos en reposo con una clave administrada por Google.
Haz clic en Crear tabla.

CLI

Ingresa el comando bq load con la marca --replace para reemplazar la tabla. Usa la marca --noreplace para agregar datos a una tabla. Si no se especifica ninguna marca, se agregan datos de manera predeterminada. Proporciona la marca --source_format y configúrala como ORC. Debido a que los esquemas de ORC se recuperan de forma automática a partir de los datos de origen autodescriptivos, no necesitas proporcionar una definición de esquema.

Proporciona la marca --location y configura el valor como 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

En el que:

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 calificado por completo 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 reemplaza una tabla denominada mytable de 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 de mydataset.

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

Para obtener información sobre cómo adjuntar datos a tablas particionadas o reemplazarlos con la CLI, consulta: Anexa y reemplaza datos de tablas particionadas.

API

Crea un trabajo load que apunte a los datos de origen en Cloud Storage.
Especifica tu ubicación en la propiedad location, en la sección jobReference del recurso de trabajo (opcional).
La propiedad de los source URIs debe estar calificada por completo, con el formato gs://bucket/object. Puedes incluir varios URI en una lista separada por comas. Ten en cuenta que también se admiten comodines.
Configura la propiedad configuration.load.sourceFormat como ORC para especificar el formato de datos.
Especifica la preferencia de escritura mediante la configuración de 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

// To run this sample, you will need to create (or reuse) a context and
// an instance of the bigquery client.  For example:
// import "cloud.google.com/go/bigquery"
// ctx := context.Background()
// client, err := bigquery.NewClient(ctx, "your-project-id")
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())
}

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

Antes de probar este ejemplo, sigue las instrucciones de configuración de Python incluidas en la Guía de inicio rápido de BigQuery con bibliotecas cliente. A fin de obtener más información, consulta la documentación de referencia de la API de BigQuery para 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

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 difieren las 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, por el momento, BigQuery ignora los elementos NULL para el tipo compuesto list.

Para obtener más información sobre los tipos de datos ORC, consulta 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

Anexa o reemplaza una tabla con datos ORC

Console

IU clásica

CLI

API

C#

Go

Node.js

PHP

Python

Ruby

Conversiones de ORC

Tipos básicos

Tipos complejos

Nombres de columnas

Valores NULL

Enviar comentarios sobre...

Valores `NULL`