Cargar datos de Parquet desde Cloud Storage
En esta página se ofrece una descripción general de la carga de datos Parquet de Cloud Storage en BigQuery.
Parquet es un formato de datos orientado a columnas de código abierto que se usa mucho en el ecosistema de Apache Hadoop.
Cuando cargas datos Parquet desde Cloud Storage, puedes hacerlo en una tabla o partición nuevas, o bien añadir datos a una tabla o partición ya creadas o sobrescribirlas. Cuando tus datos se cargan en BigQuery, se convierten al formato de columnas de Capacitor (el formato de almacenamiento de BigQuery).
Cuando cargas datos de Cloud Storage en una tabla de BigQuery, el conjunto de datos que contiene la tabla debe estar en la misma ubicación regional o multirregional que el segmento de Cloud Storage.
Para obtener información sobre cómo cargar datos de Parquet desde un archivo local, consulta Cargar datos desde archivos locales.
Limitaciones
Cuando cargas datos en BigQuery desde un segmento de Cloud Storage, estás sujeto a las siguientes limitaciones:
- BigQuery no garantiza la coherencia de los datos de las fuentes de datos externas. Si se modifican los datos subyacentes mientras se ejecuta una consulta, se pueden producir comportamientos inesperados.
BigQuery no admite la gestión de versiones de objetos de Cloud Storage. Si incluyes un número de generación en el URI de Cloud Storage, el trabajo de carga fallará.
No puedes usar un comodín en el URI de Cloud Storage si alguno de los archivos que se van a cargar tiene un esquema diferente. Cualquier diferencia en la posición de las columnas se considera un esquema diferente.
Requisitos de los archivos de entrada
Para evitar errores resourcesExceeded
al cargar archivos Parquet en BigQuery, sigue estas directrices:
- El tamaño de las filas no debe superar los 50 MB.
- Si los datos de entrada contienen más de 100 columnas, plantéate reducir el tamaño de página para que sea inferior al tamaño de página predeterminado (1 * 1024 * 1024 bytes). Esto resulta especialmente útil si utilizas una compresión significativa.
- Para obtener un rendimiento óptimo, el tamaño de los grupos de filas debe ser de al menos 16 MiB. Los tamaños de grupo de filas más pequeños aumentan las operaciones de E/S y ralentizan las cargas y las consultas.
Antes de empezar
Asigna roles de gestión de identidades y accesos (IAM) que proporcionen a los usuarios los permisos necesarios para realizar cada tarea de este documento y crea un conjunto de datos para almacenar tus datos.
Permisos obligatorios
Para cargar datos en BigQuery, necesitas permisos de gestión de identidades y accesos para ejecutar un trabajo de carga y cargar datos en tablas y particiones de BigQuery. Si cargas datos desde Cloud Storage, también necesitas permisos de IAM para acceder al segmento que contiene tus datos.
Permisos para cargar datos en BigQuery
Para cargar datos en una tabla o partición de BigQuery, o bien para añadir o sobrescribir una tabla o partición, necesitas los siguientes permisos de gestión de identidades y accesos:
bigquery.tables.create
bigquery.tables.updateData
bigquery.tables.update
bigquery.jobs.create
Cada uno de los siguientes roles de gestión de identidades y accesos predefinidos incluye los permisos que necesitas para cargar datos en una tabla o partición de BigQuery:
roles/bigquery.dataEditor
roles/bigquery.dataOwner
roles/bigquery.admin
(incluye el permisobigquery.jobs.create
)bigquery.user
(incluye el permisobigquery.jobs.create
)bigquery.jobUser
(incluye el permisobigquery.jobs.create
)
Además, si tienes el permiso bigquery.datasets.create
, puedes crear y actualizar tablas mediante un trabajo de carga en los conjuntos de datos que crees.
Para obtener más información sobre los roles y permisos de IAM en BigQuery, consulta el artículo sobre funciones y permisos predefinidos.
Permisos para cargar datos desde Cloud Storage
Para obtener los permisos que necesitas para cargar datos desde un segmento de Cloud Storage, pide a tu administrador que te conceda el rol de gestión de identidades y accesos Administrador de Storage (roles/storage.admin
) en el segmento.
Para obtener más información sobre cómo conceder roles, consulta el artículo Gestionar el acceso a proyectos, carpetas y organizaciones.
Este rol predefinido contiene los permisos necesarios para cargar datos desde un segmento de Cloud Storage. Para ver los permisos exactos que se necesitan, despliega la sección Permisos necesarios:
Permisos obligatorios
Para cargar datos desde un segmento de Cloud Storage, se necesitan los siguientes permisos:
-
storage.buckets.get
-
storage.objects.get
-
storage.objects.list (required if you are using a URI wildcard)
También puedes obtener estos permisos con roles personalizados u otros roles predefinidos.
Crear conjunto de datos
Crea un conjunto de datos de BigQuery para almacenar tus datos.
Esquemas de Parquet
Cuando cargas archivos Parquet en BigQuery, el esquema de la tabla se obtiene automáticamente de los datos de origen autodescriptivos. Cuando BigQuery obtiene el esquema de los datos de origen, se usa el último archivo por orden alfabético.
Por ejemplo, supongamos que tiene los siguientes archivos Parquet en Cloud Storage:
gs://mybucket/00/ a.parquet z.parquet gs://mybucket/01/ b.parquet
Al ejecutar este comando en la herramienta de línea de comandos bq, se cargan todos los archivos (como una lista separada por comas) y el esquema se deriva de mybucket/01/b.parquet
:
bq load \ --source_format=PARQUET \ dataset.table \ "gs://mybucket/00/*.parquet","gs://mybucket/01/*.parquet"
Cuando carga varios archivos Parquet que tienen esquemas diferentes, las columnas idénticas especificadas en varios esquemas deben tener el mismo modo en cada definición de esquema.
Cuando BigQuery detecta el esquema, algunos tipos de datos de Parquet se convierten en tipos de datos de BigQuery para que sean compatibles con la sintaxis de GoogleSQL. Para obtener más información, consulta Conversiones de Parquet.
Para proporcionar un esquema de tabla al crear tablas externas, define la propiedadreferenceFileSchemaUri
en la API de BigQuery o el parámetro --reference_file_schema_uri
en la herramienta de línea de comandos bq con la URL del archivo de referencia.
Por ejemplo, --reference_file_schema_uri="gs://mybucket/schema.parquet"
.
Compresión de Parquet
BigQuery admite los siguientes códecs de compresión para el contenido de los archivos Parquet:
GZip
LZO_1C
LZO_1X
LZ4_RAW
Snappy
ZSTD
Cargar datos de Parquet en una tabla nueva
Para cargar datos Parquet en una tabla nueva, puede usar una de las siguientes opciones:
- La Google Cloud consola
- Comando
bq load
de la herramienta de línea de comandos bq - El método de la API
jobs.insert
y la configuración de un trabajoload
- Las bibliotecas de cliente
Para cargar datos Parquet de Cloud Storage en una tabla de BigQuery:
Consola
En la Google Cloud consola, ve a la página BigQuery.
- En el panel Explorador, expande tu proyecto y selecciona un conjunto de datos.
- En la sección Información del conjunto de datos, haz clic en Crear tabla.
- En el panel Crear tabla, especifica los siguientes detalles:
- En la sección Fuente, selecciona Google Cloud Storage en la lista Crear tabla a partir de.
A continuación, siga estos pasos:
- Selecciona un archivo del segmento de Cloud Storage o introduce el URI de Cloud Storage.
No puedes incluir varias URIs en la consola Google Cloud , pero sí caracteres comodín. El segmento de Cloud Storage debe estar en la misma ubicación que el conjunto de datos que contiene la tabla que quieres crear, añadir o sobrescribir.
- En Formato de archivo, selecciona Parquet.
- Selecciona un archivo del segmento de Cloud Storage o introduce el URI de Cloud Storage.
No puedes incluir varias URIs en la consola Google Cloud , pero sí caracteres comodín. El segmento de Cloud Storage debe estar en la misma ubicación que el conjunto de datos que contiene la tabla que quieres crear, añadir o sobrescribir.
- En la sección Destino, especifica los siguientes detalles:
- En Conjunto de datos, selecciona el conjunto de datos en el que quieras crear la tabla.
- En el campo Tabla, introduce el nombre de la tabla que quieras crear.
- Verifica que el campo Tipo de tabla sea Tabla nativa.
- En la sección Esquema, no es necesario que haga nada. El esquema se describe automáticamente en los archivos Parquet.
- Opcional: Especifica la configuración de partición y clúster. Para obtener más información, consulta los artículos sobre cómo crear tablas con particiones y cómo crear y usar tablas agrupadas en clústeres.
- Haz clic en Opciones avanzadas y haz lo siguiente:
- En Write preference (Preferencia de escritura), deja seleccionada la opción Write if empty (Escribir si está vacía). Con esta opción se crea una tabla y se cargan los datos en ella.
- Si quieres ignorar los valores de una fila que no estén presentes en el esquema de la tabla, selecciona Valores desconocidos.
- En Encriptado, haz clic en Clave gestionada por el cliente para usar una clave de Cloud Key Management Service. Si dejas el ajuste Google-managed key, BigQuery cifra los datos en reposo.
- Haz clic en Crear tabla.
SQL
Usa la
LOAD DATA
instrucción DDL.
En el siguiente ejemplo se carga un archivo Parquet en la nueva tabla mytable
:
En la Google Cloud consola, ve a la página BigQuery.
En el editor de consultas, introduce la siguiente instrucción:
LOAD DATA OVERWRITE mydataset.mytable FROM FILES ( format = 'PARQUET', uris = ['gs://bucket/path/file.parquet']);
Haz clic en
Ejecutar.
Para obtener más información sobre cómo ejecutar consultas, consulta Ejecutar una consulta interactiva.
bq
Usa el comando bq load
, especifica PARQUET
con la marca --source_format
e incluye un URI de Cloud Storage.
Puede incluir un solo URI, una lista de URIs separados por comas o un URI que contenga un comodín.
(Opcional) Proporcione la marca --location
y asigne el valor a su ubicación.
Otras marcas opcionales son:
--time_partitioning_type
: habilita la creación de particiones basadas en el tiempo en una tabla y define el tipo de partición. Los valores posibles sonHOUR
,DAY
,MONTH
yYEAR
. Esta marca es opcional cuando se crea una tabla con particiones en una columnaDATE
,DATETIME
oTIMESTAMP
. El tipo de partición predeterminado para la partición basada en tiempo esDAY
. No puedes cambiar la especificación de partición de una tabla que ya tengas.--time_partitioning_expiration
: número entero que especifica (en segundos) cuándo se debe eliminar una partición basada en el tiempo. La hora de vencimiento se calcula como la fecha UTC de la partición más el valor entero.--time_partitioning_field
: columnaDATE
oTIMESTAMP
que se usa para crear una tabla con particiones. Si se habilita la creación de particiones basadas en tiempo sin este valor, se creará una tabla con particiones por hora de ingestión.--require_partition_filter
: cuando se habilita esta opción, los usuarios deben incluir una cláusulaWHERE
que especifique las particiones que se van a consultar. Si usas este filtro, es posible que rebajes los costes y mejores el rendimiento. Para obtener más información, consulta Requerir un filtro de partición en las consultas.--clustering_fields
: lista separada por comas de hasta cuatro nombres de columna que se usa para crear una tabla agrupada en clústeres.--destination_kms_key
: la clave de Cloud KMS para cifrar los datos de la tabla.--column_name_character_map
: define el ámbito y la gestión de los caracteres en los nombres de las columnas, con la opción de habilitar nombres de columnas flexibles. Para obtener más información, consultaload_option_list
. Para obtener más información sobre los caracteres admitidos y no admitidos, consulta el artículo sobre los nombres de columnas flexibles.Para obtener más información sobre las tablas con particiones, consulta los siguientes artículos:
Para obtener más información sobre las tablas agrupadas en clústeres, consulta los siguientes enlaces:
Para obtener más información sobre el cifrado de tablas, consulta los siguientes artículos:
Para cargar datos Parquet en BigQuery, introduce el siguiente comando:
bq --location=LOCATION load \ --source_format=FORMAT \ DATASET.TABLE \ PATH_TO_SOURCE
Haz los cambios siguientes:
LOCATION
: tu ubicación. La marca--location
es opcional. Por ejemplo, si usas BigQuery en la región de Tokio, puedes asignar el valorasia-northeast1
a la marca. Puedes definir un valor predeterminado para la ubicación mediante el archivo.bigqueryrc.FORMAT
:PARQUET
.DATASET
: un conjunto de datos.TABLE
: el nombre de la tabla en la que vas a cargar los datos.PATH_TO_SOURCE
: un URI de Cloud Storage completo o una lista de URIs separados por comas. También se admiten comodines.
Ejemplos:
El siguiente comando carga datos de gs://mybucket/mydata.parquet
en una tabla llamada mytable
en mydataset
.
bq load \
--source_format=PARQUET \
mydataset.mytable \
gs://mybucket/mydata.parquet
El siguiente comando carga datos de gs://mybucket/mydata.parquet
en una tabla con particiones por tiempo de ingestión llamada mytable
en mydataset
.
bq load \
--source_format=PARQUET \
--time_partitioning_type=DAY \
mydataset.mytable \
gs://mybucket/mydata.parquet
El siguiente comando carga datos de gs://mybucket/mydata.parquet
en una tabla particionada llamada mytable
en mydataset
. que cuenta con particiones por la columna mytimestamp
.
bq load \
--source_format=PARQUET \
--time_partitioning_field mytimestamp \
mydataset.mytable \
gs://mybucket/mydata.parquet
El siguiente comando carga datos de varios archivos de gs://mybucket/
en una tabla llamada mytable
de mydataset
. El URI de Cloud Storage usa un comodín.
bq load \
--source_format=PARQUET \
mydataset.mytable \
gs://mybucket/mydata*.parquet
El siguiente comando carga datos de varios archivos de gs://mybucket/
en una tabla llamada mytable
de mydataset
. El comando incluye una lista de URIs de Cloud Storage separados por comas con comodines.
bq load \
--source_format=PARQUET \
mydataset.mytable \
"gs://mybucket/00/*.parquet","gs://mybucket/01/*.parquet"
API
Crea una tarea
load
que apunte a los datos de origen en Cloud Storage.(Opcional) Especifica tu ubicación en la propiedad
location
de la secciónjobReference
del recurso de empleo.La propiedad
source URIs
debe estar totalmente cualificada y tener el formatogs://BUCKET/OBJECT
. Cada URI puede contener un carácter comodín "*".Especifica el formato de datos Parquet asignando el valor
PARQUET
a la propiedadsourceFormat
.Para comprobar el estado del trabajo, llama a
jobs.get(JOB_ID*)
, sustituyendo JOB_ID por el ID del trabajo devuelto por la solicitud inicial.- Si
status.state = DONE
, el trabajo se ha completado correctamente. - Si la propiedad
status.errorResult
está presente, significa que se ha producido un error en la solicitud y que el objeto incluye información que describe lo que ha fallado. Si una solicitud falla, no se crea ninguna tabla y no se cargan datos. - Si no aparece
status.errorResult
, significa que el trabajo se ha completado correctamente, aunque es posible que se hayan producido algunos errores no críticos, como problemas al importar algunas filas. Los errores no críticos se indican en la propiedadstatus.errors
del objeto job devuelto.
- Si
Notas sobre la API:
Las tareas de carga son atómicas y coherentes: si una tarea de carga falla, no habrá datos disponibles, y si se completa correctamente, todos los datos estarán disponibles.
Como práctica recomendada, genera un ID único y pásalo como
jobReference.jobId
al llamar ajobs.insert
para crear un trabajo de carga. Este enfoque es más sólido ante fallos de red, ya que el cliente puede sondear o volver a intentar la operación con el ID de trabajo conocido.Llamar a
jobs.insert
en un ID de trabajo determinado es idempotente. Puedes volver a intentarlo tantas veces como quieras con el mismo ID de trabajo y, como máximo, una de esas operaciones se completará correctamente.
Go
Antes de probar este ejemplo, sigue las Goinstrucciones de configuración de la guía de inicio rápido de BigQuery con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API Go de BigQuery.
Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de cliente.
Java
Antes de probar este ejemplo, sigue las Javainstrucciones de configuración de la guía de inicio rápido de BigQuery con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API Java de BigQuery.
Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de cliente.
Node.js
Antes de probar este ejemplo, sigue las Node.jsinstrucciones de configuración de la guía de inicio rápido de BigQuery con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API Node.js de BigQuery.
Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de cliente.
PHP
Antes de probar este ejemplo, sigue las PHPinstrucciones de configuración de la guía de inicio rápido de BigQuery con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API PHP de BigQuery.
Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de cliente.
Python
Antes de probar este ejemplo, sigue las Pythoninstrucciones de configuración de la guía de inicio rápido de BigQuery con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API Python de BigQuery.
Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de cliente.
Usa el método Client.load_table_from_uri() para iniciar un trabajo de carga desde Cloud Storage. Para usar Parquet, define la propiedad LoadJobConfig.source_format en la cadenaPARQUET
y envía la configuración de la tarea como argumento job_config
al método load_table_from_uri()
.
Añadir datos Parquet a una tabla o sobrescribirla
Puedes cargar datos adicionales en una tabla desde archivos de origen o añadiendo resultados de consultas.
En la Google Cloud consola, usa la opción Preferencia de escritura para especificar qué acción se debe llevar a cabo cuando cargues datos de un archivo de origen o de un resultado de consulta.
Cuando cargas datos adicionales en una tabla, tienes las siguientes opciones:
Opción de consola | Marca de la herramienta bq | Propiedad de la API de BigQuery | Descripción |
---|---|---|---|
Escribir si está vacía | No compatible | WRITE_EMPTY |
Escribe los datos solo si la tabla está vacía. |
Añadir a tabla | --noreplace o --replace=false . Si no se especifica --[no]replace , el valor predeterminado es "append". |
WRITE_APPEND |
Predeterminado: Añade los datos al final de la tabla. |
Sobrescribir tabla | --replace o --replace=true |
WRITE_TRUNCATE |
Borra todos los datos de una tabla antes de escribir los nuevos datos. Esta acción también elimina el esquema de la tabla, la seguridad a nivel de fila y cualquier clave de Cloud KMS. |
Si cargas datos en una tabla, la tarea de carga puede añadir los datos o sobrescribir la tabla.
Puede añadir o sobrescribir una tabla de una de las siguientes formas:
- La Google Cloud consola
- Comando
bq load
de la herramienta de línea de comandos bq - El método de la API
jobs.insert
y la configuración de un trabajoload
- Las bibliotecas de cliente
Para añadir o sobrescribir una tabla con datos Parquet, sigue estos pasos:
Consola
En la Google Cloud consola, ve a la página BigQuery.
- En el panel Explorador, expande tu proyecto y selecciona un conjunto de datos.
- En la sección Información del conjunto de datos, haz clic en Crear tabla.
- En el panel Crear tabla, especifica los siguientes detalles:
- En la sección Fuente, selecciona Google Cloud Storage en la lista Crear tabla a partir de.
A continuación, siga estos pasos:
- Selecciona un archivo del segmento de Cloud Storage o introduce el URI de Cloud Storage.
No puedes incluir varias URIs en la consola Google Cloud , pero sí caracteres comodín. El segmento de Cloud Storage debe estar en la misma ubicación que el conjunto de datos que contiene la tabla que quieres crear, añadir o sobrescribir.
- En Formato de archivo, selecciona Parquet.
- Selecciona un archivo del segmento de Cloud Storage o introduce el URI de Cloud Storage.
No puedes incluir varias URIs en la consola Google Cloud , pero sí caracteres comodín. El segmento de Cloud Storage debe estar en la misma ubicación que el conjunto de datos que contiene la tabla que quieres crear, añadir o sobrescribir.
- En la sección Destino, especifica los siguientes detalles:
- En Conjunto de datos, selecciona el conjunto de datos en el que quieras crear la tabla.
- En el campo Tabla, introduce el nombre de la tabla que quieras crear.
- Verifica que el campo Tipo de tabla sea Tabla nativa.
- En la sección Esquema, no es necesario que haga nada. El esquema se describe automáticamente en los archivos Parquet.
- Opcional: Especifica la configuración de partición y clúster. Para obtener más información, consulta los artículos sobre cómo crear tablas con particiones y cómo crear y usar tablas agrupadas en clústeres. No puedes convertir una tabla en una tabla particionada o agrupada añadiéndole datos o sobrescribiéndola. La consola de Google Cloud no admite añadir datos a tablas particionadas o agrupadas, ni sobrescribirlas, en una tarea de carga.
- Haz clic en Opciones avanzadas y haz lo siguiente:
- En Preferencia de escritura, elija Añadir a la tabla o Sobrescribir tabla.
- Si quieres ignorar los valores de una fila que no estén presentes en el esquema de la tabla, selecciona Valores desconocidos.
- En Encriptado, haz clic en Clave gestionada por el cliente para usar una clave de Cloud Key Management Service. Si dejas el ajuste Google-managed key, BigQuery cifra los datos en reposo.
- Haz clic en Crear tabla.
SQL
Usa la
LOAD DATA
instrucción DDL.
En el siguiente ejemplo se añade un archivo Parquet a la tabla mytable
:
En la Google Cloud consola, ve a la página BigQuery.
En el editor de consultas, introduce la siguiente instrucción:
LOAD DATA INTO mydataset.mytable FROM FILES ( format = 'PARQUET', uris = ['gs://bucket/path/file.parquet']);
Haz clic en
Ejecutar.
Para obtener más información sobre cómo ejecutar consultas, consulta Ejecutar una consulta interactiva.
bq
Introduce el comando bq load
con la marca --replace
para sobrescribir la tabla. Usa la marca --noreplace
para añadir datos a la tabla. Si no se especifica ninguna marca, el valor predeterminado es añadir datos. Proporciona la marca --source_format
y asígnala a PARQUET
. Como los esquemas de Parquet se obtienen automáticamente de los datos de origen autodescriptivos, no es necesario que proporcione una definición de esquema.
(Opcional) Proporcione la marca --location
y asigne el valor a su ubicación.
Otras marcas opcionales son:
--destination_kms_key
: la clave de Cloud KMS para cifrar los datos de la tabla.
bq --location=LOCATION load \ --[no]replace \ --source_format=FORMAT \ DATASET.TABLE \ PATH_TO_SOURCE
Haz los cambios siguientes:
location
: tu ubicación. La marca--location
es opcional. Puedes definir un valor predeterminado para la ubicación mediante el archivo.bigqueryrc.format
:PARQUET
.dataset
: un conjunto de datos.table
: el nombre de la tabla en la que vas a cargar los datos.path_to_source
: un URI de Cloud Storage completo o una lista de URIs separados por comas. También se admiten comodines.
Ejemplos:
El siguiente comando carga datos de gs://mybucket/mydata.parquet
y
sobrescribe una tabla llamada mytable
en mydataset
.
bq load \
--replace \
--source_format=PARQUET \
mydataset.mytable \
gs://mybucket/mydata.parquet
El siguiente comando carga datos de gs://mybucket/mydata.parquet
y añade datos a una tabla llamada mytable
en mydataset
.
bq load \
--noreplace \
--source_format=PARQUET \
mydataset.mytable \
gs://mybucket/mydata.parquet
Para obtener información sobre cómo añadir y sobrescribir tablas con particiones mediante la herramienta de línea de comandos bq, consulta el artículo Añadir y sobrescribir datos de tablas con particiones.
API
Crea una tarea
load
que apunte a los datos de origen en Cloud Storage.(Opcional) Especifica tu ubicación en la propiedad
location
de la secciónjobReference
del recurso de empleo.La propiedad
source URIs
debe estar totalmente cualificada y tener el formatogs://BUCKET/OBJECT
. Puedes incluir varios URIs en una lista separada por comas. Ten en cuenta que también se admiten comodines.Especifica el formato de los datos asignando el valor
PARQUET
a la propiedadconfiguration.load.sourceFormat
.Especifica la preferencia de escritura asignando el valor
WRITE_TRUNCATE
oWRITE_APPEND
a la propiedadconfiguration.load.writeDisposition
.
Go
Antes de probar este ejemplo, sigue las Goinstrucciones de configuración de la guía de inicio rápido de BigQuery con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API Go de BigQuery.
Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de cliente.
Java
Antes de probar este ejemplo, sigue las Javainstrucciones de configuración de la guía de inicio rápido de BigQuery con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API Java de BigQuery.
Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de cliente.
Node.js
Antes de probar este ejemplo, sigue las Node.jsinstrucciones de configuración de la guía de inicio rápido de BigQuery con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API Node.js de BigQuery.
Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de cliente.
PHP
Antes de probar este ejemplo, sigue las PHPinstrucciones de configuración de la guía de inicio rápido de BigQuery con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API PHP de BigQuery.
Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de cliente.
Python
Antes de probar este ejemplo, sigue las Pythoninstrucciones de configuración de la guía de inicio rápido de BigQuery con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API Python de BigQuery.
Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de cliente.
Para añadir las filas a una tabla que ya tengas, define la propiedadLoadJobConfig.write_disposition
en WRITE_APPEND
.
Para sustituir las filas de una tabla, define la propiedad LoadJobConfig.write_disposition
como WRITE_TRUNCATE
.
Cargar datos de Parquet con particiones de Hive
BigQuery permite cargar datos Parquet particionados por Hive almacenados en Cloud Storage y rellena las columnas de partición de Hive como columnas en la tabla gestionada de BigQuery de destino. Para obtener más información, consulta Cargar datos con particiones externas.
Conversiones de Parquet
En esta sección se describe cómo analiza BigQuery varios tipos de datos al cargar datos Parquet.
Algunos tipos de datos de Parquet (como INT32
, INT64
, BYTE_ARRAY
y FIXED_LEN_BYTE_ARRAY
) se pueden convertir en varios tipos de datos de BigQuery. Para que BigQuery convierta correctamente los tipos de datos de Parquet, especifica el tipo de datos adecuado en el archivo Parquet.
Por ejemplo, para convertir el tipo de datos INT32
de Parquet al tipo de datos DATE
de BigQuery, especifica lo siguiente:
optional int32 date_col (DATE);
BigQuery convierte los tipos de datos Parquet en los tipos de datos de BigQuery que se describen en las siguientes secciones.
Conversiones de tipos
Tipo de datos de BigQuery | ||
---|---|---|
BOOLEAN |
Ninguno | BOOLEAN |
INT32 | Ninguno, INTEGER (UINT_8 , UINT_16 ,
UINT_32 , INT_8 , INT_16 ,
INT_32 )
|
INT64 |
INT32 | DECIMAL | NUMERIC, BIGNUMERIC o STRING |
INT32 |
DATE |
FECHA |
INT64 |
Ninguno, INTEGER (UINT_64 , INT_64 )
|
INT64 |
INT64 | DECIMAL | NUMERIC, BIGNUMERIC o STRING |
INT64 |
TIMESTAMP , precision=MILLIS
(TIMESTAMP_MILLIS )
|
TIMESTAMP |
INT64 |
TIMESTAMP , precision=MICROS
(TIMESTAMP_MICROS )
|
TIMESTAMP |
INT96 |
Ninguno | TIMESTAMP |
FLOAT |
Ninguno | FLOAT64 |
DOUBLE |
Ninguno | FLOAT64 |
BYTE_ARRAY |
Ninguno | BYTES |
BYTE_ARRAY |
STRING (UTF8 ) |
STRING |
FIXED_LEN_BYTE_ARRAY | DECIMAL | NUMERIC, BIGNUMERIC o STRING |
FIXED_LEN_BYTE_ARRAY |
Ninguno | BYTES |
Los grupos anidados se convierten en tipos STRUCT
.
No se admiten otras combinaciones de tipos de Parquet y tipos convertidos.
Tipos lógicos sin signo
Los tipos UINT_8
, UINT_16
, UINT_32
y UINT_64
de Parquet no tienen signo.
BigQuery tratará los valores de estos tipos como sin signo al cargarlos en una columna INTEGER
con signo de BigQuery. En el caso de UINT_64
, se devolverá un error si el valor sin signo supera el valor máximo de INTEGER
, que es 9.223.372.036.854.775.807.
Tipo lógico decimal
Los tipos lógicos Decimal
se pueden convertir en tipos NUMERIC
, BIGNUMERIC
o STRING
. El tipo convertido depende de los parámetros de precisión y escala del tipo lógico decimal
y de los tipos de destino decimales especificados. Especifica el tipo de destino decimal de la siguiente manera:
- Para un trabajo de carga con la API
jobs.insert
, usa el campoJobConfigurationLoad.decimalTargetTypes
. - Para un trabajo de carga con el comando
bq load
de la herramienta de línea de comandos bq, usa la marca--decimal_target_types
. - Para hacer una consulta en una tabla con fuentes externas, usa el campo
ExternalDataConfiguration.decimalTargetTypes
. - En el caso de una tabla externa persistente creada con DDL, usa la opción
decimal_target_types
.
Tipo lógico de enumeración
Los tipos lógicos Enum
se pueden convertir en STRING
o BYTES
. Especifique el tipo de objetivo convertido de la siguiente manera:
- Para un trabajo de carga con la API
jobs.insert
, usa el campoJobConfigurationLoad.parquetOptions
. - Para una tarea de carga con el comando
bq load
en la herramienta de línea de comandos bq, usa la marca--parquet_enum_as_string
. - En el caso de una tabla externa persistente creada con
bq mk
, usa la marca--parquet_enum_as_string
.
Mostrar tipo lógico
Puede habilitar la inferencia de esquemas para los tipos lógicos de Parquet LIST
. BigQuery comprueba si el nodo LIST
está en el formato estándar o en uno de los formatos descritos en las reglas de retrocompatibilidad:
// standard form
<optional | required> group <name> (LIST) {
repeated group list {
<optional | required> <element-type> element;
}
}
Si es así, el campo correspondiente al nodo LIST
del esquema convertido se trata como si el nodo tuviera el siguiente esquema:
repeated <element-type> <name>
Se omiten los nodos "list" y "element".
- Para un trabajo de carga con la API
jobs.insert
, usa el campoJobConfigurationLoad.parquetOptions
. - Para un trabajo de carga con el comando
bq load
de la herramienta de línea de comandos bq, usa la marca--parquet_enable_list_inference
. - En el caso de las tablas externas persistentes creadas con
bq mk
, usa la marca--parquet_enable_list_inference
. - En el caso de una tabla externa persistente creada con la instrucción
CREATE EXTERNAL TABLE
, usa la opciónenable_list_inference
.
Datos geoespaciales
Puedes cargar archivos Parquet que contengan WKT, WKB codificado en hexadecimal o GeoJSON en una columna STRING
, o WKB en una columna BYTE_ARRAY
. Para ello, especifica un esquema de BigQuery con el tipo GEOGRAPHY
. Para obtener más información, consulta Cargar datos geoespaciales.
También puedes cargar archivos GeoParquet. En este caso, las columnas descritas por los metadatos de GeoParquet se interpretan como de tipo GEOGRAPHY
de forma predeterminada. También puedes cargar los datos WKB sin procesar en una columna BYTES
proporcionando un esquema explícito. Para obtener más información, consulta Cargar archivos GeoParquet.
Conversiones de nombres de columnas
El nombre de una columna puede contener letras (a-z, A-Z), números (0-9) o guiones bajos (_), y debe empezar por una letra o un guion bajo. Si usa nombres de columna flexibles, BigQuery permite que los nombres de columna empiecen por un número. Tenga cuidado al empezar los nombres de las columnas con un número, ya que el uso de nombres de columnas flexibles con la API Storage Read o la API Storage Write de BigQuery requiere un tratamiento especial. Para obtener más información sobre la compatibilidad con nombres de columna flexibles, consulta el artículo Nombres de columna flexibles.
Los nombres de las columnas tienen una longitud máxima de 300 caracteres. Los nombres de columna no pueden usar ninguno de los siguientes prefijos:
_TABLE_
_FILE_
_PARTITION
_ROW_TIMESTAMP
__ROOT__
_COLIDENTIFIER
No se permiten nombres de columna duplicados, aunque se distinga entre mayúsculas y minúsculas. Por ejemplo, una columna llamada Column1
se considera idéntica a una columna llamada column1
. Para obtener más información sobre las reglas de nomenclatura de columnas, consulta Nombres de columna en la referencia de GoogleSQL.
Si el nombre de una tabla (por ejemplo, test
) es el mismo que el de una de sus columnas (por ejemplo, test
), la expresión SELECT
interpreta la columna test
como un STRUCT
que contiene todas las demás columnas de la tabla. Para evitar esta colisión, utiliza uno de los siguientes métodos:
No uses el mismo nombre para una tabla y sus columnas.
Asigna otro alias a la tabla. Por ejemplo, la siguiente consulta asigna el alias de tabla
t
a la tablaproject1.dataset.test
:SELECT test FROM project1.dataset.test AS t;
Incluya el nombre de la tabla cuando haga referencia a una columna. Por ejemplo:
SELECT test.test FROM project1.dataset.test;
Nombres de columna flexibles
Ahora tiene más flexibilidad a la hora de asignar nombres a las columnas, incluido un acceso ampliado a caracteres de idiomas distintos del inglés, así como a símbolos adicionales.
Asegúrate de usar el carácter de acento grave (`
) para incluir los nombres de columna flexibles si son identificadores entre comillas.
Los nombres de columna flexibles admiten los siguientes caracteres:
- Cualquier letra de cualquier idioma, representada por la expresión regular Unicode
\p{L}
. - Cualquier carácter numérico en cualquier idioma representado por la expresión regular Unicode
\p{N}
. - Cualquier carácter de puntuación de conector, incluidos los guiones bajos, tal como se representa en la expresión regular Unicode
\p{Pc}
. - Un guion o una raya representados por la expresión regular Unicode
\p{Pd}
. - Cualquier marca que acompañe a otro carácter, tal como se representa en la expresión regular Unicode
\p{M}
. Por ejemplo, acentos, diéresis o recuadros. - Los siguientes caracteres especiales:
- Un ampersand (
&
) representado por la expresión regular Unicode\u0026
. - El signo de porcentaje (
%
) representado por la expresión regular Unicode\u0025
. - Un signo igual (
=
) representado por la expresión regular Unicode\u003D
. - Un signo más (
+
) representado por la expresión regular Unicode\u002B
. - Dos puntos (
:
) representados por la expresión regular Unicode\u003A
. - Un apóstrofo (
'
) representado por la expresión regular Unicode\u0027
. - Signo menor que (
<
) representado por la expresión regular Unicode\u003C
. - El signo mayor que (
>
) representado por la expresión regular Unicode\u003E
. - Un signo de número (
#
) representado por la expresión regular Unicode\u0023
. - Una línea vertical (
|
) representada por la expresión regular Unicode\u007c
. - Espacio en blanco.
- Un ampersand (
Los nombres de columna flexibles no admiten los siguientes caracteres especiales:
- Un signo de exclamación (
!
) representado por la expresión regular Unicode\u0021
. - Una comilla (
"
) representada por la expresión regular Unicode\u0022
. - El símbolo del dólar (
$
) representado por la expresión regular Unicode\u0024
. - Un paréntesis de apertura (
(
) representado por la expresión regular Unicode\u0028
. - Un paréntesis de cierre (
)
) representado por la expresión regular Unicode\u0029
. - Un asterisco (
*
) representado por la expresión regular Unicode\u002A
. - Una coma (
,
) representada por la expresión regular Unicode\u002C
. - Un punto (
.
) representado por la expresión regular Unicode\u002E
. Los puntos no se sustituyen por guiones bajos en los nombres de las columnas de los archivos Parquet cuando se usa un mapa de caracteres de nombres de columna. Para obtener más información, consulta las limitaciones de las columnas flexibles. - Una barra (
/
) representada por la expresión regular Unicode\u002F
. - Un punto y coma (
;
) representado por la expresión regular Unicode\u003B
. - Un signo de interrogación (
?
) representado por la expresión regular Unicode\u003F
. - Una arroba (
@
) representada por la expresión regular Unicode\u0040
. - Un corchete de apertura (
[
) representado por la expresión regular Unicode\u005B
. - Una barra invertida (
\
) representada por la expresión regular Unicode\u005C
. - Un corchete de cierre (
]
) representado por la expresión regular Unicode\u005D
. - Un acento circunflejo (
^
) representado por la expresión regular Unicode\u005E
. - Un acento grave (
`
) representado por la expresión regular Unicode\u0060
. - Una llave de apertura {
{
) representada por la expresión regular Unicode\u007B
. - Una llave de cierre (
}
) representada por la expresión regular Unicode\u007D
. - Una virgulilla (
~
) representada por la expresión regular Unicode\u007E
.
Para obtener más directrices, consulta Nombres de columna.
La API Storage Read de BigQuery y la API Storage Write de BigQuery admiten los caracteres de columna ampliados. Para usar la lista ampliada de caracteres Unicode con la API Storage Read de BigQuery, debes definir una marca. Puede usar el atributo displayName
para obtener el nombre de la columna. En el siguiente ejemplo se muestra cómo definir una marca con el cliente de Python:
from google.cloud.bigquery_storage import types
requested_session = types.ReadSession()
#set avro serialization options for flexible column.
options = types.AvroSerializationOptions()
options.enable_display_name_attribute = True
requested_session.read_options.avro_serialization_options = options
Para usar la lista ampliada de caracteres Unicode con la API Storage Write de BigQuery, debes proporcionar el esquema con la notación column_name
, a menos que uses el objeto de escritura JsonStreamWriter
. En el siguiente ejemplo se muestra cómo proporcionar el esquema:
syntax = "proto2";
package mypackage;
// Source protos located in github.com/googleapis/googleapis
import "google/cloud/bigquery/storage/v1/annotations.proto";
message FlexibleSchema {
optional string item_name_column = 1
[(.google.cloud.bigquery.storage.v1.column_name) = "name-列"];
optional string item_description_column = 2
[(.google.cloud.bigquery.storage.v1.column_name) = "description-列"];
}
En este ejemplo, item_name_column
y item_description_column
son nombres de marcadores de posición que deben cumplir la convención de nomenclatura de protocol buffer. Ten en cuenta que las anotaciones column_name
siempre tienen prioridad sobre los nombres de los marcadores de posición.
Limitaciones
No se admiten nombres de columna flexibles en las tablas externas.
No puedes cargar archivos Parquet que contengan columnas con un punto (.) en el nombre.
Los nombres de las columnas de los archivos Parquet no distinguen entre mayúsculas y minúsculas cuando se cargan en BigQuery. Si los nombres son idénticos, pero no se distingue entre mayúsculas y minúsculas, se producirán colisiones. Para evitarlo, añade un guion bajo a uno de los nombres de columna duplicados o cambia el nombre de las columnas antes de cargarlas.
Depurar un archivo Parquet
Si sus trabajos de carga fallan debido a errores en los datos, puede usar PyArrow para verificar si sus archivos de datos Parquet están dañados. Si PyArrow no puede leer los archivos, es probable que el trabajo de carga de BigQuery los rechace. En el siguiente ejemplo se muestra cómo leer el contenido de un archivo Parquet mediante PyArrow:
from pyarrow import parquet as pq
# Read the entire file
pq.read_table('your_sample_file.parquet')
# Read specific columns
pq.read_table('your_sample_file.parquet',columns=['some_column', 'another_column'])
# Read the metadata of specific columns
file_metadata=pq.read_metadata('your_sample_file.parquet')
for col in file_metadata.row_group(0).to_dict()['columns']:
print col['column_path_in_schema']
print col['num_values']
Para obtener más información, consulta la documentación de PyArrow.