Cargar datos Avro desde Cloud Storage

Avro es un formato de datos de código abierto que agrupa los datos serializados con el esquema de los datos en el mismo archivo.

Cuando cargas datos Avro desde Cloud Storage, puedes hacerlo en una tabla o partición nuevas, o bien añadir datos a una tabla o partición que ya tengas, o sobrescribirla. Cuando tus datos se cargan en BigQuery, se convierten al formato de columnas de Capacitor (el formato de almacenamiento de BigQuery).

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

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

Limitaciones

Cuando cargas datos en BigQuery desde un segmento de Cloud Storage, estás sujeto a las siguientes limitaciones:

  • BigQuery no garantiza la coherencia de los datos de las fuentes de datos externas. Si se modifican los datos subyacentes mientras se ejecuta una consulta, se pueden producir comportamientos inesperados.
  • BigQuery no admite la gestión de versiones de objetos de Cloud Storage. Si incluyes un número de generación en el URI de Cloud Storage, el trabajo de carga fallará.

También se aplican las siguientes limitaciones al cargar archivos Avro en BigQuery:

  • BigQuery no admite la carga de archivos de esquema Avro (.avsc) independientes.
  • BigQuery no admite el formato de matriz anidada. Los archivos Avro que usen este formato deben convertirse antes de importarse.
  • En un archivo Avro, los nombres y los espacios de nombres de un nombre completo solo pueden contener caracteres alfanuméricos y el carácter de guion bajo _. La siguiente expresión regular muestra los caracteres permitidos: [A-Za-z_][A-Za-z0-9_]*.

Para obtener información sobre los límites de las tareas de carga de BigQuery, consulta Tareas de carga.

Requisitos de los archivos de entrada

Para evitar errores resourcesExceeded al cargar archivos Avro en BigQuery, sigue estas directrices:

  • El tamaño de las filas no debe superar los 50 MB.
  • Si la fila contiene muchos campos de matriz o algún campo de matriz muy largo, divide los valores de la matriz en campos independientes.

Antes de empezar

Asigna roles de gestión de identidades y accesos (IAM) que proporcionen a los usuarios los permisos necesarios para realizar cada tarea de este documento y crea un conjunto de datos y una tabla para almacenar tus datos.

Permisos obligatorios

Para cargar datos en BigQuery, necesitas permisos de gestión de identidades y accesos para ejecutar un trabajo de carga y cargar datos en tablas y particiones de BigQuery. Si cargas datos desde Cloud Storage, también necesitas permisos de IAM para acceder al segmento que contiene tus datos.

Permisos para cargar datos en BigQuery

Para cargar datos en una tabla o partición de BigQuery, o bien para añadir o sobrescribir una tabla o partición, necesitas los siguientes permisos de gestión de identidades y accesos:

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

Cada uno de los siguientes roles de gestión de identidades y accesos predefinidos incluye los permisos que necesitas para cargar datos en una tabla o partición de BigQuery:

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

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

Para obtener más información sobre los roles y permisos de IAM en BigQuery, consulta el artículo sobre funciones y permisos predefinidos.

Permisos para cargar datos desde Cloud Storage

Para obtener los permisos que necesitas para cargar datos desde un segmento de Cloud Storage, pide a tu administrador que te conceda el rol de gestión de identidades y accesos Administrador de Storage (roles/storage.admin) en el segmento. Para obtener más información sobre cómo conceder roles, consulta el artículo Gestionar el acceso a proyectos, carpetas y organizaciones.

Este rol predefinido contiene los permisos necesarios para cargar datos desde un segmento de Cloud Storage. Para ver los permisos exactos que se necesitan, despliega la sección Permisos necesarios:

Permisos obligatorios

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

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

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

Crear un conjunto de datos y una tabla

Para almacenar tus datos, debes crear un conjunto de datos de BigQuery y, a continuación, una tabla de BigQuery en ese conjunto de datos.

Ventajas de Avro

Avro es el formato preferido para cargar datos en BigQuery. Cargar archivos Avro tiene las siguientes ventajas con respecto a los archivos CSV y JSON (delimitados por líneas nuevas):

  • El formato binario Avro:
    • Se carga más rápido. Los datos se pueden leer en paralelo, aunque los bloques de datos estén comprimidos.
    • No requiere escribir ni serializar.
    • Es más fácil de analizar porque no se han encontrado problemas de codificación en otros formatos, como ASCII.
  • Cuando cargas archivos Avro en BigQuery, el esquema de la tabla se obtiene automáticamente de los datos de origen autodescriptivos.

Esquemas Avro

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

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

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

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

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

Cuando se importan varios archivos Avro con esquemas Avro diferentes, todos los esquemas deben ser compatibles con la resolución de esquemas de Avro.

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

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

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

También puedes importar un esquema a BigQuery especificando un archivo de esquema JSON.

Compresión Avro

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

  • Snappy
  • DEFLATE
  • ZSTD

Cargar datos de Avro en una tabla nueva

Para cargar datos de Avro de Cloud Storage en una tabla de BigQuery, seleccione una de las siguientes opciones:

Consola

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

    Ir a BigQuery

  2. En el panel Explorador, expande tu proyecto y selecciona un conjunto de datos.

  3. Abre la opción Acciones y haz clic en Abrir.

  4. En el panel de detalles, haz clic en Crear tabla .

  5. En la página Crear tabla, ve a la sección Fuente:

    • En Crear tabla a partir de, selecciona Google Cloud Storage.

    • En el campo de origen, busca o introduce el URI de Cloud Storage. Ten en cuenta que no puedes incluir varias URIs en la Google Cloud consola, pero se admiten comodines. El segmento de Cloud Storage debe estar en la misma ubicación que el conjunto de datos que contiene la tabla que vas a crear.

      Seleccionar archivo

    • En Formato de archivo, selecciona Avro.

  6. En la página Crear tabla, ve a la sección Destino:

    • En Nombre del conjunto de datos, elige el conjunto de datos adecuado.
    • Verifica que el Tipo de tabla sea Tabla nativa.
    • En el campo Nombre de la tabla, introduce el nombre de la tabla que vas a crear en BigQuery.
  7. En la sección Esquema, no es necesario que haga nada. El esquema se describe automáticamente en los archivos Avro.

  8. (Opcional) Para crear particiones en la tabla, elige las opciones que quieras en Configuración de particiones y clústeres. Para obtener más información, consulta el artículo Crear tablas particionadas.

  9. (Opcional) En Filtro de partición, marque la casilla Requerir filtro de partición para que los usuarios incluyan una cláusula WHERE que especifique las particiones que se van a consultar. Si usas este filtro, es posible que rebajes los costes y mejores el rendimiento. Para obtener más información, consulta Requerir un filtro de partición en las consultas. Esta opción no está disponible si se selecciona Sin partición.

  10. (Opcional) Para agrupar la tabla, en el cuadro Orden de agrupación, introduzca entre uno y cuatro nombres de campo.

  11. (Opcional) Haz clic en Opciones avanzadas.

    • En Write preference (Preferencia de escritura), deja seleccionada la opción Write if empty (Escribir si está vacía). Esta opción crea una tabla y carga los datos en ella.
    • En Valores desconocidos, deje desactivada la opción Ignorar valores desconocidos. Esta opción solo se aplica a los archivos CSV y JSON.
    • En Encriptado, haz clic en Clave gestionada por el cliente para usar una clave de Cloud Key Management Service. Si dejas activado el ajuste Google-managed key, BigQuery cifra los datos en reposo.
  12. Haz clic en Crear tabla.

SQL

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

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

    Ir a BigQuery

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

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

  3. Haz clic en Ejecutar.

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

bq

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

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

Otras marcas opcionales son:

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

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

    Para obtener más información sobre las tablas agrupadas en clústeres, consulta los siguientes enlaces:

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

Para cargar datos Avro en BigQuery, introduce el siguiente comando:

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

Haz los cambios siguientes:

  • location es tu ubicación. La marca --location es opcional. Por ejemplo, si usas BigQuery en la región de Tokio, puedes definir el valor de la marca como asia-northeast1. Puedes definir un valor predeterminado para la ubicación mediante el archivo.bigqueryrc.
  • format es AVRO.
  • dataset es un conjunto de datos.
  • table es el nombre de la tabla en la que se cargan los datos.
  • path_to_source es un URI de Cloud Storage completo o una lista de URIs separados por comas. También se admiten comodines.

Ejemplos:

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

    bq load \
    --source_format=AVRO \
    mydataset.mytable \
    gs://mybucket/mydata.avro

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

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

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

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

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

    bq load \
    --source_format=AVRO \
    mydataset.mytable \
    gs://mybucket/mydata*.avro

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

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

API

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

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

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

  4. Para especificar el formato de datos Avro, asigna el valor AVRO a la propiedad sourceFormat.

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

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

Notas sobre la API:

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

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

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

Go

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

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

import (
	"context"
	"fmt"

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

// importAvro demonstrates loading Apache Avro data from Cloud Storage into a table.
func importAvro(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.avro")
	gcsRef.SourceFormat = bigquery.Avro
	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 Javainstrucciones de configuración de la guía de inicio rápido de BigQuery con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API Java de BigQuery.

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

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

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

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

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

      TableId tableId = TableId.of(datasetName, tableName);
      LoadJobConfiguration loadConfig =
          LoadJobConfiguration.of(tableId, sourceUri, FormatOptions.avro());

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

Node.js

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

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

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

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

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

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

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

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

  // 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), jobConfigurationLoad);

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

Python

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

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

from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

# TODO(developer): Set table_id to the ID of the table to create.
# table_id = "your-project.your_dataset.your_table_name

job_config = bigquery.LoadJobConfig(source_format=bigquery.SourceFormat.AVRO)
uri = "gs://cloud-samples-data/bigquery/us-states/us-states.avro"

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

Extraer datos JSON de datos Avro

Hay dos formas de asegurarse de que los datos Avro se carguen en BigQuery como JSONdatos:

  1. Anota tu esquema Avro con sqlType definido como JSON. Por ejemplo, si carga datos con el siguiente esquema Avro, la columna json_field se leerá como un tipo JSON:

    {
        "type": {"type": "string", "sqlType": "JSON"},
        "name": "json_field"
    }
  2. Especifica explícitamente el esquema de la tabla de destino de BigQuery y define el tipo de columna como JSON. Para obtener más información, consulta Especificar un esquema.

Si no especificas JSON como tipo en el esquema Avro o en el esquema de la tabla de BigQuery, los datos se leerán como STRING.

Añadir datos de Avro a una tabla o sobrescribirla

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

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

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

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

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

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

Consola

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

    Ir a BigQuery

  2. En el panel Explorador, expande tu proyecto y selecciona un conjunto de datos.

  3. Abre la opción Acciones y haz clic en Abrir.

  4. En el panel de detalles, haz clic en Crear tabla .

  5. En la página Crear tabla, ve a la sección Fuente:

    • En Crear tabla a partir de, selecciona Cloud Storage.
    • En el campo de origen, busca o introduce el URI de Cloud Storage. Ten en cuenta que no puedes incluir varios URIs en la consola Google Cloud , pero sí comodines. El segmento de Cloud Storage debe estar en la misma ubicación que el conjunto de datos que contiene la tabla que vas a añadir o sobrescribir.

      Seleccionar archivo

    • En Formato de archivo, selecciona Avro.

  6. En la página Crear tabla, ve a la sección Destino:

    • En Nombre del conjunto de datos, elige el conjunto de datos adecuado.

      Seleccionar conjunto de datos

    • En el campo Nombre de la tabla, introduzca el nombre de la tabla que quiera añadir o sobrescribir en BigQuery.

    • Verifica que el Tipo de tabla sea Tabla nativa.

  7. En la sección Esquema, no es necesario que haga nada. El esquema se describe automáticamente en los archivos Avro.

  8. En Configuración de partición y clúster, deja los valores predeterminados. No puedes convertir una tabla en una tabla con particiones o agrupada en clústeres añadiendo o sobrescribiendo datos, y la consola Google Cloud no admite la adición ni la sobrescritura de datos en tablas con particiones o agrupadas en clústeres en una tarea de carga.

  9. Haz clic en Advanced options (Opciones avanzadas).

    • En Preferencia de escritura, elija Añadir a la tabla o Sobrescribir tabla.
    • En Valores desconocidos, deje desactivada la opción Ignorar valores desconocidos. Esta opción solo se aplica a los archivos CSV y JSON.
    • En Encriptado, haz clic en Clave gestionada por el cliente para usar una clave de Cloud Key Management Service. Si dejas activado el ajuste Google-owned and managed key, BigQuery cifra los datos en reposo.
  10. Haz clic en Crear tabla.

SQL

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

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

    Ir a BigQuery

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

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

  3. Haz clic en Ejecutar.

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

bq

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

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

Otras marcas opcionales son:

  • --destination_kms_key: la clave de Cloud KMS para cifrar los datos de la tabla.
bq --location=location load \
--[no]replace \
--source_format=format \
dataset.table \
path_to_source

Haz los cambios siguientes:

  • location es tu ubicación. La marca --location es opcional. Puedes definir un valor predeterminado para la ubicación mediante el archivo.bigqueryrc.
  • format es AVRO.
  • dataset es un conjunto de datos.
  • table es el nombre de la tabla en la que se cargan los datos.
  • path_to_source es un URI de Cloud Storage completo o una lista de URIs separados por comas. También se admiten comodines.

Ejemplos:

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

    bq load \
    --replace \
    --source_format=AVRO \
    mydataset.mytable \
    gs://mybucket/mydata.avro

El siguiente comando carga datos de gs://mybucket/mydata.avro y añade datos a una tabla llamada mytable en mydataset.

    bq load \
    --noreplace \
    --source_format=AVRO \
    mydataset.mytable \
    gs://mybucket/mydata.avro

Para obtener información sobre cómo añadir y sobrescribir tablas con particiones mediante la herramienta de línea de comandos bq, consulta el artículo Añadir y sobrescribir datos de tablas con particiones.

API

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

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

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

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

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

Go

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

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

import (
	"context"
	"fmt"

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

// importAvroTruncate demonstrates loading Apache Avro data from Cloud Storage into a table
// and overwriting/truncating existing data in the table.
func importAvroTruncate(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.avro")
	gcsRef.SourceFormat = bigquery.Avro
	loader := client.Dataset(datasetID).Table(tableID).LoaderFrom(gcsRef)
	// Default for import jobs is to append data to a table.  WriteTruncate
	// specifies that existing data should instead be replaced/overwritten.
	loader.WriteDisposition = bigquery.WriteTruncate

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

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

Java

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

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

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

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

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

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

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

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

Node.js

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

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

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

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

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

async function loadTableGCSAvroTruncate() {
  /**
   * 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 = 'us_states';

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

  // 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), jobConfigurationLoad);

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

Python

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

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

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.AVRO,
)

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

Cargar datos de Avro con particiones de Hive

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

Conversiones Avro

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

Tipos primitivos

Tipo de datos Avro sin el atributo logicalType Tipo de datos de BigQuery Notas
null BigQuery ignora estos valores
booleano BOOLEAN
int INTEGER
long INTEGER
flotante FLOAT
doble FLOAT
bytes BYTES
cadena STRING Solo UTF-8

Tipos lógicos

De forma predeterminada, BigQuery ignora el atributo logicalType de la mayoría de los tipos y usa el tipo Avro subyacente. Para convertir los tipos lógicos de Avro en sus tipos de datos de BigQuery correspondientes, asigna el valor true a la marca --use_avro_logical_types con la herramienta de línea de comandos bq o asigna el valor useAvroLogicalTypes a la propiedad job resource cuando llames al método jobs.insert para crear una tarea de carga.

En la tabla siguiente se muestra la conversión de tipos lógicos de Avro a tipos de datos de BigQuery.

Tipo lógico de Avro Tipo de datos de BigQuery: tipo lógico inhabilitado Tipo de datos de BigQuery: tipo lógico habilitado
fecha INTEGER FECHA
time-millis INTEGER HORA
time_micros INTEGER (convertido de LONG) HORA
timestamp-millis INTEGER (convertido de LONG) TIMESTAMP
timestamp-micros INTEGER (convertido de LONG) TIMESTAMP
local-timestamp-millis INTEGER (convertido de LONG) DATETIME
local-timestamp-micros INTEGER (convertido de LONG) DATETIME
duración BYTES (convertido del tipo fixed de tamaño 12) BYTES (convertido del tipo fixed de tamaño 12)
decimal NUMERIC, BIGNUMERIC o STRING (consulta Tipo lógico decimal) NUMERIC, BIGNUMERIC o STRING (consulta Tipo lógico decimal)

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

Tipo lógico de fecha

En cualquier archivo Avro que quieras cargar, debes especificar los tipos lógicos de fecha con el siguiente formato:

{
       "type": {"logicalType": "date", "type": "int"},
       "name": "date_field"
}

Tipo lógico decimal

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

Por motivos de compatibilidad con versiones anteriores, si no se especifican los tipos de destino decimales, puede cargar un archivo Avro que contenga una columna bytes con el tipo lógico decimal en una columna BYTES de una tabla. En este caso, se ignora el tipo lógico decimal de la columna del archivo Avro. Este modo de conversión está obsoleto y puede que se elimine en el futuro.

Para obtener más información sobre el tipo lógico decimal de Avro, consulta la especificación de Apache Avro™ 1.8.2.

Tipo lógico de tiempo

En cualquier archivo Avro que quieras cargar, debes especificar los tipos lógicos de tiempo en uno de los siguientes formatos.

Para obtener una precisión de milisegundos:

{
       "type": {"logicalType": "time-millis", "type": "int"},
       "name": "time_millis_field"
}

Para obtener una precisión de microsegundos:

{
       "type": {"logicalType": "time-micros", "type": "int"},
       "name": "time_micros_field"
}

Tipo lógico de marca de tiempo

En cualquier archivo Avro que quiera cargar, debe especificar los tipos lógicos de marca de tiempo en uno de los siguientes formatos.

Para obtener una precisión de milisegundos:

{
       "type": {"logicalType": "timestamp-millis", "type": "long"},
       "name": "timestamp_millis_field"
}

Para obtener una precisión de microsegundos:

{
       "type": {"logicalType": "timestamp-micros", "type": "long"},
       "name": "timestamp_micros_field"
}

Tipo lógico Local-Timestamp

En cualquier archivo Avro que quieras cargar, debes especificar un tipo lógico local-timestamp en uno de los siguientes formatos.

Para obtener una precisión de milisegundos:

{
       "type": {"logicalType": "local-timestamp-millis", "type": "long"},
       "name": "local_timestamp_millis_field"
}

Para obtener una precisión de microsegundos:

{
       "type": {"logicalType": "local-timestamp-micros", "type": "long"},
       "name": "local_timestamp_micros_field"
}

Tipos complejos

Tipo de datos Avro Tipo de datos de BigQuery Notas
registro RECORD
  • Los alias se ignoran
  • El documento se convierte en una descripción de campo
  • Los valores predeterminados se definen en el momento de la lectura
  • Se ignora el orden
  • Se eliminan los campos recursivos: solo se mantiene el primer nivel de anidación de los campos recursivos.
enum STRING
  • La cadena es el valor simbólico de la enumeración.
  • Los alias se ignoran
  • El documento se convierte en una descripción de campo
array campos repetidos No se admiten matrices de matrices. Se ignoran las matrices que solo contienen tipos NULL.
map<T> RECORD BigQuery convierte un campo de mapa<T> de Avro en un RECORD repetido que contiene dos campos: una clave y un valor. BigQuery almacena la clave como una CADENA y convierte el valor al tipo de datos correspondiente en BigQuery.
unión
  • Campo que admite valores nulos
  • RECORD con una lista de campos que aceptan valores nulos
  • Si una unión solo tiene un tipo no nulo, se convierte en un campo anulable. .
  • De lo contrario, se convierte en un RECORD con una lista de campos que aceptan valores nulos. Solo se definirá uno de estos campos en el momento de la lectura.
Fijo BYTES
  • Los alias se ignoran
  • Se ignora el tamaño