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 ampliamente 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 se cargan datos de Cloud Storage en una tabla BigQuery, el conjunto de datos que contiene la tabla debe encontrarse en la misma ubicación regional o multirregional que el depósito de Cloud Storage.

Para obtener más información sobre cómo cargar datos de Parquet desde un archivo local, consulta Cómo cargar datos en BigQuery desde una fuente de datos local.

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

Este comando carga todos los archivos en un solo comando de CLI (como una lista separada por comas), y el esquema se deriva desde 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 BigQuery SQL. Para obtener más información, consulta Conversiones de Parquet.

Compresión de Parquet

Los archivos comprimidos de Parquet no son compatibles, pero sí lo son los bloques de datos comprimidos. BigQuery es compatible con los códecs de Snappy, GZip y LZO_1X para bloques de datos comprimidos en archivos de Parquet.

Permisos necesarios

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

Permisos de BigQuery

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

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

Las siguientes funciones predefinidas de Cloud IAM incluyen los permisos bigquery.tables.create y bigquery.tables.updateData:

bigquery.dataEditor
bigquery.dataOwner
bigquery.admin

Las siguientes funciones predefinidas de Cloud IAM incluyen los permisos de bigquery.jobs.create:

bigquery.user
bigquery.jobUser
bigquery.admin

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

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

Permisos de Cloud Storage

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

Se puede otorgar la función predefinida de Cloud IAM storage.objectViewer para proporcionar permisos storage.objects.get y storage.objects.list.

Carga datos de Parquet en una tabla nueva

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

Mediante GCP Console o la IU web clásica
Mediante el comando bq load de la CLI
Mediante una llamada al método de la API jobs.insert y la configuración de un trabajo load
Mediante las bibliotecas cliente

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

Console

Abre la IU web de BigQuery en GCP Console.
Ir a GCP Console
En el panel de navegación, en la sección Recursos, expande tu proyecto y selecciona un conjunto de datos.
En el lado derecho de la ventana, en el panel de detalles, haz clic en Crear tabla (Create table). El proceso de carga de datos es el mismo que el que se usa para crear una tabla vacía.
En la página Crear tabla (Create table), en la sección Origen (Source), sigue estos pasos:
- En Crear tabla desde (Create table from), selecciona Cloud Storage.
- En el campo de origen, busca o ingresa el URI de Cloud Storage. Ten en cuenta que no puedes incluir varios URI en GCP Console, pero sí se admiten comodines. El depósito de Cloud Storage debe encontrarse en la misma ubicación que el conjunto de datos que contiene la tabla que quieres crear.
- En Formato de archivo (File format), selecciona Parquet.
En la página Crear tabla, en la sección Destino (Destination), sigue estos pasos:
- En Nombre del conjunto de datos (Dataset name), selecciona el conjunto de datos que corresponda.
- Verifica que Tipo de tabla (Table type) esté configurado como Tabla nativa (Native table).
- En el campo Nombre de tabla, ingresa el nombre de la tabla que quieres crear en BigQuery.
En la sección Esquema no es necesaria ninguna acción. El esquema se describe en sí en archivos de Parquet.
Para particionar la tabla, elige las opciones en la Configuración de partición y agrupamiento en clústeres (opcional):
- Para crear una tabla particionada, haz clic en Sin particionar, selecciona Particionar por campo y elige una columna DATE o TIMESTAMP. Esta opción no estará disponible si el esquema no incluye una columna DATE o TIMESTAMP.
- Para crear una tabla particionada por tiempo de transferencia, haz clic en Sin particionar y selecciona Particionar por tiempo de transferencia.
En Filtro de partición, haz clic en el cuadro Exigir filtro de partición para exigirle a los usuarios que incluyan una cláusula WHERE que especifique las particiones que se van a consultar (opcional). Exigir un filtro de partición puede reducir los costos y mejorar el rendimiento. Para obtener más información, lee Cómo consultar tablas particionadas. Esta opción no estará disponible si se selecciona Sin particionar.
Para agrupar la tabla, en el cuadro Orden de agrupamiento en clústeres, ingresa entre uno y cuatro nombres de campo (opcional). En la actualidad, el agrupamiento en clústeres solo es compatible con tablas particionadas.
Haz clic en Opciones avanzadas (opcional).
- En Preferencia de escritura, deja seleccionado Escribir si está vacía. Esta opción crea una tabla nueva y carga los datos en ella.
- En Cantidad de errores permitidos, acepta el valor predeterminado de 0 o ingresa la cantidad máxima de filas con errores que pueden ignorarse. Si la cantidad de filas con errores supera este valor, el trabajo generará un mensaje invalid y fallará.
- En Valores desconocidos, desmarca la opción Ignorar valores desconocidos. Esta opción se aplica solo a los archivos CSV y JSON.
- En Encriptación, haz clic en Clave administrada por el cliente para usar una clave de Cloud Key Management Service. Si lo configuras como Clave administrada por Google, BigQuery encriptará los datos en reposo.
Haz clic en Crear tabla.

IU clásica

Ve a la IU web de BigQuery.
Ir a la IU web de BigQuery
En el panel de navegación, desplaza el cursor sobre un conjunto de datos, haz clic en el ícono de flecha hacia abajo y, luego, en Crear tabla nueva. El proceso de carga de datos es el mismo que el que se usa para crear una tabla vacía.
En la página Crear tabla, en la sección Datos de origen, realiza los siguientes pasos:
- Haz clic en Crear desde el origen.
- En Ubicación, selecciona Cloud Storage y en el campo de origen ingresa el URI de Cloud Storage. Ten en cuenta que no puedes ingresar varios URI en la IU web de BigQuery, pero se admiten comodines. El depósito de Cloud Storage debe encontrarse en la misma ubicación que el conjunto de datos que contiene la tabla que quieres crear.
- En Formato de archivo, selecciona Parquet.
En la sección Tabla de destino, sigue estos pasos:
- En Nombre de tabla, selecciona el conjunto de datos que corresponda y, en el campo de nombre de tabla, ingresa el nombre de la tabla que quieres crear en BigQuery.
- Verifica que Tipo de tabla esté configurado como Tabla nativa.
En la sección Esquema no es necesaria ninguna acción. El esquema se describe en sí en archivos de Parquet.
En la sección Opciones, realiza los siguientes pasos (opcional):
- En Cantidad de errores permitidos, acepta el valor predeterminado de 0 o ingresa la cantidad máxima de filas con errores que pueden ignorarse. Si la cantidad de filas con errores supera este valor, el trabajo generará un mensaje invalid y fallará.
- En Preferencia de escritura, deja seleccionado Escribir si está vacía. Esta opción crea una tabla nueva y carga los datos en ella.
- Para dividir la tabla, realiza las siguientes acciones:
  - Para Tipo de partición, haz clic en Ninguno y elige Día.
  - En Campo de partición:
  - Para crear una tabla particionada, elige una columna DATE o TIMESTAMP. Esta opción no estará disponible si el esquema no incluye una columna DATE o TIMESTAMP.
  - Para crear una tabla particionada por tiempo de transferencia, deja el valor predeterminado: _PARTITIONTIME.
  - Haz clic en el cuadro Exigir filtro de partición para solicitar a los usuarios que incluyan una cláusula WHERE que especifique las particiones que quieren consultar. Exigir un filtro de partición puede reducir los costos y mejorar el rendimiento. Para obtener más información, lee Cómo consultar tablas particionadas. Esta opción no estará disponible si el Tipo de partición está configurado como Ninguno.
- Para agrupar en clústeres la tabla, en el cuadro Agrupar campos, ingresa entre uno y cuatro nombres de campo.
- En Encriptación de destino, elige Encriptación administrada por el cliente para encriptar la tabla con una clave de Cloud Key Management Service. Si dejas la configuración Default, BigQuery encriptará los datos en reposo a través de una clave administrada por Google.
Haz clic en Crear tabla.

CLI

Usa el comando bq load, especifica PARQUET con el marcador --source_format y agrega un URI de Cloud Storage. Puedes incluir un solo URI, una lista de URI separados por comas o un URI que contenga un comodín.

Proporciona el marcador --location y configura el valor como tu ubicación (opcional).

A continuación, se detallan otros marcadores opcionales:

--max_bad_records: un número entero que especifica la cantidad máxima de registros incorrectos permitidos antes de que falle todo el trabajo. El valor predeterminado es 0. Como máximo, se muestran cinco errores de cualquier tipo, independientemente del valor que se le asigne a --max_bad_records.
--time_partitioning_type: habilita la partición basada en el tiempo en una tabla y establece el tipo de partición. Actualmente, el único valor posible es DAY, que genera una partición por día. Este marcador es opcional cuando se crea una tabla particionada en una columna DATE o TIMESTAMP.
--time_partitioning_expiration: un número entero que especifica (en segundos) cuándo se debe borrar una partición basada en el tiempo. La hora de vencimiento se evalúa según la suma de la fecha de la partición en formato UTC más el valor del número entero.
--time_partitioning_field: la columna DATE o TIMESTAMP utilizada 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 está habilitada, esta opción requiere que los usuarios incluyan una cláusula WHERE que especifique las particiones que se van a consultar. Exigir un filtro de partición puede reducir los costos y mejorar el rendimiento. Para obtener más información, lee Cómo consultar tablas particionadas.
--clustering_fields: una lista separada por comas de hasta cuatro nombres de columna para crear una tabla agrupada. Este marcador solo se puede usar con tablas particionadas.
--destination_kms_key: la clave de Cloud KMS para la encriptación de los datos de la tabla.

Para obtener más información sobre tablas particionadas, consulta los siguientes artículos:
- Cómo crear y usar tablas particionadas
- Crea y usa tablas particionadas por tiempo de transferencia
Para obtener más información sobre tablas agrupadas, consulta el siguiente artículo:
- Cómo crear y usar 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

Donde:

location es tu ubicación. El marcador --location es opcional. Por ejemplo, si usas BigQuery en la región de Tokio, puedes configurar el valor del marcador en asia-northeast1. Puedes configurar un valor predeterminado para la ubicación con el archivo .bigqueryrc.
format es PARQUET.
dataset es un conjunto de datos existente.
table es el nombre de la tabla en la que cargas los datos.
path_to_source es un URI de Cloud Storage totalmente calificado o una lista de URI separados por comas. También se admiten los 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

El siguiente comando carga datos de gs://mybucket/mydata.parquet a una tabla particionada por tiempo de transferencia 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

El siguiente comando carga 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

El siguiente comando carga 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

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

Notas de API:

Los trabajos de carga son atómicos y coherentes. Si un trabajo de carga falla, ninguno de los datos estará disponible, y si un trabajo de carga se realiza con éxito, todos los datos estarán disponibles.
La práctica recomendada es generar un ID único y pasarlo como jobReference.jobId cuando se llama 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 cierto ID de trabajo 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 de Go incluidas en la Guía de inicio rápido de BigQuery con bibliotecas cliente. A fin de obtener más información, consulta la Documentación de referencia de la API de Go de BigQuery.

Ver en GitHub Comentarios

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

Java

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

Ver en GitHub Comentarios

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();
// Load the table
Job loadJob = bigquery.create(JobInfo.of(configuration));
loadJob = loadJob.waitFor();
// Check the table
StandardTableDefinition destinationTable = bigquery.getTable(tableId).getDefinition();
System.out.println("State: " + loadJob.getStatus().getState());
System.out.printf("Loaded %d rows.\n", destinationTable.getNumRows());

Node.js

Antes de probar esta muestra, sigue las instrucciones de configuración para Node.js que se encuentran en la Guía de inicio rápido de BigQuery con bibliotecas cliente. A fin de obtener más información, consulta la documentación de referencia de la API de BigQuery para Node.js.

Ver en GitHub Comentarios

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

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

/**
 * This sample loads the 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 esta muestra, sigue las instrucciones de configuración de PHP que se encuentran en la Guía de inicio rápido de BigQuery con bibliotecas cliente. A fin de obtener más información, consulta la documentación de referencia de la API de BigQuery para PHP.

Ver en GitHub Comentarios

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

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

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

// create the import job
$gcsUri = 'gs://cloud-samples-data/bigquery/us-states/us-states.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 de Python incluidas en la Guía de inicio rápido de BigQuery con bibliotecas cliente. Para obtener más información, consulta la Documentación de referencia de la API de Python de BigQuery.

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 como la constante PARQUET en SourceFormat, y pasa la configuración del trabajo como el argumento job_config al método load_table_from_uri().

Ver en GitHub

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

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

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

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

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

Agrega o reemplaza una tabla con datos de Parquet

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

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

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

Opción de Console	Opción de IU web clásica	Marcador CLI	Propiedad de la API de BigQuery	Descripción
Escribir si está vacía	Escribir si está vacía	Ninguno	`WRITE_EMPTY`	Solo escribe los datos si la tabla está vacía.
Adjuntar a la tabla	Agregar a la tabla	`--noreplace` o `--replace=false`; si `--[no]replace` no está especificado, la opción predeterminada será agregar	`WRITE_APPEND`	Adjunta los datos al final de la tabla (predeterminado).
Reemplazar tabla	Reemplazar tabla	`--replace` o `--replace=true`	`WRITE_TRUNCATE`	Borra todos los datos existentes de una tabla antes de escribir los datos nuevos.

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

Puedes agregar o reemplazar una tabla de la siguiente manera:

Mediante GCP Console o la IU web clásica
Mediante el comando bq load de la CLI
Mediante una llamada al método de la API jobs.insert y la configuración de un trabajo load
Mediante las bibliotecas cliente

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

Console

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

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

IU clásica

Ve a la IU web de BigQuery.
Ir a la IU web de BigQuery
En el panel de navegación, desplaza el cursor sobre un conjunto de datos, haz clic en el ícono de flecha hacia abajo y, luego, en Crear tabla nueva. El proceso para agregar y reemplazar datos en un trabajo de carga es el mismo que el de crear una tabla en un trabajo de carga.
En la página Crear tabla, en la sección Datos de origen, realiza los siguientes pasos:
- En Ubicación, selecciona Cloud Storage, y en el campo de origen, ingresa el URI de Cloud Storage. Ten en cuenta que no puedes ingresar varios URI en la IU, pero se admiten comodines. El depósito de Cloud Storage debe encontrarse en la misma ubicación que el conjunto de datos que contiene la tabla que agregas o reemplazas.
- En Formato de archivo, selecciona Parquet.
En la página Crear tabla, en la sección Tabla de destino, realiza los siguientes pasos:
- En Nombre de la tabla, selecciona el conjunto de datos que corresponda y, en el campo de nombre de tabla, ingresa el nombre de la tabla que quieres agregar o reemplazar.
- Verifica que Tipo de tabla esté configurado como Tabla nativa.
En la sección Esquema no es necesaria ninguna acción. La información del esquema se describe en sí en archivos de Parquet.

Nota: Es posible modificar el esquema de la tabla cuando lo agregas o reemplazas. Para obtener más información sobre los cambios de esquema admitidos durante una operación de carga, consulta Modifica esquemas de tablas.
En la sección Opciones, sigue estos pasos:
- En Cantidad de errores permitidos, acepta el valor predeterminado de 0 o ingresa la cantidad máxima de filas con errores que pueden ignorarse. Si la cantidad de filas con errores supera este valor, el trabajo generará un mensaje invalid y fallará.
- En Preferencia de escritura, selecciona Agregar a la tabla o Reemplazar tabla.
- Deja los valores predeterminados en Tipo de partición, Campos de partición, Exigir filtro de partición y Campos de agrupamiento. No puedes agregar ni reemplazar una tabla para convertirla en una tabla particionada o agrupada; la IU web no admite agregar ni reemplazar tablas particionadas o agrupadas en un trabajo de carga.
- En Encriptación de destino, elige Encriptación administrada por el cliente para encriptar la tabla con una clave de Cloud Key Management Service. Si dejas la configuración Default, BigQuery encriptará los datos en reposo a través de una clave administrada por Google.
Haz clic en Crear tabla.

CLI

Ingresa el comando bq load con el marcador --replace para reemplazar la tabla. Usa el marcador --noreplace para agregar datos a la tabla. Si no se especifica ningún marcador, se agregan datos de manera predeterminada. Proporciona el marcador --source_format y configúralo como PARQUET. Debido a que los esquemas de Parquet se recuperan automáticamente de los datos de origen autodescriptivos, no es necesario proporcionar una definición de esquema.

Proporciona el marcador --location y configura el valor como tu ubicación (opcional).

A continuación, se detallan otros marcadores opcionales:

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

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

Donde:

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

Ejemplos:

Con el siguiente comando, se cargan datos de gs://mybucket/mydata.parquet y se reemplaza una tabla denominada 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 agregan los datos en una tabla denominada mytable en mydataset.

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

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

API

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

Go

Ver en GitHub Comentarios

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

Node.js

Ver en GitHub Comentarios

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

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

/**
 * This sample loads the 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

Ver en GitHub Comentarios

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

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

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

// create the import job
$gcsUri = 'gs://cloud-samples-data/bigquery/us-states/us-states.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 de Python incluidas en la Guía de inicio rápido de BigQuery con bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de Python de BigQuery.

Para remplazar las filas de una tabla existente, configura la propiedad LoadJobConfig.write_disposition con la constante WRITE_TRUNCATE de WriteDisposition.

Ver en GitHub

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

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

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

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

Conversiones de Parquet

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

Tipos de conversiones

Tipo de Parquet	Tipos de conversión de Parquet	Tipos de datos de BigQuery
BOOLEANO	NINGUNO	Booleano
INT32	NINGUNO, UINT_8, UINT_16, UINT_32, INT_8, INT_16, INT_32	Número entero
INT32	DECIMAL (ver anotación DECIMAL)	Numérico
INT32	FECHA	Fecha
INT64	NINGUNO, UINT_64, INT_64	Número entero
INT64	DECIMAL (ver anotación DECIMAL)	Numérico
INT64	TIMESTAMP_MILLIS	Marca de tiempo
INT64	TIMESTAMP_MICROS	Marca de tiempo
INT96	NINGUNO	Marca de tiempo
FLOAT	NINGUNO	Punto flotante
DOBLE	NINGUNO	Punto flotante
BYTE_ARRAY	NINGUNO	Bytes
BYTE_ARRAY	UTF8	String
FIXED_LEN_BYTE_ARRAY	DECIMAL (ver anotación DECIMAL)	Numérico
FIXED_LEN_BYTE_ARRAY	NINGUNO	Bytes

Otras combinaciones de tipos de Parquet y tipos convertidos no son compatibles.

Anotación decimal

Los tipos de Parquet con la anotación DECIMAL pueden tener como máximo una precisión de 38 (número total de dígitos) y como máximo una escala de 9 (dígitos a la derecha del decimal). El número de dígitos enteros, que es la precisión menos la escala, puede ser de máximo 29. Por ejemplo, DECIMAL(38, 9) es compatible porque la precisión es 38 y la escala es 9. En este ejemplo, el número de dígitos enteros es 29. DECIMAL(38, 5) no es compatible porque tiene una precisión de 38 y una escala de 5. En este ejemplo, el número de dígitos enteros es 33.

Conversiones de nombre de columna

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

_TABLE_
_FILE_
_PARTITION

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

Actualmente, 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. Se pueden agregar guiones bajos a los nombres de las columnas para evitar colisiones. Por ejemplo, si un archivo de Parquet contiene 2 columnas Column1 y column1, las columnas se cargan como Column1 y column1_, respectivamente.

Esquemas de Parquet

Compresión de Parquet

Permisos necesarios

Permisos de BigQuery

Permisos de Cloud Storage

Carga datos de Parquet en una tabla nueva

Console

IU clásica

CLI

API

Go

Java

Node.js

PHP

Python

Agrega o reemplaza una tabla con datos de Parquet

Console

IU clásica

CLI

API

Go

Node.js

PHP

Python

Conversiones de Parquet

Tipos de conversiones

Anotación decimal

Conversiones de nombre de columna

Enviar comentarios sobre...