Carga datos de Avro desde Cloud Storage

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

Cuando cargas los datos de Avro desde Cloud Storage, puedes cargarlos a una tabla o partición nueva o puedes agregarlos o reemplazarlos en una tabla o partición existentes. Cuando tus datos se cargan en BigQuery, se convierten en formato de columnas para Capacitor (formato de almacenamiento de BigQuery).

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

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

Nota: BigQuery no admite la carga de archivos de esquema Avro (.avsc) independientes. Para importar un esquema en BigQuery, especifica un archivo de esquema JSON.

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

Requisitos del archivo de entrada

Para evitar errores de resourcesExceeded cuando cargues archivos de Avro en BigQuery, sigue estos lineamientos:

• Mantén los tamaños de las filas en 50 MB o menos.
• Si la fila contiene muchos campos de arreglo o cualquier campo de arreglo muy largo, divide los valores del arreglo en campos separados.

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 y una tabla 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 a proyectos, carpetas y organizaciones.

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 y una tabla

Para almacenar tus datos, debes crear un conjunto de datos de BigQuery y, luego, crear una tabla de BigQuery dentro de ese conjunto de datos.

Ventajas de Avro

Avro es el formato preferido para cargar datos en BigQuery. Cargar archivos de Avro tiene las siguientes ventajas sobre CSV y JSON (delimitado por saltos de línea):

• El formato binario de Avro tiene estas características:
  • Carga más rápido. Los datos se pueden leer en paralelo, incluso si los bloques de datos están comprimidos.
  • No requiere escritura o serialización.
  • Es más fácil de analizar porque no hay problemas de codificación encontrados en otros formatos como ASCII.
• Cuando cargas los archivos de Avro en BigQuery, el esquema de la tabla se recupera de forma automática desde los datos de origen autodescriptivos.

Esquemas de Avro

Cuando cargas los archivos de Avro en una tabla nueva de BigQuery, el esquema de la tabla se recupera de forma automática mediante los datos de origen. 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 Avro en Cloud Storage:

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

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.avro:

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

Cuando importas varios archivos de Avro con diferentes esquemas de Avro, todos los esquemas deben ser compatibles con Resolución de esquema de Avro.

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

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.avro".

Compresión de Avro

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

• Snappy
• DEFLATE
• ZSTD

Carga datos de Avro en una tabla nueva

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

Console

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

   Ir a BigQuery

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

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

4. En el panel de detalles, haz clic en Crear tabla  (Create table).

5. En la página Crear tabla, en la sección Fuente haz lo siguiente:

   • En Create table from (Crear tabla desde), elige Google Cloud Storage.

   • En el campo de fuente, busca o escribe el URI de Cloud Storage. Ten en cuenta que no puedes incluir varios 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 quieres crear.

     

   • En File format (Formato de archivo), elige Avro.

6. En la sección Destination (Destino) de la página Create table (Crear tabla), haz lo siguiente:

   • En Nombre del conjunto de datos (Dataset name), elige 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 la tabla (Table name), escribe el nombre de la tabla que quieres crear en BigQuery.

7. En la sección Esquema no es necesaria ninguna acción. El esquema se describe a sí mismo en los archivos de Avro.

8. Para particionar la tabla, elige las opciones en la Configuración de partición y agrupamiento en clústeres (opcional). Para obtener más información, consulta Crea tablas particionadas.

9. Para el Filtro de partición, haz clic en la casilla Exigir filtro de partición para solicitar a los usuarios que incluyan una cláusula WHERE que especifique las particiones que deben consultarse (opcional). Exigir un filtro de partición puede reducir los costos y mejorar el rendimiento. Para obtener más información, consulta Cómo exigir un filtro de partición en las consultas. Esta opción no está disponible si se selecciona Sin particionar (No partitioning).

10. Para agrupar en clústeres la tabla, en la casilla Orden de agrupamiento en clústeres, escribe entre uno y cuatro nombres de campo (opcional).

11. Haz clic en Opciones avanzadas (opcional).

    • En Preferencia de escritura (Write preference), deja elegido Escribir si está vacía (Write if empty). Esta opción crea una tabla nueva y carga los datos en ella.
    • En Valores desconocidos (Unknown values), desmarca la opción Ignorar valores desconocidos (Ignore unknown values). Esta opción se aplica solo a los archivos CSV y JSON.
    • En Encriptación (Encryption), haz clic en Clave administrada por el cliente (Customer-managed key) para usar una clave de Cloud Key Management Service. Si dejas establecida la configuración Clave administrada por Google (Google-managed key), BigQuery encripta los datos en reposo.

12. 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, mediante 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 Avro en una nueva 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 OVERWRITE mydataset.mytable
   FROM FILES (
     format = 'avro',
     uris = ['gs://bucket/path/file.avro']);

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 AVRO 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, consulta Cómo exigir un filtro de partición en las consultas.
• --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 Avro en BigQuery, escribe 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 establecer el valor de la marca como asia-northeast1. Puedes configurar un valor predeterminado para la ubicación mediante el archivo .bigqueryrc.
• format es AVRO.
• dataset es un conjunto de datos existente.
• table es el nombre de la tabla en la que cargas datos.
• path_to_source es un URI de Cloud Storage completamente 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.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 a una tabla particionada por tiempo de transferencia llamada mytable en mydataset.

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

Con el siguiente comando, se cargan datos de gs://mybucket/mydata.avro en una tabla particionada llamada mytable en mydataset. La tabla está particionada en la columna mytimestamp.

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

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=AVRO \
    mydataset.mytable \
    gs://mybucket/mydata*.avro

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=AVRO \
    mydataset.mytable \
    "gs://mybucket/00/*.avro","gs://mybucket/01/*.avro"

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 completamente calificada en el formato gs://bucket/object. Cada URI puede contener un carácter comodín “*”.

4. Establece la propiedad sourceFormat en AVRO para especificar el formato de datos Avro.

5. Para comprobar el estado del trabajo, llama a jobs.get(job_id*). job_id es el ID del trabajo que muestra 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 incluirá información que describirá qué 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 sobre la API:

• Los trabajos de carga son atómicos y coherentes. Es decir, si falla uno, ninguno de los datos estará disponible y si uno se hace 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 con un ID de trabajo dado es idempotente. En otras palabras, puedes volver a intentarlo tantas veces como desees con el mismo ID de trabajo y al menos una de las operaciones será correcta.

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

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

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

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

Extrae datos JSON de datos de Avro

Existen dos maneras de garantizar que los datos de Avro se carguen en BigQuery como datos JSON:

1. Anota tu esquema Avro con sqlType configurado como JSON. Por ejemplo, si cargas datos con el siguiente esquema de Avro, la columna json_field se lee como un tipo JSON:

   {
       "type": {"type": "string", "sqlType": "JSON"},
       "name": "json_field"
   }

2. Especifica el esquema de la tabla de destino de BigQuery de forma explícita y establece el tipo de columna en JSON. Si deseas obtener más información, consulta Especifica un esquema.

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

Anexa o reemplaza una tabla con datos de Avro

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
Realiza la operación de escritura si la tabla está vacía.	No compatible	WRITE_EMPTY	Solo escribe los datos si la tabla está vacía.
Adjuntar 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.

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 datos de Avro a una tabla o reemplazar sus valores con estos, haz lo siguiente:

Console

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

   Ir a BigQuery

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

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

4. En el panel de detalles, haz clic en Crear tabla  (Create table).

5. En la página Crear tabla, en la sección Fuente haz lo siguiente:

   • En Create table from (Crear tabla desde), elige Cloud Storage.

   • En el campo de fuente, busca o escribe el URI de Cloud Storage. Ten en cuenta que no puedes incluir varios URI en la consola de Google Cloud, pero se admiten comodines. El bucket de Cloud Storage debe encontrarse en la misma ubicación que el conjunto de datos que contiene la tabla en la que agregas datos o los reemplazas.

     

   • En File format (Formato de archivo), elige Avro.

6. En la sección Destination (Destino) de la página Create table (Crear tabla), haz lo siguiente:

   • En Nombre del conjunto de datos (Dataset name), elige el conjunto de datos que corresponda.

     

   • En el campo Nombre de la tabla (Table name), escribe el nombre de la tabla a la que quieres agregar datos o que quieres reemplazar en BigQuery.

   • Verifica que Tipo de tabla (Table type) esté establecido en Tabla nativa (Native table).

7. En la sección Esquema no es necesaria ninguna acción. El esquema se describe a sí mismo en los archivos de Avro.

   Nota: Es posible cambiar 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.

8. En Configuración de partición y agrupamiento en clústeres, deja los valores predeterminados. No puedes agregar datos a una tabla ni reemplazarla para convertirla en una tabla particionada o agrupada en clústeres y la consola de Google Cloud no admite agregar datos a tablas particionadas o agrupadas en clústeres ni reemplazarlas en un trabajo de carga.

9. Haz clic en Opciones avanzadas.

   • En Preferencia de escritura, elige Adjuntar a la tabla o Reemplazar tabla.
   • En Valores desconocidos (Unknown values), desmarca la opción Ignorar valores desconocidos (Ignore unknown values). Esta opción se aplica solo a los archivos CSV y JSON.
   • En Encriptación (Encryption), haz clic en Clave administrada por el cliente (Customer-managed key) para usar una clave de Cloud Key Management Service. Si dejas establecida la configuración Clave administrada por Google (Google-managed key), BigQuery encripta los datos en reposo.

10. Haz clic en Crear tabla.

SQL

Usa la declaración DDL LOAD DATA. En el siguiente ejemplo, se agrega un archivo Avro 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 = 'avro',
     uris = ['gs://bucket/path/file.avro']);

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 AVRO. Debido a que los esquemas de Avro se recuperan de manera automática de los datos de origen autodescriptivos, no necesitas proporcionar una definición de esquema.

Nota: Es posible cambiar 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 mediante el archivo .bigqueryrc.
• format es AVRO.
• dataset es un conjunto de datos existente.
• table es el nombre de la tabla en la que cargas datos.
• path_to_source es un URI de Cloud Storage completamente 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.avro y se reemplazan los datos de una tabla llamada mytable en mydataset.

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

Con el siguiente comando, se cargan datos de gs://mybucket/mydata.avro y se adjuntan 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 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 completamente 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 AVRO.

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

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

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

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

Carga datos Avro con partición en colmena

BigQuery admite la carga de datos Avro con partición de subárbol almacenados en Cloud Storage y propagará las columnas con partición de subárbol como columnas en la tabla administrada de destino de BigQuery. Para obtener más información, consulta Carga datos particionados de forma externa de Cloud Storage.

Conversiones de Avro

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

Tipos básicos

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

Tipos lógicos

De forma predeterminada, BigQuery ignora el atributo logicalType para la mayoría de los tipos y usa el tipo de Avro subyacente en su lugar. Para convertir tipos lógicos de Avro en sus tipos de datos de BigQuery correspondientes, configura la marca --use_avro_logical_types en true con la herramienta de línea de comandos de bq o establece la propiedad useAvroLogicalTypes en los recurso de trabajo cuando llamas al método jobs.insert para crear un trabajo de carga.

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

Tipos lógicos de Avro	Tipo de datos de BigQuery: Tipo lógico inhabilitado	Tipo de datos de BigQuery: Tipo lógico habilitado
fecha	INTEGER	DATE
time-millis	INTEGER	TIME
time-micros	INTEGER (convertido desde LONG)	TIME
timestamp-millis	INTEGER (convertido desde LONG)	TIMESTAMP
timestamp-micros	INTEGER (convertido desde LONG)	TIMESTAMP
local-timestamp-millis	INTEGER (convertido desde LONG)	DATETIME
local-timestamp-micros	INTEGER (convertido desde LONG)	DATETIME
duración	BYTES (convertidos desde el tipo fixed de tamaño 12)	BYTES (convertidos desde el tipo fixed de tamaño 12)
decimal	NUMERIC, BIGNUMERIC o STRING (consulta Tipos lógicos decimales)	NUMERIC, BIGNUMERIC o STRING (consulta Tipos lógicos decimales)

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

Nota: Cuando realizas una exportación a Avro desde BigQuery, DATETIME se exporta como una STRING con una hora lógica personalizada que no se reconoce como DATETIME cuando se vuelve a importar a BigQuery.

Tipo lógico de fecha

En cualquier archivo Avro que desees cargar, debes especificar tipos lógicos de fecha en el siguiente formato:

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

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.

Para la retrocompatibilidad, si no se especifican los tipos de objetivo decimal, puedes cargar un archivo Avro que contenga una columna bytes con el tipo lógico decimal en una columna BYTES de una instancia existente. mesa En este caso, se ignora el tipo lógico decimal en la columna del archivo Avro. Este modo de conversión está obsoleto y es posible que se quite en el futuro.

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

Tipo lógico de tiempo

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

Para precisión de milisegundos:

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

Para la precisión de microsegundos, usa lo siguiente:

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

Tipo lógico de marca de tiempo

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

Para precisión de milisegundos:

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

Para la precisión de microsegundos, usa lo siguiente:

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

Tipo lógico de marca de tiempo local

En cualquier archivo Avro que desees cargar, debes especificar un tipo lógico de marca de tiempo local en uno de los siguientes formatos.

Para precisión de milisegundos:

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

Para la precisión de microsegundos, usa lo siguiente:

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

Tipos complejos

Tipos de datos de Avro	Tipo de datos de BigQuery	Notas
registro	RECORD	Se ignoran los alias El documento se convierte en una descripción de campo Los valores predeterminados se establecen a un tiempo de lectura. Se ignora el orden Los campos recursivos se borran: solo se mantiene el primer nivel de anidamiento para estos campos.
enum	STRING	La string es el valor simbólico de la enumeración Se ignoran los alias El documento se convierte en una descripción de campo
array	repeated fields	No se admiten los arreglos de arreglos. Se ignoran los arreglos que contienen solo tipos NULL.
map<T>	RECORD	BigQuery convierte un campo de Avro map <T> en un REGISTRO repetido que contiene dos campos: una clave y un valor. BigQuery almacena la clave como una STRING y convierte el valor a su tipo de datos correspondiente en BigQuery.
unión	Campo de valor nulo REGISTRO con una lista de campos de valor nulo	Cuando union solo tiene un tipo de valor nulo, se convierte en un campo de valor nulo. De lo contrario, se convierte en un REGISTRO con una lista de campos de valor nulo. Solo uno de estos campos se establecerán a un tiempo de lectura.
fijo	BYTES	Se ignoran los alias Se ignora el tamaño.

Limitaciones

• El formato de array anidado no es compatible con BigQuery. Los archivos Avro que usan este formato deben convertirse antes de la importación.
• En un archivo Avro, los nombres y los espacios de nombres para 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 más información, consulta Límites de trabajos de carga de BigQuery.