Cargar datos de ORC desde Cloud Storage

En esta página se ofrece 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 mucho en el ecosistema de Apache Hadoop.

Cuando cargas datos ORC desde Cloud Storage, puedes hacerlo en una tabla o partición nuevas, o bien puedes añadirlos a una tabla o partición que ya exista o sobrescribirlos. Cuando tus datos se cargan en BigQuery, se convierten al formato de columnas de Capacitor (el 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 segmento de Cloud Storage.

Para obtener información sobre cómo cargar datos ORC desde un archivo local, consulta el artículo Cargar datos en BigQuery desde una fuente de datos local.

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

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:

Permisos obligatorios

Para cargar datos desde un segmento de Cloud Storage, se necesitan los siguientes permisos:

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

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

Crear conjunto de datos

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

Esquemas ORC

Cuando cargas archivos ORC en BigQuery, el esquema de la tabla se obtiene automáticamente de los datos de origen autodescriptivos. Cuando BigQuery obtiene el esquema de los datos de origen, se usa el último archivo por orden alfabético.

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

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

Al ejecutar este comando en la herramienta de línea de comandos bq, se cargan todos los archivos (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 que sean compatibles con la sintaxis de GoogleSQL. Todos los campos del esquema detectado son NULLABLE. Para obtener más información, consulta Conversiones de ORC.

Cuando se cargan varios archivos ORC que tienen esquemas diferentes, los campos idénticos (con el mismo nombre y el mismo nivel de anidación) especificados en varios esquemas deben asignarse al mismo tipo de datos de BigQuery convertido en cada definición de esquema.

Para proporcionar un esquema de tabla al crear tablas externas, define la propiedad referenceFileSchemaUri en la API de BigQuery o el parámetro
--reference_file_schema_uri en la herramienta de línea de comandos bq con la URL del archivo de referencia.

Por ejemplo, --reference_file_schema_uri="gs://mybucket/schema.orc".

Compresión ORC

BigQuery admite los siguientes códecs de compresión para el contenido de los archivos ORC:

  • Zlib
  • Snappy
  • LZO
  • LZ4
  • ZSTD

Los datos de los archivos ORC no permanecen comprimidos después de subirse a BigQuery. El almacenamiento de datos se indica en bytes lógicos o físicos, según el modelo de facturación del almacenamiento de conjuntos de datos. Para obtener información sobre el uso del almacenamiento, consulta la vista INFORMATION_SCHEMA.TABLE_STORAGE.

Cargar datos de ORC en una tabla nueva

Para cargar datos de ORC en una tabla nueva, puedes hacer lo siguiente:

  • Usar la Google Cloud consola
  • Usar el comando bq load de la herramienta de línea de comandos bq
  • Llamar al método de API jobs.insert y configurar un trabajo load
  • Usar las bibliotecas de cliente

Para cargar datos ORC de Cloud Storage en una tabla de BigQuery:

Consola

  1. En la Google Cloud consola, ve a la página BigQuery.

    Ir a BigQuery

  2. En el panel Explorador, expande tu proyecto y selecciona un conjunto de datos.
  3. En la sección Información del conjunto de datos, haz clic en Crear tabla.
  4. En el panel Crear tabla, especifica los siguientes detalles:
    1. En la sección Fuente, selecciona Google Cloud Storage en la lista Crear tabla a partir de. A continuación, siga estos pasos:
      1. Selecciona un archivo del segmento de Cloud Storage o introduce el URI de Cloud Storage. No puedes incluir varias URIs en la consola Google Cloud , pero sí caracteres comodín. El segmento de Cloud Storage debe estar en la misma ubicación que el conjunto de datos que contiene la tabla que quieres crear, añadir o sobrescribir. Seleccionar el archivo de origen para crear una tabla de BigQuery
      2. En Formato de archivo, selecciona ORC.
    2. En la sección Destino, especifica los siguientes detalles:
      1. En Conjunto de datos, selecciona el conjunto de datos en el que quieras crear la tabla.
      2. En el campo Tabla, introduce el nombre de la tabla que quieras crear.
      3. Verifica que el campo Tipo de tabla sea Tabla nativa.
    3. En la sección Esquema, no es necesario que haga nada. El esquema se describe automáticamente en los archivos ORC.
    4. Opcional: Especifica la configuración de partición y clúster. Para obtener más información, consulta los artículos sobre cómo crear tablas con particiones y cómo crear y usar tablas agrupadas en clústeres.
    5. Haz clic en Opciones avanzadas y haz lo siguiente:
      • En Write preference (Preferencia de escritura), deja seleccionada la opción Write if empty (Escribir si está vacía). Con esta opción se crea una tabla y se cargan los datos en ella.
      • Si quieres ignorar los valores de una fila que no estén presentes en el esquema de la tabla, selecciona Valores desconocidos.
      • En Encriptado, haz clic en Clave gestionada por el cliente para usar una clave de Cloud Key Management Service. Si dejas el ajuste Google-managed key, BigQuery cifra los datos en reposo.
    6. Haz clic en Crear tabla.

SQL

Usa la LOAD DATA instrucción DDL. En el siguiente ejemplo se carga un archivo ORC en la nueva tabla mytable:

  1. En la Google Cloud consola, ve a la página BigQuery.

    Ir a BigQuery

  2. En el editor de consultas, introduce la siguiente instrucción:

    LOAD DATA OVERWRITE mydataset.mytable
    FROM FILES (
      format = 'ORC',
      uris = ['gs://bucket/path/file.orc']);

  3. Haz clic en Ejecutar.

Para obtener más información sobre cómo ejecutar consultas, consulta Ejecutar una consulta interactiva.

bq

Usa el comando bq load, especifica ORC como source_format e incluye un URI de Cloud Storage. Puede incluir un solo URI, una lista de URIs separados por comas o un URI que contenga un comodín.

(Opcional) Proporcione la marca --location y asigne el valor a su ubicación.

Otras marcas opcionales son:

  • --time_partitioning_type: habilita la creación de particiones basadas en el tiempo en una tabla y define el tipo de partición. Los valores posibles son HOUR, DAY, MONTH y YEAR. Esta marca es opcional cuando se crea una tabla con particiones en una columna DATE, DATETIME o TIMESTAMP. El tipo de partición predeterminado para la partición basada en tiempo es DAY. No puedes cambiar la especificación de partición de una tabla que ya tengas.
  • --time_partitioning_expiration: número entero que especifica (en segundos) cuándo se debe eliminar una partición basada en el tiempo. El tiempo de caducidad se calcula como la fecha UTC de la partición más el valor entero.
  • --time_partitioning_field: columna DATE o TIMESTAMP que se usa para crear una tabla con particiones. Si se habilita la creación de particiones basadas en tiempo sin este valor, se creará una tabla con particiones por hora de ingestión.
  • --require_partition_filter: cuando se habilita esta opción, los usuarios deben incluir una cláusula WHERE que especifique las particiones que se van a consultar. Si usas este filtro, es posible que rebajes los costes y mejores el rendimiento. Para obtener más información, consulta Requerir un filtro de partición en las consultas.
  • --clustering_fields: lista separada por comas de hasta cuatro nombres de columna que se usa para crear una tabla agrupada en clústeres.
  • --destination_kms_key: la clave de Cloud KMS para cifrar los datos de la tabla.

    Para obtener más información sobre las tablas con particiones, consulta los siguientes artículos:

    Para obtener más información sobre las tablas agrupadas, consulta los siguientes artículos:

    Para obtener más información sobre el cifrado de tablas, consulta los siguientes artículos:

Para cargar datos ORC en BigQuery, introduce 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 definir el valor de la marca como asia-northeast1. Puedes definir un valor predeterminado para la ubicación mediante el archivo.bigqueryrc.
  • format es ORC.
  • dataset es un conjunto de datos.
  • table es el nombre de la tabla en la que se cargan los datos.
  • path_to_source es un URI de Cloud Storage completo o una lista de URIs separados por comas. También se admiten comodines.

Ejemplos:

El siguiente comando carga datos de gs://mybucket/mydata.orc en una tabla llamada mytable en mydataset.

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

El siguiente comando carga datos de gs://mybucket/mydata.orc en una tabla con particiones por tiempo de ingestión llamada mytable en mydataset.

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

El siguiente comando carga datos de gs://mybucket/mydata.orc en una tabla particionada llamada mytable en mydataset. que cuenta con particiones por la columna mytimestamp.

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

El siguiente comando carga datos de varios archivos de 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

El siguiente comando carga datos de varios archivos de gs://mybucket/ en una tabla llamada mytable de mydataset. El comando incluye una lista de URIs de Cloud Storage separados por comas con comodines.

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

API

  1. Crea una tarea load que apunte a los datos de origen en Cloud Storage.

  2. (Opcional) Especifica tu ubicación en la propiedad location de la sección jobReference del recurso de empleo.

  3. La propiedad source URIs debe estar totalmente cualificada y tener el formato gs://bucket/object. Cada URI puede contener un carácter comodín "*".

  4. Especifica el formato de datos ORC asignando el valor ORC a la propiedad sourceFormat.

  5. Para comprobar el estado del trabajo, llama a jobs.get(job_id*), donde job_id es el ID del trabajo devuelto por la solicitud inicial.

    • Si status.state = DONE, el trabajo se ha completado correctamente.
    • Si la propiedad status.errorResult está presente, significa que se ha producido un error en la solicitud y que el objeto incluye información que describe lo que ha fallado. Si una solicitud falla, no se crea ninguna tabla y no se cargan datos.
    • Si no aparece status.errorResult, significa que el trabajo se ha completado correctamente, aunque es posible que se hayan producido algunos errores no graves, como problemas al importar algunas filas. Los errores no críticos se indican en la propiedad status.errors del objeto de trabajo devuelto.

Notas sobre la API:

  • Las tareas de carga son atómicas y coherentes: si una tarea de carga falla, no habrá datos disponibles, y si se completa correctamente, todos los datos estarán disponibles.

  • Como práctica recomendada, genera un ID único y pásalo como jobReference.jobId al llamar a jobs.insert para crear un trabajo de carga. Este enfoque es más sólido ante fallos de red, ya que el cliente puede sondear o volver a intentar la operación con el ID de trabajo conocido.

  • Llamar a jobs.insert en un ID de trabajo determinado es idempotente. Puedes volver a intentarlo tantas veces como quieras con el mismo ID de trabajo y, como máximo, una de esas operaciones se completará correctamente.

C#

Antes de probar este ejemplo, sigue las C#instrucciones de configuración de la guía de inicio rápido de BigQuery con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API C# de BigQuery.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de cliente.


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 = loadJob.PollUntilCompleted().ThrowOnAnyError();  // 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 Goinstrucciones de configuración de la guía de inicio rápido de BigQuery con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API Go de BigQuery.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de cliente.

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)
	}
	defer client.Close()

	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
}

Java

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Field;
import com.google.cloud.bigquery.FormatOptions;
import com.google.cloud.bigquery.Job;
import com.google.cloud.bigquery.JobInfo;
import com.google.cloud.bigquery.LoadJobConfiguration;
import com.google.cloud.bigquery.Schema;
import com.google.cloud.bigquery.StandardSQLTypeName;
import com.google.cloud.bigquery.TableId;

// Sample to load ORC data from Cloud Storage into a new BigQuery table
public class LoadOrcFromGCS {

  public static void runLoadOrcFromGCS() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    String sourceUri = "gs://cloud-samples-data/bigquery/us-states/us-states.orc";
    Schema schema =
        Schema.of(
            Field.of("name", StandardSQLTypeName.STRING),
            Field.of("post_abbr", StandardSQLTypeName.STRING));
    loadOrcFromGCS(datasetName, tableName, sourceUri, schema);
  }

  public static void loadOrcFromGCS(
      String datasetName, String tableName, String sourceUri, Schema schema) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      TableId tableId = TableId.of(datasetName, tableName);
      LoadJobConfiguration loadConfig =
          LoadJobConfiguration.newBuilder(tableId, sourceUri, FormatOptions.orc())
              .setSchema(schema)
              .build();

      // Load data from a GCS ORC file into the table
      Job job = bigquery.create(JobInfo.of(loadConfig));
      // Blocks until this load table job completes its execution, either failing or succeeding.
      job = job.waitFor();
      if (job.isDone() && job.getStatus().getError() == null) {
        System.out.println("ORC from GCS successfully added during load append job");
      } else {
        System.out.println(
            "BigQuery was unable to load into the table due to an error:"
                + job.getStatus().getError());
      }
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Column not added during load append \n" + e.toString());
    }
  }
}

Node.js

Antes de probar este ejemplo, sigue las Node.jsinstrucciones de configuración de la guía de inicio rápido de BigQuery con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API Node.js de BigQuery.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de cliente.

// 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 PHPinstrucciones de configuración de la guía de inicio rápido de BigQuery con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API PHP de BigQuery.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de cliente.

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 Pythoninstrucciones de configuración de la guía de inicio rápido de BigQuery con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API Python de BigQuery.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de cliente.

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.ORC)
uri = "gs://cloud-samples-data/bigquery/us-states/us-states.orc"

load_job = client.load_table_from_uri(
    uri, table_id, job_config=job_config
)  # Make an API request.

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

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

Ruby

Antes de probar este ejemplo, sigue las Rubyinstrucciones de configuración de la guía de inicio rápido de BigQuery con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API Ruby de BigQuery.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de cliente.

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

Añadir datos ORC a una tabla o sobrescribirla

Puedes cargar datos adicionales en una tabla desde archivos de origen o añadiendo resultados de consultas.

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.

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

Opción de consola Marca de la herramienta bq Propiedad de la API de BigQuery Descripción
Escribir si está vacía No compatible WRITE_EMPTY Escribe los datos solo si la tabla está vacía.
Añadir a tabla --noreplace o --replace=false. Si no se especifica --[no]replace, el valor predeterminado es "append". WRITE_APPEND Predeterminado: Añade los datos al final de la tabla.
Sobrescribir tabla --replace o --replace=true WRITE_TRUNCATE Borra todos los datos de una tabla antes de escribir los nuevos datos. Esta acción también elimina el esquema de la tabla, la seguridad a nivel de fila y cualquier clave de Cloud KMS.

Si cargas datos en una tabla, la tarea de carga puede añadir los datos o sobrescribir la tabla.

Puedes añadir datos a una tabla o sobrescribirla de las siguientes formas:

  • Usar la Google Cloud consola
  • Usar el comando bq load de la herramienta de línea de comandos bq
  • Llamar al método de API jobs.insert y configurar un trabajo load
  • Usar las bibliotecas de cliente

Para añadir o sobrescribir una tabla con datos ORC, sigue estos pasos:

Consola

  1. En la Google Cloud consola, ve a la página BigQuery.

    Ir a BigQuery

  2. En el panel Explorador, expande tu proyecto y selecciona un conjunto de datos.
  3. En la sección Información del conjunto de datos, haz clic en Crear tabla.
  4. En el panel Crear tabla, especifica los siguientes detalles:
    1. En la sección Fuente, selecciona Google Cloud Storage en la lista Crear tabla a partir de. A continuación, siga estos pasos:
      1. Selecciona un archivo del segmento de Cloud Storage o introduce el URI de Cloud Storage. No puedes incluir varias URIs en la consola Google Cloud , pero sí caracteres comodín. El segmento de Cloud Storage debe estar en la misma ubicación que el conjunto de datos que contiene la tabla que quieres crear, añadir o sobrescribir. Seleccionar el archivo de origen para crear una tabla de BigQuery
      2. En Formato de archivo, selecciona ORC.
    2. En la sección Destino, especifica los siguientes detalles:
      1. En Conjunto de datos, selecciona el conjunto de datos en el que quieras crear la tabla.
      2. En el campo Tabla, introduce el nombre de la tabla que quieras crear.
      3. Verifica que el campo Tipo de tabla sea Tabla nativa.
    3. En la sección Esquema, no es necesario que haga nada. El esquema se describe automáticamente en los archivos ORC.
    4. Opcional: Especifica la configuración de partición y clúster. Para obtener más información, consulta los artículos sobre cómo crear tablas con particiones y cómo crear y usar tablas agrupadas en clústeres. No puedes convertir una tabla en una tabla particionada o agrupada añadiéndole datos o sobrescribiéndola. La consola de Google Cloud no admite añadir datos a tablas particionadas o agrupadas, ni sobrescribirlas, en una tarea de carga.
    5. Haz clic en Opciones avanzadas y haz lo siguiente:
      • En Preferencia de escritura, elija Añadir a la tabla o Sobrescribir tabla.
      • Si quieres ignorar los valores de una fila que no estén presentes en el esquema de la tabla, selecciona Valores desconocidos.
      • En Encriptado, haz clic en Clave gestionada por el cliente para usar una clave de Cloud Key Management Service. Si dejas el ajuste Google-managed key, BigQuery cifra los datos en reposo.
    6. Haz clic en Crear tabla.

SQL

Usa la LOAD DATA instrucción DDL. En el siguiente ejemplo se añade un archivo ORC a la tabla mytable:

  1. En la Google Cloud consola, ve a la página BigQuery.

    Ir a BigQuery

  2. En el editor de consultas, introduce la siguiente instrucción:

    LOAD DATA INTO mydataset.mytable
    FROM FILES (
      format = 'ORC',
      uris = ['gs://bucket/path/file.orc']);

  3. Haz clic en Ejecutar.

Para obtener más información sobre cómo ejecutar consultas, consulta Ejecutar una consulta interactiva.

bq

Introduce el comando bq load con la marca --replace para sobrescribir la tabla. Usa la marca --noreplace para añadir datos a la tabla. Si no se especifica ninguna marca, el valor predeterminado es añadir datos. Proporciona la marca --source_format y asígnala a ORC. Como los esquemas ORC se obtienen automáticamente de los datos de origen autodescriptivos, no es necesario que proporciones una definición de esquema.

(Opcional) Proporcione la marca --location y asigne el valor a su ubicación.

Otras marcas opcionales son:

  • --destination_kms_key: la clave de Cloud KMS para cifrar 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 definir un valor predeterminado para la ubicación mediante el archivo.bigqueryrc.
  • format es ORC.
  • dataset es un conjunto de datos.
  • table es el nombre de la tabla en la que se cargan los datos.
  • path_to_source es un URI de Cloud Storage completo o una lista de URIs separados por comas. También se admiten comodines.

Ejemplos:

El siguiente comando carga datos de gs://mybucket/mydata.orc y sobrescribe una tabla llamada mytable en mydataset.

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

El siguiente comando carga datos de gs://mybucket/mydata.orc y añade 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 añadir y sobrescribir tablas con particiones mediante la herramienta de línea de comandos bq, consulta el artículo Añadir y sobrescribir datos de tablas con particiones.

API

  1. Crea una tarea load que apunte a los datos de origen en Cloud Storage.

  2. (Opcional) Especifica tu ubicación en la propiedad location de la sección jobReference del recurso de trabajo.

  3. La propiedad source URIs debe estar completa y tener el formato gs://bucket/object. Puedes incluir varios URIs en una lista separada por comas. Ten en cuenta que también se admiten comodines.

  4. Especifica el formato de los datos asignando el valor ORC a la propiedad configuration.load.sourceFormat.

  5. Especifica la preferencia de escritura asignando el valor WRITE_TRUNCATE o WRITE_APPEND a la propiedad configuration.load.writeDisposition.

C#

Antes de probar este ejemplo, sigue las C#instrucciones de configuración de la guía de inicio rápido de BigQuery con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API C# de BigQuery.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de cliente.


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 = loadJob.PollUntilCompleted().ThrowOnAnyError();  // 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 Goinstrucciones de configuración de la guía de inicio rápido de BigQuery con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API Go de BigQuery.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de cliente.

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)
	}
	defer client.Close()

	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
}

Java

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.FormatOptions;
import com.google.cloud.bigquery.Job;
import com.google.cloud.bigquery.JobInfo;
import com.google.cloud.bigquery.LoadJobConfiguration;
import com.google.cloud.bigquery.TableId;

// Sample to overwrite the BigQuery table data by loading a ORC file from GCS
public class LoadOrcFromGcsTruncate {

  public static void runLoadOrcFromGcsTruncate() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    String sourceUri = "gs://cloud-samples-data/bigquery/us-states/us-states.orc";
    loadOrcFromGcsTruncate(datasetName, tableName, sourceUri);
  }

  public static void loadOrcFromGcsTruncate(
      String datasetName, String tableName, String sourceUri) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      TableId tableId = TableId.of(datasetName, tableName);
      LoadJobConfiguration loadConfig =
          LoadJobConfiguration.newBuilder(tableId, sourceUri)
              .setFormatOptions(FormatOptions.orc())
              // Set the write disposition to overwrite existing table data
              .setWriteDisposition(JobInfo.WriteDisposition.WRITE_TRUNCATE)
              .build();

      // Load data from a GCS ORC file into the table
      Job job = bigquery.create(JobInfo.of(loadConfig));
      // Blocks until this load table job completes its execution, either failing or succeeding.
      job = job.waitFor();
      if (job.isDone() && job.getStatus().getError() == null) {
        System.out.println("Table is successfully overwritten by ORC file loaded from GCS");
      } else {
        System.out.println(
            "BigQuery was unable to load into the table due to an error:"
                + job.getStatus().getError());
      }
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Column not added during load append \n" + e.toString());
    }
  }
}

Node.js

Antes de probar este ejemplo, sigue las Node.jsinstrucciones de configuración de la guía de inicio rápido de BigQuery con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API Node.js de BigQuery.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de cliente.

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

Antes de probar este ejemplo, sigue las PHPinstrucciones de configuración de la guía de inicio rápido de BigQuery con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API PHP de BigQuery.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de cliente.

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 Pythoninstrucciones de configuración de la guía de inicio rápido de BigQuery con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API Python de BigQuery.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de cliente.

Para sustituir las filas de una tabla, define la propiedad LoadJobConfig.write_disposition en WRITE_TRUNCATE.
import io

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(
    schema=[
        bigquery.SchemaField("name", "STRING"),
        bigquery.SchemaField("post_abbr", "STRING"),
    ],
)

body = io.BytesIO(b"Washington,WA")
client.load_table_from_file(body, table_id, job_config=job_config).result()
previous_rows = client.get_table(table_id).num_rows
assert previous_rows > 0

job_config = bigquery.LoadJobConfig(
    write_disposition=bigquery.WriteDisposition.WRITE_TRUNCATE,
    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_id, job_config=job_config
)  # Make an API request.

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

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

Ruby

Antes de probar este ejemplo, sigue las Rubyinstrucciones de configuración de la guía de inicio rápido de BigQuery con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API Ruby de BigQuery.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de cliente.

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

Cargar datos ORC con particiones de Hive

BigQuery permite cargar datos ORC particionados de Hive almacenados en Cloud Storage y rellena las columnas de partición de Hive como columnas en la tabla gestionada de BigQuery de destino. Para obtener más información, consulta el artículo Cargar datos con particiones externas desde Cloud Storage.

Conversiones de ORC

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

Tipos primitivos

Tipo de datos de ORC Tipo de datos de BigQuery Notas
booleano BOOLEAN
byte INTEGER
corto INTEGER
int INTEGER
long INTEGER
flotante FLOAT
doble FLOAT
cadena STRING Solo UTF-8
varchar STRING Solo UTF-8
char STRING Solo UTF-8
binario BYTES
fecha FECHA Si se intenta convertir cualquier valor de los datos ORC que sea inferior a -719162 días o superior a 2932896 días, se devuelve un error invalid date value. Si esto le afecta, póngase en contacto con el equipo de Asistencia para que convierta los valores no admitidos al valor mínimo de BigQuery, 0001-01-01, o al valor máximo, 9999-12-31, según corresponda.
timestamp TIMESTAMP

ORC admite una precisión de nanosegundos, pero BigQuery convierte los valores inferiores a microsegundos en microsegundos cuando se leen los datos.

Si se intenta convertir cualquier valor de los datos ORC que sea inferior a -719162 días o superior a 2932896 días, se devuelve un error invalid date value. Si esto le afecta, póngase en contacto con el equipo de Asistencia para que convierta los valores no admitidos al valor mínimo de BigQuery (0001-01-01) o al valor máximo (9999-12-31), según corresponda.

decimal NUMERIC, BIGNUMERIC o STRING Consulta Tipo decimal.

Tipo decimal

Los tipos lógicos Decimal se pueden convertir en tipos NUMERIC, BIGNUMERIC o STRING. El tipo convertido depende de los parámetros de precisión y escala del tipo lógico decimal y de los tipos de destino decimales especificados. Especifica el tipo de destino decimal de la siguiente manera:

Tipos complejos

Tipo de datos de ORC Tipo de datos de BigQuery Notas
tipo STRUCT RECORD
  • Todos los campos pueden ser NULL.
  • No se tiene en cuenta el orden de los campos.
  • El nombre de un campo debe ser un nombre de columna válido.
map<K,V> RECORD Un campo de mapa ORC<K,V> se convierte en un RECORD repetido que contiene dos campos: una clave del mismo tipo de datos que K y un valor del mismo tipo de datos que V. Ambos campos son NULLABLE.
list campos repetidos No se admiten listas anidadas ni listas de mapas.
unión RECORD
  • Si una unión solo tiene una variante, se convierte en un campo NULLABLE.
  • De lo contrario, una unión se convierte en un RECORD con una lista de campos NULLABLE. Los campos NULLABLE tienen sufijos como field_0, field_1, y así sucesivamente. Solo se asigna un valor a uno de estos campos cuando se leen los datos.

Nombres de columna

El nombre de una columna puede contener letras (a-z, A-Z), números (0-9) o guiones bajos (_), y debe empezar por una letra o un guion bajo. Si usa nombres de columna flexibles, BigQuery permite que los nombres de columna empiecen por un número. Tenga cuidado al empezar los nombres de las columnas con un número, ya que el uso de nombres de columnas flexibles con la API Storage Read o la API Storage Write de BigQuery requiere un tratamiento especial. Para obtener más información sobre la compatibilidad con nombres de columna flexibles, consulta el artículo Nombres de columna flexibles.

Los nombres de las columnas tienen una longitud máxima de 300 caracteres. Los nombres de columna no pueden usar ninguno de los siguientes prefijos:

  • _TABLE_
  • _FILE_
  • _PARTITION
  • _ROW_TIMESTAMP
  • __ROOT__
  • _COLIDENTIFIER

No se permiten nombres de columna duplicados, aunque se distinga entre mayúsculas y minúsculas. Por ejemplo, una columna llamada Column1 se considera idéntica a una columna llamada column1. Para obtener más información sobre las reglas de nomenclatura de columnas, consulta Nombres de columna en la referencia de GoogleSQL.

Si el nombre de una tabla (por ejemplo, test) es el mismo que el de una de sus columnas (por ejemplo, test), la expresión SELECT interpreta la columna test como un STRUCT que contiene todas las demás columnas de la tabla. Para evitar esta colisión, utiliza uno de los siguientes métodos:

  • No uses el mismo nombre para una tabla y sus columnas.

  • Asigna otro alias a la tabla. Por ejemplo, la siguiente consulta asigna el alias de tabla t a la tabla project1.dataset.test:

    SELECT test FROM project1.dataset.test AS t;
    
  • Incluya el nombre de la tabla cuando haga referencia a una columna. Por ejemplo:

    SELECT test.test FROM project1.dataset.test;
    

Nombres de columna flexibles

Ahora tiene más flexibilidad a la hora de asignar nombres a las columnas, incluido un acceso ampliado a caracteres de idiomas distintos del inglés, así como a símbolos adicionales. Asegúrate de usar el carácter de acento grave (`) para incluir los nombres de columna flexibles si son identificadores entre comillas.

Los nombres de columna flexibles admiten los siguientes caracteres:

  • Cualquier letra de cualquier idioma, representada por la expresión regular Unicode \p{L}.
  • Cualquier carácter numérico en cualquier idioma representado por la expresión regular Unicode \p{N}.
  • Cualquier carácter de puntuación de conector, incluidos los guiones bajos, tal como se representa en la expresión regular Unicode \p{Pc}.
  • Un guion o una raya representados por la expresión regular Unicode \p{Pd}.
  • Cualquier marca que acompañe a otro carácter, tal como se representa en la expresión regular Unicode \p{M}. Por ejemplo, acentos, diéresis o recuadros.
  • Los siguientes caracteres especiales:
    • Un ampersand (&) representado por la expresión regular Unicode \u0026.
    • El signo de porcentaje (%) representado por la expresión regular Unicode \u0025.
    • Un signo igual (=) representado por la expresión regular Unicode \u003D.
    • Un signo más (+) representado por la expresión regular Unicode \u002B.
    • Dos puntos (:) representados por la expresión regular Unicode \u003A.
    • Un apóstrofo (') representado por la expresión regular Unicode \u0027.
    • Signo menor que (<) representado por la expresión regular Unicode \u003C.
    • El signo mayor que (>) representado por la expresión regular Unicode \u003E.
    • Un signo de número (#) representado por la expresión regular Unicode \u0023.
    • Una línea vertical (|) representada por la expresión regular Unicode \u007c.
    • Espacio en blanco.

Los nombres de columna flexibles no admiten los siguientes caracteres especiales:

  • Un signo de exclamación (!) representado por la expresión regular Unicode \u0021.
  • Una comilla (") representada por la expresión regular Unicode \u0022.
  • El símbolo del dólar ($) representado por la expresión regular Unicode \u0024.
  • Un paréntesis de apertura (() representado por la expresión regular Unicode \u0028.
  • Un paréntesis de cierre ()) representado por la expresión regular Unicode \u0029.
  • Un asterisco (*) representado por la expresión regular Unicode \u002A.
  • Una coma (,) representada por la expresión regular Unicode \u002C.
  • Un punto (.) representado por la expresión regular Unicode \u002E. Los puntos no se sustituyen por guiones bajos en los nombres de las columnas de los archivos Parquet cuando se usa un mapa de caracteres de nombres de columna. Para obtener más información, consulta las limitaciones de las columnas flexibles.
  • Una barra (/) representada por la expresión regular Unicode \u002F.
  • Un punto y coma (;) representado por la expresión regular Unicode \u003B.
  • Un signo de interrogación (?) representado por la expresión regular Unicode \u003F.
  • Una arroba (@) representada por la expresión regular Unicode \u0040.
  • Un corchete de apertura ([) representado por la expresión regular Unicode \u005B.
  • Una barra invertida (\) representada por la expresión regular Unicode \u005C.
  • Un corchete de cierre (]) representado por la expresión regular Unicode \u005D.
  • Un acento circunflejo (^) representado por la expresión regular Unicode \u005E.
  • Un acento grave (`) representado por la expresión regular Unicode \u0060.
  • Una llave de apertura {{) representada por la expresión regular Unicode \u007B.
  • Una llave de cierre (}) representada por la expresión regular Unicode \u007D.
  • Una virgulilla (~) representada por la expresión regular Unicode \u007E.

Para obtener más directrices, consulta Nombres de columna.

La API Storage Read de BigQuery y la API Storage Write de BigQuery admiten los caracteres de columna ampliados. Para usar la lista ampliada de caracteres Unicode con la API Storage Read de BigQuery, debes definir una marca. Puede usar el atributo displayName para obtener el nombre de la columna. En el siguiente ejemplo se muestra cómo definir una marca con el cliente de Python:

from google.cloud.bigquery_storage import types
requested_session = types.ReadSession()

#set avro serialization options for flexible column.
options = types.AvroSerializationOptions()
options.enable_display_name_attribute = True
requested_session.read_options.avro_serialization_options = options

Para usar la lista ampliada de caracteres Unicode con la API Storage Write de BigQuery, debes proporcionar el esquema con la notación column_name, a menos que uses el objeto de escritura JsonStreamWriter. En el siguiente ejemplo se muestra cómo proporcionar el esquema:

syntax = "proto2";
package mypackage;
// Source protos located in github.com/googleapis/googleapis
import "google/cloud/bigquery/storage/v1/annotations.proto";

message FlexibleSchema {
  optional string item_name_column = 1
  [(.google.cloud.bigquery.storage.v1.column_name) = "name-列"];
  optional string item_description_column = 2
  [(.google.cloud.bigquery.storage.v1.column_name) = "description-列"];
}

En este ejemplo, item_name_column y item_description_column son nombres de marcadores de posición que deben cumplir la convención de nomenclatura de protocol buffer. Ten en cuenta que las anotaciones column_name siempre tienen prioridad sobre los nombres de los marcadores de posición.

Limitaciones

NULL valores

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

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