Carga datos de Parquet desde Cloud Storage

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

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

Cuando cargas datos de Parquet desde Cloud Storage, puedes hacerlo en una tabla o partición nuevas, o bien puedes agregar o reemplazar una tabla o partición existente. Cuando los 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 bucket de Cloud Storage.

Para obtener información sobre cómo cargar datos Parquet desde un archivo local, consulta Carga datos desde archivos locales.

Limitaciones

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

• Si la ubicación de tu conjunto de datos está configurada en un valor diferente a la multirregión US, el bucket de Cloud Storage debe estar en la misma región o multirregión que el conjunto de datos.
• BigQuery no garantiza la coherencia de los datos provenientes de fuentes de datos externas. Los cambios en los datos subyacentes mientras se ejecuta una consulta pueden dar como resultado un comportamiento inesperado.

• BigQuery no es compatible con el control de versiones de objetos de Cloud Storage. Si incluyes un número de generación en el URI de Cloud Storage, el trabajo de carga fallará.

• La carga de datos de Parquet sigue la convención de nombres de columnas y no admite nombres flexibles de columnas de forma predeterminada. Para inscribirte en esta vista previa, completa el formulario de inscripción.

• No puedes usar un comodín en el URI de Cloud Storage si alguno de los archivos que se cargarán tiene esquemas diferentes. Cualquier diferencia en la posición de las columnas califica como un esquema diferente.

Requisitos del archivo de entrada

Para evitar errores de resourcesExceeded cuando cargues archivos de Parquet a BigQuery, sigue estos lineamientos:

• Mantén los tamaños de las filas en 50 MB o menos.
• Si los datos de entrada contienen más de 100 columnas, considera reducir el tamaño de la página para que sea más pequeño que el tamaño predeterminado de la página (1 * 1,024 * 1,024 bytes). Esta opción es útil si usas una compresión significativa.

Antes de comenzar

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

Permisos necesarios

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

Permisos para cargar datos a BigQuery

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

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

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

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

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

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

Permisos para subir datos desde Cloud Storage

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

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

Permisos necesarios

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

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

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

Crea un conjunto de datos

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

Esquemas de Parquet

Cuando cargas archivos de Parquet en BigQuery, el esquema de la tabla se recupera automáticamente de los datos de origen de descripción automática. Cuando BigQuery recupera el esquema de los datos de origen, se usa el último archivo en orden alfabético.

Por ejemplo, tienes los siguientes archivos de Parquet en Cloud Storage:

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

Cuando se ejecuta este comando en la herramienta de línea de comandos de bq, se cargan todos los archivos (como una lista separada por comas) y el esquema se deriva de mybucket/01/b.parquet:

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

Cuando cargas varios archivos de Parquet con diferentes esquemas, las columnas idénticas especificadas en múltiples esquemas deben tener el mismo modo en cada definición de esquema.

Cuando BigQuery detecta el esquema, algunos tipos de datos de Parquet se convierten en tipos de datos de BigQuery para que sean compatibles con la sintaxis de GoogleSQL. Para obtener más información, consulta Conversiones de Parquet.

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

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

Compresión de Parquet

BigQuery admite los siguientes códecs de compresión para el contenido del archivo de Parquet:

• GZip
• LZO_1C
• LZO_1X
• LZ4_RAW
• Snappy
• ZSTD

Carga datos Parquet en una tabla nueva

Puedes cargar datos de Parquet en una tabla nueva con una de las siguientes opciones:

• La consola de Google Cloud
• El comando bq load de la herramienta de línea de comandos de bq
• El método de API jobs.insert y la configuración de un trabajo load
• Las bibliotecas cliente

Para cargar datos de Parquet desde Cloud Storage en una tabla nueva de BigQuery, realiza los siguientes pasos:

Console

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

   Ir a BigQuery

2. En el panel Explorador, expande tu proyecto y, luego, elige 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, elige Google Cloud Storage en la lista Crear tabla desde. A continuación, sigue estos pasos:
   1. Elige un archivo del bucket de Cloud Storage o escribe el URI de Cloud Storage. No puedes incluir múltiples URI en la consola de Google Cloud, pero se admiten comodines. El bucket de Cloud Storage debe estar en la misma ubicación que el conjunto de datos que contiene la tabla que deseas crear, agregar o reemplazar.
   2. En Formato del archivo, selecciona Parquet.
2. En la sección Destino, especifica los siguientes detalles:
   1. En Conjunto de datos, elige el conjunto de datos en el que deseas crear la tabla.
   2. En el campo Tabla, escribe el nombre de la tabla que deseas crear.
   3. Verifica que el campo Tipo de tabla esté configurado como Tabla nativa.
3. En la sección Esquema, no es necesaria ninguna acción. El esquema se describe automáticamente en archivos Parquet.
4. Opcional: Especifica Configuración de particiones y clústeres. Para obtener más información, consulta Crea tablas particionadas y Crea y usa tablas agrupadas en clústeres.
5. Haz clic en Opciones avanzadas y haz lo siguiente:
   • En Preferencia de escritura, deja elegido Escribir si está vacía. Con esta opción, se crea una tabla nueva y se cargan los datos en ella.
   • Si deseas ignorar los valores de una fila que no están presentes en el esquema de la tabla, elige Valores desconocidos.
   • 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 del parámetro Clave administrada por Google, BigQuery encripta los datos en reposo.
6. Haz clic en Crear tabla.

Nota: Cuando se cargan datos en una tabla vacía a través de la consola de Google Cloud, no se puede agregar una etiqueta, descripción ni el vencimiento de una tabla ni partición.

Una vez creada la tabla, con la consola de Google Cloud puedes actualizar el vencimiento, la descripción y las etiquetas de la tabla, pero no se puede agregar un vencimiento de la partición. Para obtener más información, consulta Administra tablas.

SQL

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

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

   Ir a BigQuery

2. En el editor de consultas, escribe la siguiente sentencia:

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

3. Haz clic en Ejecutar.

Si deseas obtener información sobre cómo ejecutar consultas, visita Ejecuta una consulta interactiva.

bq

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

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

Las siguientes son otras marcas opcionales:

• --time_partitioning_type: habilita las particiones basadas en el tiempo en una tabla y establece el tipo de partición. Los valores posibles son HOUR, DAY, MONTH y YEAR. Esta marca es opcional cuando se crea una tabla particionada en una columna DATE, DATETIME o TIMESTAMP. El tipo de partición predeterminado para la partición basada en el tiempo es DAY. No puedes cambiar la especificación de partición de una tabla existente.
• --time_partitioning_expiration: Un número entero que especifica (en segundos) cuándo se debe borrar una partición basada en el tiempo. La hora de vencimiento se evalúa según la suma de la fecha de la partición en formato UTC más el valor del número entero.
• --time_partitioning_field: La columna DATE o TIMESTAMP que se usa para crear una tabla particionada. Si la partición basada en el tiempo se habilita sin este valor, se creará una tabla particionada por tiempo de transferencia.
• --require_partition_filter: Cuando se habilita esta opción, se solicita a los usuarios que incluyan una cláusula WHERE que especifique las particiones que se desean consultar. Exigir un filtro de partición puede reducir los costos y mejorar el rendimiento. Para obtener más información, lee Consulta tablas particionadas.
• --clustering_fields: Una lista separada por comas de hasta cuatro nombres de columna que se usa para crear una tabla agrupada en clústeres.

• --destination_kms_key: Es la clave de Cloud KMS para la encriptación de los datos de la tabla.

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

  • Crea tablas particionadas

  Para obtener más información sobre tablas agrupadas, consulta el siguiente artículo:

  • Crea y usa tablas agrupadas

  Para obtener más información sobre la encriptación de tablas, consulta el siguiente artículo:

  • Protege datos con claves de Cloud KMS

Para cargar datos de Parquet en BigQuery, ingresa el siguiente comando:

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

Reemplaza lo siguiente:

• 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 la marca como asia-northeast1. Puedes configurar un valor predeterminado para la ubicación con el archivo .bigqueryrc.
• FORMAT: PARQUET.
• DATASET: Es un conjunto de datos existente.
• TABLE: es el nombre de la tabla en la que se están cargando los datos.
• PATH_TO_SOURCE: Es un URI de Cloud Storage por completo calificado o una lista de URI separados por comas. También se admiten comodines.

Ejemplos:

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

    bq load \
    --source_format=PARQUET \
    mydataset.mytable \
    gs://mybucket/mydata.parquet

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

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

El siguiente comando carga datos de gs://mybucket/mydata.parquet a una tabla particionada llamada mytable en mydataset. La tabla está particionada en la columna mytimestamp.

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

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

    bq load \
    --source_format=PARQUET \
    mydataset.mytable \
    gs://mybucket/mydata*.parquet

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

    bq load \
    --source_format=PARQUET \
    mydataset.mytable \
    "gs://mybucket/00/*.parquet","gs://mybucket/01/*.parquet"

API

1. Crea un trabajo load que apunte a los datos de origen en Cloud Storage.

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

3. La propiedad source URIs debe estar por completo calificada en el formato gs://BUCKET/OBJECT. Cada URI puede contener un carácter comodín “*”.

4. Configura la propiedad sourceFormat como PARQUET para especificar el formato de datos de Parquet.

5. Para verificar el estado del trabajo, llama a jobs.get(JOB_ID*) y reemplaza JOB_ID con el ID del trabajo que devuelve la solicitud inicial.

   • Si se muestra status.state = DONE, el trabajo se completó de forma correcta.
   • Si la propiedad status.errorResult está presente, la solicitud falló y ese objeto incluye información que describe lo que salió mal. Cuando una solicitud falla, no se crea ninguna tabla ni se cargan datos.
   • Si status.errorResult está ausente, el trabajo se completó con éxito, aunque puede haber algunos errores recuperables, como problemas cuando se importan algunas filas. Se enumeran los errores recuperables en la propiedad status.errors del objeto de trabajo que se muestra.

Notas de API:

• Los trabajos de carga son atómicos y coherentes: si uno falla, ninguno de los datos estará disponible, y, si uno se realiza con éxito, todos los datos estarán disponibles.

• Como práctica recomendada, genera un ID único y pásalo como jobReference.jobId cuando llames a jobs.insert para crear un trabajo de carga. Este enfoque es más resistente al fallo de la red porque el cliente puede sondear o reintentar con el ID de trabajo conocido.

• Llamar a jobs.insert en un ID de trabajo determinado es idempotente. Puedes intentar tantas veces como desees en el mismo ID de trabajo y, a lo sumo, una de esas operaciones tendrá éxito.

Go

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

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

import (
	"context"
	"fmt"

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

// importParquet demonstrates loading Apache Parquet data from Cloud Storage into a table.
func importParquet(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.parquet")
	gcsRef.SourceFormat = bigquery.Parquet
	gcsRef.AutoDetect = true
	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

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

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

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;
import java.math.BigInteger;

public class LoadParquet {

  public static void runLoadParquet() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    loadParquet(datasetName);
  }

  public static void loadParquet(String datasetName) {
    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();

      String sourceUri = "gs://cloud-samples-data/bigquery/us-states/us-states.parquet";
      TableId tableId = TableId.of(datasetName, "us_states");

      LoadJobConfiguration configuration =
          LoadJobConfiguration.builder(tableId, sourceUri)
              .setFormatOptions(FormatOptions.parquet())
              .build();

      // For more information on Job see:
      // https://googleapis.dev/java/google-cloud-clients/latest/index.html?com/google/cloud/bigquery/package-summary.html
      // Load the table
      Job job = bigquery.create(JobInfo.of(configuration));

      // Blocks until this load table job completes its execution, either failing or succeeding.
      Job completedJob = job.waitFor();
      if (completedJob == null) {
        System.out.println("Job not executed since it no longer exists.");
        return;
      } else if (completedJob.getStatus().getError() != null) {
        System.out.println(
            "BigQuery was unable to load the table due to an error: \n"
                + job.getStatus().getError());
        return;
      }

      // Check number of rows loaded into the table
      BigInteger numRows = bigquery.getTable(tableId).getNumRows();
      System.out.printf("Loaded %d rows. \n", numRows);

      System.out.println("GCS parquet loaded successfully.");
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("GCS Parquet was not loaded. \n" + e.toString());
    }
  }
}

Node.js

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

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

// 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 Parquet file at
 * https://storage.googleapis.com/cloud-samples-data/bigquery/us-states/us-states.parquet
 *
 * TODO(developer): Replace the following lines with the path to your file.
 */
const bucketName = 'cloud-samples-data';
const filename = 'bigquery/us-states/us-states.parquet';

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

  /**
   * 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: 'PARQUET',
    location: 'US',
  };

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

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

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

PHP

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

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

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.parquet';
$loadConfig = $table->loadFromStorage($gcsUri)->sourceFormat('PARQUET');
$job = $table->runJob($loadConfig);
// poll the job until it is complete
$backoff = new ExponentialBackoff(10);
$backoff->execute(function () use ($job) {
    print('Waiting for job to complete' . PHP_EOL);
    $job->reload();
    if (!$job->isComplete()) {
        throw new Exception('Job has not yet completed', 500);
    }
});
// check if the job has errors
if (isset($job->info()['status']['errorResult'])) {
    $error = $job->info()['status']['errorResult']['message'];
    printf('Error running job: %s' . PHP_EOL, $error);
} else {
    print('Data imported successfully' . PHP_EOL);
}

Python

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

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

Usa el método Client.load_table_from_uri() para iniciar un trabajo de carga desde Cloud Storage. Para usar Parquet, configura la propiedad LoadJobConfig.source_format en la cadena PARQUET y pasa la configuración del trabajo como el argumento job_config para el método load_table_from_uri().

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

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

Agrega o reemplaza una tabla con datos de Parquet

Puedes cargar datos adicionales en una tabla desde archivos de origen o cuando adjuntas resultados de consultas.

En la consola de Google Cloud, usa la opción de Preferencia de escritura para especificar qué acción se debe tomar cuando cargues datos desde un archivo de origen o desde el resultado de una consulta.

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

Opción de Console	Marca de la herramienta de bq	Propiedad de la API de BigQuery	Descripción
Escribir si está vacía	No compatible	WRITE_EMPTY	Solo escribe los datos si la tabla está vacía.
Agregar a la tabla	--noreplace o --replace=false; si no se especifica --[no]replace, la opción predeterminada es agregar	WRITE_APPEND	Agrega los datos al final de la tabla (predeterminado).
Reemplazar tabla	--replace o --replace=true	WRITE_TRUNCATE	Borra todos los datos existentes de una tabla antes de escribir los datos nuevos. Esta acción también borra el esquema de la tabla, la seguridad a nivel de las filas y quita cualquier clave de Cloud KMS.

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

Puedes agregar o reemplazar una tabla con una de las siguientes opciones:

• La consola de Google Cloud
• El comando bq load de la herramienta de línea de comandos de bq
• El método de API jobs.insert y la configuración de un trabajo load
• Las bibliotecas cliente

Nota: En esta página, no se explica cómo reemplazar tablas particionadas ni cómo agregarles datos. Para obtener información sobre cómo agregar y reemplazar tablas particionadas, consulta Anexa y reemplaza datos de tablas particionadas.

Para agregar o sobrescribir una tabla con datos de Parquet, realiza los siguientes pasos:

Console

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

   Ir a BigQuery

2. En el panel Explorador, expande tu proyecto y, luego, elige 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, elige Google Cloud Storage en la lista Crear tabla desde. A continuación, sigue estos pasos:
   1. Elige un archivo del bucket de Cloud Storage o escribe el URI de Cloud Storage. No puedes incluir múltiples URI en la consola de Google Cloud, pero se admiten comodines. El bucket de Cloud Storage debe estar en la misma ubicación que el conjunto de datos que contiene la tabla que deseas crear, agregar o reemplazar.
   2. En Formato del archivo, selecciona Parquet.
Nota: Es posible modificar el esquema de la tabla cuando le agregas datos o la reemplazas. Para obtener más información sobre los cambios de esquema admitidos durante una operación de carga, consulta Modifica esquemas de tablas.
2. En la sección Destino, especifica los siguientes detalles:
   1. En Conjunto de datos, elige el conjunto de datos en el que deseas crear la tabla.
   2. En el campo Tabla, escribe el nombre de la tabla que deseas crear.
   3. Verifica que el campo Tipo de tabla esté configurado como Tabla nativa.
3. En la sección Esquema, no es necesaria ninguna acción. El esquema se describe automáticamente en archivos Parquet.
Nota: Es posible modificar el esquema de la tabla cuando le agregas datos o la reemplazas. Para obtener más información sobre los cambios de esquema admitidos durante una operación de carga, consulta Modifica esquemas de tablas.
4. Opcional: Especifica Configuración de particiones y clústeres. Para obtener más información, consulta Crea tablas particionadas y Crea y usa tablas agrupadas en clústeres. No puedes agregar datos a una tabla ni reemplazarla para convertirla en una tabla particionada o agrupada en clústeres. La consola de Google Cloud no admite agregar datos a tablas particionadas o agrupadas en clústeres ni reemplazarlas en un trabajo de carga.
5. Haz clic en Opciones avanzadas y haz lo siguiente:
   • En Preferencia de escritura, elige Agregar a la tabla o Reemplazar tabla.
   • Si deseas ignorar los valores de una fila que no están presentes en el esquema de la tabla, elige Valores desconocidos.
   • 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 del parámetro Clave administrada por Google, BigQuery encripta los datos en reposo.
6. Haz clic en Crear tabla.

SQL

Usa la declaración DDL LOAD DATA. En el siguiente ejemplo, se agrega un archivo Parquet a la tabla mytable:

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

   Ir a BigQuery

2. En el editor de consultas, escribe la siguiente sentencia:

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

3. Haz clic en Ejecutar.

Si deseas obtener información sobre cómo ejecutar consultas, visita Ejecuta una consulta interactiva.

bq

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

Nota: Es posible modificar el esquema de la tabla cuando la agregas o reemplazas. Para obtener más información sobre los cambios de esquema compatibles durante una operación de carga, consulta Modifica esquemas de tablas.

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

Las siguientes son otras marcas opcionales:

• --destination_kms_key: Es 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

Reemplaza lo siguiente:

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

Ejemplos:

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

    bq load \
    --replace \
    --source_format=PARQUET \
    mydataset.mytable \
    gs://mybucket/mydata.parquet

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

    bq load \
    --noreplace \
    --source_format=PARQUET \
    mydataset.mytable \
    gs://mybucket/mydata.parquet

Para obtener información sobre cómo agregar o reemplazar tablas particionadas con la herramienta de línea de comandos de bq, consulta Agrega y reemplaza datos de tablas particionadas.

API

1. Crea un trabajo load que apunte a los datos de origen en Cloud Storage.

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

3. La propiedad source URIs debe estar por completo calificada en el formato gs://BUCKET/OBJECT. Puedes incluir varios URI en una lista separada por comas. Ten en cuenta que también se admiten comodines.

4. Para especificar el formato de los datos, establece la propiedad configuration.load.sourceFormat en PARQUET.

5. Para especificar la preferencia de escritura, establece la propiedad configuration.load.writeDisposition en WRITE_TRUNCATE o WRITE_APPEND.

Go

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

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

import (
	"context"
	"fmt"

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

// importParquetTruncate demonstrates loading Apache Parquet data from Cloud Storage into a table
// and overwriting/truncating existing data in the table.
func importParquetTruncate(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.parquet")
	gcsRef.SourceFormat = bigquery.Parquet
	gcsRef.AutoDetect = true
	loader := client.Dataset(datasetID).Table(tableID).LoaderFrom(gcsRef)
	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

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

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

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.JobInfo.WriteDisposition;
import com.google.cloud.bigquery.LoadJobConfiguration;
import com.google.cloud.bigquery.TableId;
import java.math.BigInteger;

public class LoadParquetReplaceTable {

  public static void runLoadParquetReplaceTable() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    loadParquetReplaceTable(datasetName);
  }

  public static void loadParquetReplaceTable(String datasetName) {
    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();

      // Imports a GCS file into a table and overwrites table data if table already exists.
      // This sample loads CSV file at:
      // https://storage.googleapis.com/cloud-samples-data/bigquery/us-states/us-states.csv
      String sourceUri = "gs://cloud-samples-data/bigquery/us-states/us-states.parquet";
      TableId tableId = TableId.of(datasetName, "us_states");

      // For more information on LoadJobConfiguration see:
      // https://googleapis.dev/java/google-cloud-clients/latest/com/google/cloud/bigquery/LoadJobConfiguration.Builder.html
      LoadJobConfiguration configuration =
          LoadJobConfiguration.builder(tableId, sourceUri)
              .setFormatOptions(FormatOptions.parquet())
              // Set the write disposition to overwrite existing table data.
              .setWriteDisposition(WriteDisposition.WRITE_TRUNCATE)
              .build();

      // For more information on Job see:
      // https://googleapis.dev/java/google-cloud-clients/latest/index.html?com/google/cloud/bigquery/package-summary.html
      // Load the table
      Job job = bigquery.create(JobInfo.of(configuration));

      // Load data from a GCS parquet file into the table
      // Blocks until this load table job completes its execution, either failing or succeeding.
      Job completedJob = job.waitFor();
      if (completedJob == null) {
        System.out.println("Job not executed since it no longer exists.");
        return;
      } else if (completedJob.getStatus().getError() != null) {
        System.out.println(
            "BigQuery was unable to load into the table due to an error: \n"
                + job.getStatus().getError());
        return;
      }

      // Check number of rows loaded into the table
      BigInteger numRows = bigquery.getTable(tableId).getNumRows();
      System.out.printf("Loaded %d rows. \n", numRows);

      System.out.println("GCS parquet overwrote existing table successfully.");
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Table extraction job was interrupted. \n" + e.toString());
    }
  }
}

Node.js

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

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

// 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 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.parquet';

async function loadParquetFromGCSTruncate() {
  /**
   * 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: 'PARQUET',
    // 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 instrucciones de configuración para PHP incluidas en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para PHP.

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

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.parquet';
$loadConfig = $table->loadFromStorage($gcsUri)->sourceFormat('PARQUET')->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 para Python incluidas en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para Python.

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

Para reemplazar las filas de una tabla existente, configura la propiedad LoadJobConfig.write_disposition como 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.PARQUET,
)

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

Carga datos de Parquet particionados por Hive

BigQuery admite la carga de datos de Parquet particionados en Cloud Storage y propaga las columnas de partición de Hive como columnas en la tabla administrada de destino de BigQuery. Para obtener más información, consulta Carga datos con particiones externas.

Conversiones de Parquet

En esta sección, se describe cómo BigQuery analiza varios tipos de datos cuando se cargan datos de Parquet.

Algunos tipos de datos de Parquet (como INT32, INT64, BYTE_ARRAY y FIXED_LEN_BYTE_ARRAY) se pueden convertir en varios tipos de datos de BigQuery. Para asegurarte de que BigQuery convierta los tipos de datos de Parquet de forma correcta, especifica el tipo de datos adecuado en el archivo Parquet.

Por ejemplo, para convertir el tipo de datos INT32 de Parquet en el tipo de datos DATE de BigQuery, especifica lo siguiente:

optional int32 date_col (DATE);

BigQuery convierte los tipos de datos de Parquet en los tipos de datos de BigQuery que se describen en las siguientes secciones.

Tipos de conversiones

Tipo de Parquet	Tipos lógicos de Parquet	Tipo de datos de BigQuery
BOOLEAN	Ninguna	BOOLEAN
INT32	Ninguna, INTEGER (UINT_8, UINT_16, UINT_32, INT_8, INT_16, INT_32)	INT64
INT32	DECIMAL	NUMERIC, BIGNUMERIC o STRING
INT32	DATE	DATE
INT64	Ninguna, INTEGER (UINT_64, INT_64)	INT64
INT64	DECIMAL	NUMERIC, BIGNUMERIC o STRING
INT64	TIMESTAMP, precision=MILLIS (TIMESTAMP_MILLIS)	TIMESTAMP
INT64	TIMESTAMP, precision=MICROS (TIMESTAMP_MICROS)	TIMESTAMP
INT96	Ninguna	TIMESTAMP
FLOAT	Ninguna	FLOAT64
DOUBLE	Ninguna	FLOAT64
BYTE_ARRAY	Ninguna	BYTES
BYTE_ARRAY	STRING (UTF8)	STRING
FIXED_LEN_BYTE_ARRAY	DECIMAL	NUMERIC, BIGNUMERIC o STRING
FIXED_LEN_BYTE_ARRAY	Ninguna	BYTES

Los grupos anidados se convierten en tipos STRUCT. Otras combinaciones de tipos de Parquet y tipos convertidos no son compatibles.

Tipos lógicos sin firmas

Los tipos UINT_8, UINT_16, UINT_32 y UINT_64 de Parquet no están firmados. BigQuery tratará los valores con estos tipos como no firmados cuando se carguen en una columna INTEGER firmada de BigQuery. En el caso de UINT_64, se devolverá un error si el valor sin firmar excede el valor máximo de INTEGER de 9,223,372,036,854,775,807.

Tipos lógicos decimales

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

• Para un trabajo de carga con la API de jobs.insert, usa el campo JobConfigurationLoad.decimalTargetTypes.
• Para obtener un trabajo de carga con el comando bq load en la herramienta de línea de comandos bq, usa la marca --decimal_target_types.
• Para una consulta en una tabla con fuentes externas, usa el campo ExternalDataConfiguration.decimalTargetTypes.
• Para una tabla externa persistente creada con DDL, usa la opción decimal_target_types.

Tipos lógicos Enum

Los tipos lógicos Enum se pueden convertir en STRING, o BYTES. Especifica el tipo de objetivo decimal de la siguiente manera:

• Para un trabajo de carga con la API de jobs.insert, usa el campo JobConfigurationLoad.parquetOptions.
• Para obtener un trabajo de carga con el comando bq load en la herramienta de línea de comandos bq, usa la marca --parquet_enum_as_string.
• Para una tabla externa persistente creada con bq mk, usa la marca --parquet_enum_as_string.

Tipos lógicos List

Puedes habilitar la inferencia de esquema para los tipos lógicos LIST de Parquet. BigQuery verifica si el nodo LIST está en la forma estándar o en una de las formas descritas en las reglas de retrocompatibilidad:

// standard form
<optional | required> group <name> (LIST) {
  repeated group list {
    <optional | required> <element-type> element;
  }
}

Si es así, el campo correspondiente para el nodo LIST en el esquema convertido se trata como si el nodo tuviera el siguiente esquema:

repeated <element-type> <name>

Se omiten los nodos “list” y “element”.

• Para un trabajo de carga con la API de jobs.insert, usa el campo JobConfigurationLoad.parquetOptions.
• Para obtener un trabajo de carga con el comando bq load en la herramienta de línea de comandos bq, usa la marca --parquet_enable_list_inference.
• Para una tabla externa persistente creada con bq mk, usa la marca --parquet_enable_list_inference.

Datos geoespaciales

Puedes cargar archivos Parquet que contengan WKT codificado en hexadecimal, WKB o GeoJSON en una columna STRING, o WKB en una columna BYTE_ARRAY mediante la especificación de un esquema de BigQuery con el tipo GEOGRAPHY. Consulta Carga datos geoespaciales.

Nota: Ten cuidado cuando uses este enfoque para los datos de GeoParquet. BigQuery no leerá los metadatos sobre el sistema de coordenadas y la orientación poligonal.

Conversiones de nombre de columna

El nombre de una columna puede contener letras (a-z, A-Z), números (0-9) o guiones bajos (_) y debe empezar con una letra o guion bajo. Si usas nombres de columna flexibles, BigQuery admite que se inicie un nombre de columna con un número. Ten cuidado cuando inicies columnas con un número, ya que el uso de nombres de columna flexibles con la API de lectura de almacenamiento de BigQuery o la API de escritura de BigQuery Storage requiere un control especial. Para obtener más información sobre la compatibilidad con los nombres de columnas flexibles, consulta Nombres de columnas flexibles.

Los nombres de las columnas tienen una longitud máxima de 300 caracteres. No se puede usar ninguno de los siguientes prefijos para los nombres de columna:

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

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. Si deseas obtener más información sobre las reglas de nombres de columnas, consulta Nombres de columnas en la referencia de Google SQL.

Si un nombre de tabla (por ejemplo, test) es el mismo que uno de los nombres 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, usa uno de los siguientes métodos:

• Evita usar el mismo nombre para una tabla y sus columnas.

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

  SELECT test FROM project1.dataset.test AS t;
  

• Incluye el nombre de la tabla cuando hagas referencia a una columna. Por ejemplo:

  SELECT test.test FROM project1.dataset.test;
  

Nombres de columnas flexibles

Vista previa

Este producto o función está sujeto a las "Condiciones de las Ofertas de Fase Previa a la DG" de la sección Condiciones Generales del Servicio de las Condiciones específicas del Servicio. Los productos y las funciones que se encuentran en la fase previa a la DG están disponibles “tal cual” y podrían tener asistencia limitada. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

Ahora tiene más flexibilidad en los nombres de las columnas, incluido el acceso expandido a caracteres en otros idiomas además del inglés, así como símbolos adicionales.

Los nombres flexibles de las columnas admiten los siguientes caracteres:

• Cualquier letra en cualquier lenguaje, como lo representa la expresión regular Unicode \p{L}.
• Cualquier carácter numérico en cualquier lenguaje representado por la expresión regular Unicode \p{N}.
• Cualquier carácter de puntuación de conector, incluidos los guiones bajos, como lo representa la expresión regular Unicode \p{Pc}.
• Un guion o una raya representada por la expresión regular Unicode \p{Pd}.
• Cualquier marca destinada a acompañar otro carácter, como lo representa la expresión regular Unicode \p{M}. Por ejemplo, los acentos, las diéresis o los cuadros de cierre.
• Los siguientes caracteres especiales:
  • Un signo et (&) representado por la expresión regular Unicode \u0026.
  • Un 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.
  • Los dos puntos (:) que representa la expresión regular Unicode \u003A
  • Un apóstrofo (') representado por la expresión regular Unicode \u0027.
  • Un signo menor que (<) representado por la expresión regular Unicode \u003C.
  • Un 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 columnas flexibles no son compatibles con 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.
• Un signo de 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.
• 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 inversa (\) 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 lineamientos adicionales, consulta Nombres de columnas.

Los caracteres expandidos de columna son compatibles con la API de BigQuery Storage Read y la API de BigQuery Storage Write. Para usar la lista expandida de caracteres Unicode con la API de BigQuery Storage Read, debes establecer una marca. Puedes usar el atributo displayName para recuperar el nombre de la columna. En el siguiente ejemplo, se muestra cómo configurar 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 expandida de caracteres Unicode con la API de BigQuery Storage Write, debes proporcionar el esquema con la notación column_name, a menos que uses el objeto de escritor 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 con la convención de nombres del búfer de protocolo. Ten en cuenta que las anotaciones column_name siempre tienen prioridad sobre los nombres de los marcadores de posición.

• La carga de datos de Parquet no admite nombres flexibles de columnas de forma predeterminada. Para inscribirte en esta vista previa, completa el formulario de inscripción. Ten en cuenta que después de inscribirte en la vista previa, cualquier nombre de columna no válido (por ejemplo, intercalaciones de nombres de columna) devuelve un error. Para los proyectos no inscritos, la solicitud de carga reemplaza los caracteres no válidos por guiones bajos en lugar de devolver un error.
• La carga de datos CSV con la detección automática de esquemas no es compatible con los nombres flexibles de columnas de forma predeterminada. Para inscribirte en esta vista previa, completa el formulario de inscripción. Ten en cuenta que después de inscribirte en la vista previa, cualquier nombre de columna no válido (por ejemplo, intercalaciones de nombres de columna) devuelve un error. Para los proyectos no inscritos, la solicitud de carga reemplaza los caracteres no válidos por guiones bajos en lugar de devolver un error.

Los nombres de columnas flexibles no son compatibles con las tablas externas.

Por el momento, no puedes cargar archivos de Parquet que contengan columnas que tengan un punto (.) en el nombre de la columna.

Si el nombre de una columna de Parquet contiene otros caracteres (aparte de un punto), los caracteres se reemplazan por guiones bajos. Puedes agregar guiones bajos al final de los nombres de columna para evitar colisiones. Por ejemplo, si un archivo Parquet contiene 2 columnas Column1 y column1, las columnas se cargan como Column1 y column1_ respectivamente.

Depura tu archivo Parquet

Si tus trabajos de carga fallan con errores de datos, puedes usar PyArrow para verificar si tus archivos de datos de Parquet están dañados. Si PyArrow no lee los archivos, es probable que el trabajo de carga de BigQuery los rechace. En el siguiente ejemplo, se muestra cómo leer el contenido de un archivo Parquet con PyArrow:

from pyarrow import parquet as pq

# Read the entire file
pq.read_table('your_sample_file.parquet')
# Read specific columns
pq.read_table('your_sample_file.parquet',columns=['some_column', 'another_column'])
# Read the metadata of specific columns
file_metadata=pq.read_metadata('your_sample_file.parquet')
for col in file_metadata.row_group(0).to_dict()['columns']:
    print col['column_path_in_schema']
    print col['num_values']

Para obtener más información, consulta los documentos de PyArrow.