Carga de datos de Avro desde Google Cloud Storage

Carga archivos 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 suben 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 depósito 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.

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 de descripción automática.

Permisos necesarios

Cuando cargas datos en BigQuery, necesitas permisos de proyecto o de nivel de conjunto de datos que te permitan cargar datos en tablas y particiones de BigQuery nuevas o existentes. Si cargas datos desde Cloud Storage, también necesitas acceso al depósito que contiene tus datos.

Permisos de BigQuery

Cuando cargas datos en BigQuery desde Cloud Storage, se te debe otorgar la función bigquery.dataOwner o bigquery.dataEditor a nivel de proyecto o a nivel de conjunto de datos. Ambas funciones otorgan a los usuarios y grupos el permiso para cargar datos en una tabla nueva, agregar o reemplazar una tabla existente.

Otorgar las funciones a nivel de proyecto le da al usuario o al grupo permiso para cargar datos en tablas en cada conjunto de datos del proyecto. Otorgar las funciones a nivel de conjunto de datos le da al usuario o al grupo la capacidad para cargar datos solo en las tablas de ese conjunto de datos.

Para obtener más información sobre cómo configurar el acceso al conjunto de datos, consulta Control de acceso al conjunto de datos. Para obtener más información sobre las funciones de IAM en BigQuery, consulta Control de acceso.

Permisos de Cloud Storage

Para cargar datos desde un depósito de Cloud Storage, se te deben otorgar permisos de storage.objects.get en el nivel del proyecto o en ese depósito individual. Si usas un comodín de URI, también debes tener permisos storage.objects.list.

La función predefinida de IAM storage.objectViewer se puede otorgar para proporcionar permisos storage.objects.get y storage.objects.list.

Esquemas de Avro

Cuando cargas los archivos de Avro en 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 de Avro en Cloud Storage:

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

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

bq --location=US load --source_format=AVRO [DATASET].[TABLE_NAME] "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 de Avro se convierten en tipos de datos de BigQuery para hacerlos compatibles con la sintaxis SQL de BigQuery. Para obtener más información, consulta Conversiones de Avro.

Compresión de Avro

Los archivos de Avro comprimidos no son compatibles, pero los bloques de datos comprimidos sí los son. BigQuery es admite los códec DEFLATE y Snappy.

Carga datos de Avro en una tabla nueva

Si quieres cargar datos de Avro desde Cloud Storage en una tabla nueva de BigQuery o agregar datos de Avro en una tabla existente, sigue estos pasos:

IU web

  1. Dirígete a la IU web de BigQuery.
    Ir a la IU web de BigQuery

  2. En el panel de navegación, desplázate sobre un conjunto de datos, haz clic en el ícono de flecha hacia abajo imagen del ícono de flecha hacia abajo y, luego, en Crear tabla nueva. El proceso de carga de datos es el mismo que el proceso para crear una tabla vacía.

  3. En la página Crear tabla, en la sección Datos de origen, realiza lo siguiente:

    • En Location (Ubicación), selecciona Google Cloud Storage y en el campo de origen 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 estar en la misma ubicación que el conjunto de datos que contiene la tabla que vas a crear.
    • Para el Formato de archivo, selecciona Avro.
  4. En la página Crear tabla, en la sección Tabla de destino, realiza lo siguiente:

    • En Table name (Nombre de tabla), selecciona el conjunto de datos apropiado y, en el campo de nombre de tabla, ingresa el nombre de la tabla que vas a crear en BigQuery.
    • Verifica que Tipo de tabla esté configurado como Tabla nativa.
  5. En la sección Esquema, no hace falta que realices ninguna acción. El esquema se infiere desde los archivos de Avro.

  6. Haz clic en Crear tabla.

Línea de comandos

Usa el comando bq load, especifica AVRO como el 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 la marca --location y establece el valor en tu ubicación.

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

donde:

  • [LOCATION] es tu ubicación. La marca --location es opcional si tus datos están en la ubicación multirregión US o EU. Por ejemplo, si usas BigQuery en la región de Tokio, configura el valor de la marca como asia-northeast1. Puedes configurar un valor predeterminado para la ubicación con el archivo .bigqueryrc.
  • [FORMAT] es AVRO.
  • [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 calificado por completo o una lista de URI separados por comas. También se admiten comodines.

Ejemplos:

  • El siguiente comando carga datos desde gs://mybucket/mydata.avro en una tabla llamada mytable en mydataset. mybucket y mydataset se crearon en la ubicación multirregión US.

    bq --location=US load --source_format=AVRO mydataset.mytable gs://mybucket/mydata.avro
    
  • El siguiente comando carga datos de varios archivos en gs://mybucket/ en una tabla llamada mytable en mydataset. El URI de Cloud Storage usa un comodín. mybucket y mydataset se crearon en la ubicación multirregión US.

    bq --location=US load --source_format=AVRO mydataset.mytable gs://mybucket/mydata*.avro
    
  • El siguiente comando carga datos de varios archivos en gs://mybucket/ en una tabla llamada mytable en mydataset. El comando incluye una lista separada por comas de URI de Cloud Storage con comodines. mybucket y mydataset se crearon en la región asia-northeast1.

    bq --location=asia-northeast1 load --autodetect --source_format=AVRO mydataset.mytable "gs://mybucket/00/*.avro","gs://mybucket/01/*.avro"
    

API

Configura las siguientes propiedades para cargar datos de Avro con la API.

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

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

  3. Los URI de origen deben estar calificados por completo en el formato gs://[BUCKET]/[OBJECT]. Cada URI puede contener un carácter comodín “*”.

  4. Especifica el formato de datos de Avro con la configuración de la propiedad configuration.load.sourceFormat en AVRO.

  5. Para verificar el estado del trabajo, llama a jobs.get([JOB_ID]*), en el que [JOB_ID] es el ID del trabajo mostrado por la solicitud inicial.

    • Si se muestra status.state = DONE, el trabajo se completó con éxito
    • Si la propiedad status.errorResult está presente, la solicitud falló y ese objeto incluirá información que describe qué salió mal. Cuando una solicitud falla, no se crea ninguna tabla ni se agregan datos.
    • Si status.errorResult está ausente, el trabajo se completó con éxito, aunque pueden haber algunos errores no fatales, como problemas cuando se importan algunas filas. Los errores no fatales se enumeran en la propiedad status.errors del objeto de trabajo mostrado.

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.

  • Como recomendación, 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.

Python

Antes de probar esta muestra, sigue las instrucciones de configuración para Python 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 Python.

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

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

Reemplaza una tabla con datos de Avro

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 la consola Opción de la IU 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 Adjuntar a la tabla --noreplace o --replace=false; si --[no]replace no se especifica, la opción predeterminada es adjuntar WRITE_APPEND (Predeterminado) Adjunta los datos al final de la tabla.
Reemplazar tabla Reemplazar tabla --replace o --replace=true WRITE_TRUNCATE Borra todos los datos existentes de una tabla antes de escribir los datos nuevos.

De manera predeterminada, los trabajos de carga adjuntan datos a una tabla. Para reemplazar los datos de tablas mediante un trabajo de carga, sigue estos pasos:

IU web

  1. Dirígete a la IU web de BigQuery.
    Ir a la IU web de BigQuery

  2. En el panel de navegación, desplázate sobre un conjunto de datos, haz clic en el ícono de flecha hacia abajo imagen del ícono de flecha hacia abajo y, luego, en Crear tabla nueva. El proceso de carga de datos es el mismo que el proceso para crear una tabla vacía.

  3. En la página Crear tabla, en la sección Datos de origen, realiza lo siguiente:

    • En Ubicación, selecciona Google Cloud Storage y en el campo de origen, ingresa el URI de Cloud Storage. Ten en cuenta que no puedes incluir varios URI en la IU, pero se admiten comodines. El depósito de Cloud Storage debe estar en la misma ubicación que el conjunto de datos que contiene la tabla que creas o reemplazas.
    • Para el Formato de archivo, selecciona Avro.
  4. En la página Crear tabla, en la sección Tabla de destino, realiza lo siguiente:

    • En Nombre de la tabla, elige el conjunto de datos apropiado y en el campo de nombre de la tabla ingresa el nombre de la tabla que creas o reemplazas.
    • Verifica que Tipo de tabla esté configurado como Tabla nativa.
  5. En la sección Esquema, no hace falta que realices ninguna acción. La información del esquema se infiere desde los archivos de Avro.

  6. En la sección Opciones, en Escribir preferencia, elige Escribir si está vacía, Adjuntar a la tabla o bien Reemplazar tabla.

    Agregar esquema con agregar campos

  7. Haz clic en Crear tabla.

Línea de comandos

Ingresa el comando bq load con el marcador --replace para reemplazar la tabla. Proporciona la marca --location y establece el valor en tu ubicación. Usa la marca --noreplace para agregar datos a una tabla. Si no se especifica ningún marcador, se adjuntan datos de manera predeterminada.

bq --location=[LOCATION] load --[no]replace [DATASET].[TABLE] [PATH_TO_SOURCE]

donde:

  • [LOCATION] es tu ubicación. La marca --location es opcional si tus datos están en la ubicación multirregión US o EU.Puedes configurar un valor predeterminado para la ubicación con el archivo .bigqueryrc.
  • [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 calificado por completo o una lista de URI separados por comas. También se admiten comodines.

Ejemplos:

  • El siguiente comando carga datos desde gs://mybucket/mydata.avro y reemplaza una tabla llamada mytable en mydataset. mybucket y mydataset se crearon en la ubicación multirregión US.

    bq --location=US load --replace --source_format=AVRO mydataset.mytable gs://mybucket/mydata.avro
    
  • El siguiente comando carga datos desde gs://mybucket/mydata.avro y agrega los datos a una tabla llamada mytable en mydataset. mybucket y mydataset se crearon en la región asia-northeast1.

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

API

Configura las siguientes propiedades para cargar datos CSV con la API.

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

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

  3. Los URI de origen deben estar calificados por completo en el formato gs://[BUCKET]/[OBJECT]. Puedes incluir varios URI en una lista separada por comas. Ten en cuenta que los comodines también son compatibles cuando se cargan datos CSV desde Google Cloud Storage.

  4. Establece la propiedad configuration.load.sourceFormat como AVRO para especificar el formato de datos.

  5. Configura la propiedad configuration.load.writeDisposition como WRITE_TRUNCATE, WRITE_APPEND o WRITE_EMPTY para especificar la preferencia de escritura.

Python

Antes de probar esta muestra, sigue las instrucciones de configuración para Python 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 Python.

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

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

Tipos básicos

Tipos de datos de Avro Tipo de datos de BigQuery Notas
null BigQuery ignora estos valores
boolean BOOLEAN
int INTEGER
long INTEGER
float FLOAT
double FLOAT
bytes BYTES
bytes con un tipo lógico decimal NUMERIC
string STRING Solo UTF-8

Tipos complejos

Tipos de datos de Avro Tipo de datos de BigQuery Notas
record 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 eliminan: 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
arrray 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.
union
  • 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.
fixed BYTES
  • Se ignoran los alias
  • Se ignora el tamaño

Tipos lógicos

De forma predeterminada, BigQuery ignora el atributo logicalType y usa el tipo de Avro subyacente en su lugar.

Tipos lógicos de Avro Tipo de datos de BigQuery
date INTEGER
time-millis INTEGER
time-micros INTEGER (convertido desde LONG)
timestamp-millis INTEGER (convertido desde LONG)
timestamp-micros INTEGER (convertido desde LONG)
duration BYTES (convertidos desde tipo fixed de tamaño 12)
decimal NUMERIC (ver Tipo lógico decimal)

Si quieres habilitar la conversión de los tipos lógicos de Avro a sus tipos de datos de BigQuery correspondientes, configura la marca --use_avro_logical_types en True con la herramienta de línea de comandos o estblece la propiedad useAvroLogicalTypes en el recurso del trabajo cuando llames al método jobs.insert con el fin de crear una carga de trabajo.

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 Tipos de datos de BigQuery convertidos
date DATE
time-millis TIME
time-micros TIME
timestamp-millis TIMESTAMP
timestamp-micros TIMESTAMP
duration BYTES (convertidos desde tipo fixed de tamaño 12)
decimal NUMERIC (ver Tipo lógico decimal)

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

Tipos lógicos decimales

Un tipo bytes de Avro con un tipo lógico decimal puede tener como máximo una precision de 38 (cantidad total de dígitos) y como máximo una scale de 9 (dígitos a la derecha del decimal). La cantidad de números enteros, que es la precision menos la scale, puede ser como máximo de 29. Por ejemplo, un decimal con una precision de 38 y una scale de 9 se admite porque la cantidad de número enteros es 29. Un decimal con una precision de 38 y una scale de 5 no se admite porque la cantidad de números enteros es 33.

Cuando cargas un archivo de Avro que contiene una columna bytes con el tipo lógico decimal en una tabla existente, el tipo de datos de la columna en la definición del esquema de la tabla puede ser BYTES o NUMERIC. Si el tipo de datos de la columna es BYTES, el tipo lógico decimal en la columna en el archivo de Avro se ignora.

Si deseas obtener más información sobre los tipos lógicos decimal de Avro, consulta la Especificación de Apache Avro™ 1.8.2.

¿Te sirvió esta página? Envíanos tu opinión:

Enviar comentarios sobre…

¿Necesitas ayuda? Visita nuestra página de asistencia.