Carga datos de Avro desde 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 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 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.

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

Con este comando, se cargan todos los archivos en un solo comando de la CLI (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 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 admite los códecs DEFLATE y Snappy.

Permisos necesarios

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

Permisos de BigQuery

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

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

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

  • bigquery.dataEditor
  • bigquery.dataOwner
  • bigquery.admin

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

  • bigquery.user
  • bigquery.jobUser
  • bigquery.admin

Además, si un usuario tiene permisos bigquery.datasets.create, cuando cree un conjunto de datos, se le otorgará el acceso bigquery.dataOwner a este. El acceso de bigquery.dataOwner permite que el usuario cree y actualice tablas en el conjunto de datos a través de un trabajo de carga.

Para obtener más información sobre las funciones y los permisos de Cloud IAM en BigQuery, consulta Controla el acceso a los conjuntos de datos.

Permisos de Cloud Storage

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

La función de Cloud IAM predefinida storage.objectViewer puede otorgarse para proporcionar los permisos storage.objects.get y storage.objects.list.

Carga datos de Avro en una tabla nueva

Puedes cargar datos de Avro en una nueva tabla:

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

Para cargar datos de Avro de Cloud Storage en una tabla nueva de BigQuery, sigue estos pasos:

Console

  1. Abre la IU web de BigQuery en Cloud Console.
    Ir a Cloud Console

  2. En el panel de navegación, en la sección Recursos, expande tu proyecto y selecciona un conjunto de datos.

  3. En el lado derecho de la ventana, en el panel de detalles, haz clic en Create table (Crear tabla). El proceso de carga de datos es el mismo que el proceso para crear una tabla vacía.

    Crear tabla

  4. En la página Create table (Crear tabla), en la sección Source (Fuente), haz lo siguiente:

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

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

      Seleccionar archivo

    • Para File format (Formato de archivo), selecciona Avro.

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

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

      Ver conjunto de datos

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

    • En el campo Nombre de tabla, ingresa el nombre de la tabla que quieres crear en BigQuery.

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

  7. Para particionar la tabla, elige tus opciones en la Configuración de la partición y el clúster (opcional):

    • Para crear una tabla particionada, haz clic en Sin particionar, selecciona Particionar por campo y elige una columna DATE o TIMESTAMP. Esta opción no estará disponible si el esquema no incluye una columna DATE o TIMESTAMP.
    • Para crear una tabla particionada por tiempo de transferencia, haz clic en Sin particionar y selecciona Particionar por tiempo de transferencia.
  8. Para el Filtro de partición, haz clic en la casilla Exigir filtro de partición a fin de 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, lee la sección Consulta tablas particionadas. Esta opción no está disponible si se selecciona Sin particionar.

  9. Para agrupar la tabla, en la casilla Orden de agrupamiento en clústeres, ingresa entre uno y cuatro nombres de campo (opcional). En la actualidad, el agrupamiento en clústeres solo es compatible con tablas particionadas.

  10. Haz clic en Opciones avanzadas (opcional).

    • En Preferencia de escritura, deja seleccionado Escribir si está vacía. Esta opción crea una tabla nueva y carga los datos en ella.
    • En Cantidad de errores permitidos, acepta el valor predeterminado de 0 o ingresa la cantidad máxima de filas con errores que pueden ignorarse. Si la cantidad de filas con errores excede este valor, el trabajo generará un mensaje invalid y fallará.
    • En Valores desconocidos, desmarca la opción Ignorar valores desconocidos. Esta opción se aplica solo a los archivos CSV y JSON.
    • Para Encriptación, haz clic en Clave administrada por el cliente a fin de usar una clave de servicio de administración de claves. Si dejas establecida la configuración Clave administrada por Google, BigQuery encripta los datos en reposo.
  11. Haz clic en Crear tabla.

IU clásica

  1. Ve a la IU web de BigQuery.
    Ir a la IU web de BigQuery

  2. En el panel de navegación, coloca el cursor 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 fuente, sigue estos pasos:

    • Haz clic en Crear desde el origen.
    • En Ubicación, selecciona Cloud Storage y, en el campo de origen, ingresa el URI de Cloud Storage. Ten en cuenta que no puedes incluir varios URI en la IU web de BigQuery, pero sí 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 quieres crear.
    • Para el Formato de archivo, selecciona Avro.
  4. En la sección Tabla de destino, haz lo siguiente:

    • En Nombre de tabla, selecciona el conjunto de datos que corresponda y, en el campo de nombre de tabla, ingresa el nombre de la tabla que quieres crear en BigQuery.
    • Verifica que Tipo de tabla esté establecido en Tabla nativa.
  5. En la sección Esquema, no es necesaria ninguna acción. El esquema se describe a sí mismo en los archivos de Avro.

  6. En la sección Opciones, sigue estos pasos (opcional):

    • En Cantidad de errores permitidos, acepta el valor predeterminado de 0 o ingresa la cantidad máxima de filas con errores que pueden ignorarse. Si la cantidad de filas con errores excede este valor, el trabajo generará un mensaje invalid y fallará.
    • En Preferencia de escritura, deja seleccionado Escribir si está vacía. Esta opción crea una tabla nueva y carga los datos en ella.
    • Para realizar la partición de la tabla, sigue estos pasos:
      • Para Tipo de partición, haz clic en Ninguna y elige Día.
      • En Campo de partición:
      • Para crear una tabla particionada, elige una columna DATE o TIMESTAMP. Esta opción no estará disponible si el esquema no incluye una columna DATE o TIMESTAMP.
      • Para crear una tabla particionada por tiempo de transferencia, deja el valor predeterminado: _PARTITIONTIME.
      • Haz clic en la casilla Exigir filtro de partición para solicitar a los usuarios que incluyan una cláusula WHERE que especifique las particiones que desean consultar. Exigir un filtro de partición puede reducir los costos y mejorar el rendimiento. Para obtener más información, lee la sección Consulta tablas particionadas. Esta opción no estará disponible si el Tipo de partición está configurado como Ninguno.
    • Para agrupar en clústeres la tabla, en la casilla Agrupar campos, ingresa entre uno y cuatro nombres de campo.
    • En Encriptación de destino, elige Encriptación administrada por el cliente para usar una Clave del servicio de administración de claves para encriptar la tabla. Si dejas la configuración Default, BigQuery encripta los datos en reposo con una clave administrada por Google.
  7. Haz clic en Crear tabla.

CLI

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.

Proporciona la marca --location y establece el valor según tu ubicación (opcional).

Las siguientes son otras marcas opcionales:

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

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

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

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

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

En el comando anterior, se muestra 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 en 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 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

Con el siguiente comando, se cargan datos de gs://mybucket/mydata.avro en 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 verificar el estado del trabajo, llama a jobs.get(job_id*), en el que 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. Los errores recuperables se enumeran en la propiedad status.errors del objeto de trabajo que se muestra.

Notas de API:

  • Los trabajos de carga son atómicos y coherentes. Si 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 práctica recomendada, genera un ID único y pásalo como jobReference.jobId cuando llames a jobs.insert para crear un trabajo de carga. Este enfoque es más resistente al fallo de la red porque el cliente puede sondear o reintentar con el ID de trabajo conocido.

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

Python

Antes de probar este ejemplo, sigue las instrucciones de configuración de Python incluidas en la Guía de inicio rápido: usa bibliotecas cliente. Si deseas 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))

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 y en la IU web clásica de BigQuery, usa la opción de Preferencia de escritura para especificar qué acción tomar cuando cargues datos desde un archivo de origen o desde un resultado de consulta.

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

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

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

Puedes agregar o reemplazar una tabla de la siguiente manera:

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

Para agregar datos Avro a una tabla o reemplazar sus valores con estos, haz lo siguiente:

Console

  1. Abre la IU web de BigQuery en Cloud Console.
    Ir a Cloud Console

  2. En el panel de navegación, en la sección Recursos, expande tu proyecto y selecciona un conjunto de datos.

  3. En el lado derecho de la ventana, en el panel de detalles, haz clic en Create table (Crear tabla). El proceso para agregar y reemplazar datos en un trabajo de carga es el mismo que el de crear una tabla en un trabajo de carga.

    Crear tabla

  4. En la página Create table (Crear tabla), en la sección Source (Fuente), haz lo siguiente:

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

    • En el campo de fuente, busca o ingresa el URI de Cloud Storage. Ten en cuenta que no puedes incluir varios URI en la IU web de BigQuery, pero sí se admiten comodines. El depósito de Cloud Storage debe encontrarse en la misma ubicación que el conjunto de datos que contiene la tabla que agregas o reemplazas.

      Seleccionar archivo

    • Para File format (Formato de archivo), selecciona Avro.

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

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

      Seleccionar conjunto de datos

    • En el campo Nombre de tabla, ingresa el nombre de la tabla que quieres agregar o reemplazar en BigQuery.

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

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

  7. En Configuración de partición y agrupamiento en clústeres, deja los valores predeterminados. No se puede adjuntar ni reemplazar una tabla para convertirla en una tabla particionada o agrupada en clústeres; Cloud Console no admite que se adjunten ni reemplacen tablas particionadas o agrupadas en un trabajo de carga.

  8. Haz clic en Opciones avanzadas.

    • En Preferencia de escritura, elige Adjuntar a la tabla o Reemplazar tabla.
    • En Cantidad de errores permitidos, acepta el valor predeterminado de 0 o ingresa la cantidad máxima de filas con errores que pueden ignorarse. Si la cantidad de filas con errores excede este valor, el trabajo generará un mensaje invalid y fallará.
    • En Valores desconocidos, desmarca la opción Ignorar valores desconocidos. Esta opción se aplica solo a los archivos CSV y JSON.
    • Para Encriptación, haz clic en Clave administrada por el cliente a fin de usar una clave de servicio de administración de claves. Si dejas establecida la configuración Clave administrada por Google, BigQuery encripta los datos en reposo.

      Reemplazar tabla

  9. Haz clic en Crear tabla.

IU clásica

  1. Ve a la IU web de BigQuery.
    Ir a la IU web de BigQuery

  2. En el panel de navegación, coloca el cursor 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 para agregar y reemplazar datos en un trabajo de carga es el mismo que el de crear una tabla en un trabajo de carga.

  3. En la página Crear tabla, en la sección Datos fuente, sigue estos pasos:

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

    • En Nombre de la tabla, selecciona el conjunto de datos que corresponda y, en el campo de nombre de tabla, ingresa el nombre de la tabla que quieres agregar o reemplazar.
    • Verifica que Tipo de tabla esté establecido en Tabla nativa.
  5. En la sección Esquema, no es necesaria ninguna acción. La información del esquema es autodescriptiva en los archivos Avro.

  6. En la sección Opciones:

    • En Cantidad de errores permitidos, acepta el valor predeterminado de 0 o ingresa la cantidad máxima de filas con errores que pueden ignorarse. Si la cantidad de filas con errores excede este valor, el trabajo generará un mensaje invalid y fallará.
    • En Preferencia de escritura, elige Adjuntar a la tabla o Reemplazar tabla.
    • Deja los valores predeterminados en Tipo de partición, Campos de partición, Exigir filtro de partición y Campos de agrupamiento. No puedes agregar ni reemplazar una tabla para convertirla en una tabla particionada o agrupada; la IU web no admite agregar ni reemplazar tablas particionadas o agrupadas en un trabajo de carga.
    • En Encriptación de destino, elige Encriptación administrada por el cliente para usar una Clave del servicio de administración de claves para encriptar la tabla. Si dejas la configuración Default, BigQuery encripta los datos en reposo con una clave administrada por Google.
  7. Haz clic en Crear tabla.

CLI

Ingresa el comando bq load con la marca --replace para reemplazar la tabla. Usa la marca --noreplace para adjuntar 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.

Proporciona la marca --location y establece el valor según tu ubicación (opcional).

Las siguientes son otras marcas opcionales:

  • --max_bad_records: un número entero que especifica la cantidad máxima de registros incorrectos permitidos antes de que falle todo el trabajo. El valor predeterminado es 0. Como máximo, se muestran cinco errores de cualquier tipo, sin importar el valor --max_bad_records.
  • --destination_kms_key: la clave de 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

En la que:

  • location es tu ubicación. La marca --location es opcional. 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 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 reemplaza 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 desde gs://mybucket/mydata.avro y se anexan 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 adjuntar datos a tablas particionadas o reemplazarlos con la CLI, consulta: Anexa 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, configura la propiedad configuration.load.writeDisposition como WRITE_TRUNCATE o WRITE_APPEND.

Python

Antes de probar este ejemplo, sigue las instrucciones de configuración de Python incluidas en la Guía de inicio rápido: usa bibliotecas cliente. Si deseas 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))

Carga datos Avro con partición de subárbol

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 la página sobre cómo cargar 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

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 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.
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.
corregido 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)
duración BYTES (convertidos desde el tipo fixed de tamaño 12)
decimal NUMERIC (ver Tipo lógico decimal)

Para habilitar la conversión de los tipos lógicos de Avro en sus tipos de datos de BigQuery correspondientes, establece la marca --use_avro_logical_types en True mediante la herramienta de línea de comandos o establece la propiedad useAvroLogicalTypes en el 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 Tipos de datos de BigQuery convertidos
date DATE
time-millis TIME
time-micros TIME
timestamp-millis MARCA DE TIEMPO
timestamp-micros MARCA DE TIEMPO
duración 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 Avro bytes con un tipo lógico decimal puede tener como máximo un precision de 38 (cantidad total de dígitos) y como máximo un scale de 9 (dígitos a la derecha del punto decimal). El número de dígitos enteros, que es el precision menos el scale, puede ser como máximo 29. Por ejemplo, se admite un decimal con un precision de 38 y un scale de 9 porque el número de dígitos enteros es 29. Un decimal con un precision de 38 y un scale de 5 no es compatible porque la cantidad de dígitos enteros es 33.

Cuando cargas un archivo 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 de esquema de la tabla puede ser BYTES o NUMERIC. Si el tipo de datos de la columna es BYTES, se ignorará el tipo lógico decimal en la columna del archivo Avro.

Para obtener más información sobre el tipo lógico de Avro decimal, 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.