Puedes cargar datos en BigQuery desde Cloud Storage o desde un archivo local como una operación por lotes. Los datos fuente pueden estar en cualquiera de los siguientes formatos:
- Avro
- Valores separados por comas (CSV)
- JSON (delimitado por saltos de línea)
- ORC
- Parquet
- Exportaciones de Firestore almacenadas en Cloud Storage
También puedes usar el Servicio de transferencia de datos de BigQuery para configurar cargas recurrentes de Cloud Storage en BigQuery.
Permisos necesarios
Cuando cargas datos en BigQuery, necesitas permisos para ejecutar un trabajo de carga y permisos que te habiliten a cargar datos en tablas y particiones nuevas o existentes de BigQuery. 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 obligatorios si los datos se cargan en una tabla o partición nueva, o si se reemplaza una tabla o partición o se agregan datos a esta.
bigquery.tables.create
bigquery.tables.updateData
bigquery.jobs.create
Las siguientes funciones predefinidas de IAM incluyen los permisos bigquery.tables.create
y bigquery.tables.updateData
:
bigquery.dataEditor
bigquery.dataOwner
bigquery.admin
Las siguientes funciones predefinidas de IAM incluyen los permisos bigquery.jobs.create
:
bigquery.user
bigquery.jobUser
bigquery.admin
Además, si un usuario tiene permisos bigquery.datasets.create
, se le otorga el acceso bigquery.dataOwner
cuando crea un conjunto de datos.
El acceso bigquery.dataOwner
permite que el usuario cree y actualice tablas en el conjunto de datos mediante un trabajo de carga.
Para obtener más información sobre las funciones y permisos de IAM en BigQuery, consulta Control de acceso.
Permisos de Cloud Storage
Para cargar datos desde un bucket de Cloud Storage, debes tener permisos storage.objects.get
. Si usas un comodín de URI, también debes tener permisos storage.objects.list
.
Se puede otorgar la función predefinida de IAM storage.objectViewer
para proporcionar los permisos storage.objects.get
y storage.objects.list
.
Carga datos desde Cloud Storage
BigQuery es compatible con la carga de datos desde cualquiera de las siguientes clases de almacenamiento de Cloud Storage:
- Estándar
- Nearline
- Coldline
- Archivo
Para obtener información sobre cómo cargar datos en BigQuery, consulta la página de tu formato de datos:
Para obtener información sobre cómo configurar una carga recurrente de Cloud Storage a BigQuery, consulta Transferencias de Cloud Storage.
Consideraciones de ubicación
Cuando elijas una ubicación para tus datos, ten en cuenta esta información:
- Ubica los depósitos de Cloud Storage para cargar datos.
- Si tu conjunto de datos de BigQuery está en una ubicación multirregional, el bucket de Cloud Storage que contiene los datos que cargas debe estar en un bucket regional o multirregional en la misma ubicación. Por ejemplo, si tu conjunto de datos de BigQuery está en la UE, el bucket de Cloud Storage debe estar en un bucket regional o multirregional en la UE.
- Si tu conjunto de datos está en una ubicación regional, tu bucket de Cloud Storage debe ser un bucket regional en la misma ubicación. Por ejemplo, si tu conjunto de datos está en la región de Tokio, tu bucket de Cloud Storage debe ser un bucket regional en Tokio.
- Excepción: Si el conjunto de datos se encuentra en la ubicación multirregional de los EE.UU., puedes cargar datos desde un depósito de Cloud Storage en cualquier ubicación regional o multirregional.
- Desarrolla un plan de administración de datos.
- Si eliges un recurso de almacenamiento regional, como un conjunto de datos de BigQuery o un depósito de Cloud Storage, debes desarrollar un plan para administrar tus datos geográficamente.
Para obtener más información sobre las ubicaciones de Cloud Storage, consulta Ubicaciones de depósitos en la documentación de Cloud Storage.
No puedes cambiar la ubicación de un conjunto de datos después de crearlo, pero puedes hacer una copia del conjunto de datos o moverlo manualmente. Para obtener más información, consulte:
Recupera el URI de Cloud Storage
Para cargar los datos desde la fuente de datos de Cloud Storage, debes proporcionar el URI de Cloud Storage.
El URI de Cloud Storage incluye el nombre del bucket y tu objeto (nombre del archivo).
Por ejemplo, si el depósito de Cloud Storage se llama mybucket
y el archivo de datos se llama myfile.csv
, el URI del depósito será gs://mybucket/myfile.csv
.
Si los datos se separan en varios archivos, puedes usar un comodín en el URI. Para obtener más información, consulta la documentación sobre los URI de solicitud de Cloud Storage.
BigQuery no admite los URI de origen que incluyen varias barras consecutivas después de la doble barra inicial. Los nombres de los objetos de Cloud Storage pueden contener varios caracteres de barras consecutivas (“/”). Sin embargo, BigQuery convierte varias barras consecutivas en una sola barra. Por ejemplo, el URI de origen que se muestra a continuación, a pesar de ser válido en Cloud Storage, no funciona en BigQuery: gs://bucket/my//object//name
.
Para recuperar el URI de Cloud Storage, sigue estos pasos:
Abre Cloud Storage Console
Explora la ubicación del objeto (archivo) que contiene los datos de origen.
En la parte superior de la consola de Cloud Storage, toma nota de la ruta al objeto. Para redactar el URI, reemplaza
gs://bucket/file
por la ruta adecuada, por ejemplo,gs://mybucket/myfile.json
. bucket es el nombre del depósito de Cloud Storage y file es el nombre del objeto (archivo) que contiene los datos.
Admisión de comodines para el URI de Cloud Storage
Si tus datos de Cloud Storage están separados en varios archivos que comparten un nombre base común, puedes usar un comodín en el URI cuando cargas los datos.
Para agregar un comodín al URI de Cloud Storage, debes agregar un asterisco (*
) al nombre base. Por ejemplo, si tienes dos archivos llamados fed-sample000001.csv
y fed-sample000002.csv
, el URI del depósito es gs://mybucket/fed-sample*
.
Luego, puedes usar este URI de comodín en Cloud Console, la herramienta de línea de comandos de bq
, la API o las bibliotecas cliente.
Solo puedes usar un comodín para los objetos (nombres de archivos) dentro de tu bucket. El comodín puede aparecer dentro o al final del nombre del objeto. No se admite la adición de un comodín al nombre del bucket.
Para las exportaciones de Google Datastore, solo se puede especificar un URI, y este debe terminar con .backup_info
o .export_metadata
.
No se permite el carácter comodín de asterisco en los siguientes casos:
- Cuando creas tablas externas vinculadas a exportaciones de Datastore o Firestore.
- Cuando cargas datos de exportación de Datastore o Firestore desde Cloud Storage.
Limitaciones
Estás sujeto a las siguientes limitaciones cuando cargas datos en BigQuery desde un bucket de Cloud Storage:
- Si la ubicación de tu conjunto de datos está configurada en un valor diferente a
US
, el depósito de Cloud Storage regional o multirregional debe estar en la misma región que el conjunto de datos. - BigQuery no garantiza la coherencia de los datos provenientes de fuentes de datos externas. Los cambios en los datos subyacentes mientras se ejecuta una consulta pueden dar como resultado un comportamiento inesperado.
Según el formato de tus datos de origen de Cloud Storage, puede haber limitaciones adicionales. Para obtener más información, consulte:
- Limitaciones de CSV
- Limitaciones de JSON
- Limitaciones de exportación de Datastore
- Limitaciones de exportación de Firestore
- Limitaciones sobre datos anidados y repetidos
Carga datos de archivos locales
Puedes cargar datos desde una fuente de datos legible (como tu máquina local) mediante una de las siguientes opciones:
- Google Cloud Console
- El comando
bq load
de la herramienta de línea de comandos debq
- La API
- Las bibliotecas cliente
Cuando cargas datos mediante Cloud Console o la herramienta de línea de comandos de bq
, se crea un trabajo de carga de forma automática.
Para cargar datos desde una fuente de datos local, sigue los pasos que se detallan a continuación:
Console
Abre la página de BigQuery en Cloud Console.
En el panel de navegación, en la sección Recursos, expande tu proyecto de Google Cloud y selecciona un conjunto de datos.
En el lado derecho de la ventana, en el panel de detalles, haz clic en Crear tabla (Create table). El proceso de carga de datos es el mismo que el que se usa para crear una tabla vacía.
En la página Crear tabla (Create table), en la sección Origen (Source) haz lo siguiente:
Para Crear tabla desde (Create table from), selecciona Subir (Upload).
En Seleccionar archivo (Select file), haz clic en Navegar (Browse).
Busca el archivo y haz clic en Abrir. Ten en cuenta que los comodines y las listas separadas por comas no son compatibles con archivos locales.
En Formato de archivo (File format), selecciona CSV, JSON (delimitado por saltos de línea) (JSON [newline delimited]), Avro, ORC o Parquet.
En la página Crear tabla (Create table), en la sección Destino (Destination), haz lo siguiente:
En Nombre del conjunto de datos (Dataset name), selecciona el conjunto de datos que corresponda.
En el campo Nombre de la tabla, ingresa el nombre de la tabla que quieres crear en BigQuery.
Verifica que Tipo de tabla (Table type) esté configurado como Tabla nativa (Native table).
En la sección Esquema, ingresa la definición del esquema.
Para los archivos CSV y JSON, puedes marcar la opción Detección automática (Automatically detect) a fin de habilitar la detección automática del esquema. La información del esquema se describe de forma automática en los datos de origen para otros tipos de archivos compatibles.
También puedes ingresar la información del esquema de forma manual, como se indica a continuación:
Haz clic en Editar como texto e ingresa el esquema de la tabla como un arreglo JSON:
Usa la opción Agregar campo para ingresar el esquema de forma manual.
Selecciona los elementos aplicables en la sección Opciones avanzadas. Para obtener información sobre las opciones disponibles, consulta Opciones de CSV y Opciones de JSON.
Opcional: En las Opciones avanzadas, elige la disposición de escritura:
- Escribir si está vacía: Escribe los datos solo si la tabla está vacía.
- Agregar a la tabla: Agrega los datos al final de la tabla. Esta configuración es la predeterminada.
- Reemplazar tabla: Borra todos los datos existentes en la tabla antes de escribir los datos nuevos.
Haz clic en Crear tabla.
bq
Usa el comando bq load
y especifica el valor source_format
y la ruta de acceso al archivo local.
Opcional: Proporciona la marca --location
y configura el valor en tu ubicación.
Para cargar datos a un proyecto que no sea el predeterminado, agrega el ID del proyecto al conjunto de datos en el siguiente formato: PROJECT_ID:DATASET
.
bq --location=LOCATION load \ --source_format=FORMAT \ PROJECT_ID:DATASET.TABLE \ PATH_TO_SOURCE \ SCHEMA
Reemplaza lo siguiente:
LOCATION
: Es tu ubicación. La marca--location
es opcional. Por ejemplo, si usas BigQuery en la región de Tokio, establece el valor de la marca enasia-northeast1
. Puedes configurar un valor predeterminado para la ubicación con el archivo .bigqueryrc.FORMAT
: EsCSV
,AVRO
,PARQUET
,ORC
, oNEWLINE_DELIMITED_JSON
.project_id
: Es el ID del proyecto.dataset
: Es un conjunto de datos existente.table
: Es el nombre de la tabla en la que se están cargando los datos.path_to_source
: Es la ruta del archivo local.schema
: Es un esquema válido. El esquema puede ser un archivo JSON local o se puede escribir intercalado como parte del comando. También puedes usar la marca--autodetect
en lugar de proporcionar una definición de esquema.
Además, puedes agregar marcas para las opciones que te permiten controlar cómo BigQuery analiza los datos. Por ejemplo, puedes usar la marca --skip_leading_rows
para ignorar las filas del encabezado en un archivo CSV. Si deseas obtener más información, consulta Opciones de CSV y Opciones de JSON.
Ejemplos:
El siguiente comando carga un archivo JSON local delimitado por saltos de línea (mydata.json
) en una tabla llamada mytable
en mydataset
en tu proyecto predeterminado. El esquema se define en un archivo de esquema local llamado myschema.json
.
bq load \
--source_format=NEWLINE_DELIMITED_JSON \
mydataset.mytable \
./mydata.json \
./myschema.json
Con el siguiente comando, se carga un archivo CSV local (mydata.csv
) en una tabla llamada mytable
en mydataset
en myotherproject
. El esquema se define intercalado en el formato FIELD:DATA_TYPE, FIELD:DATA_TYPE
.
bq load \
--source_format=CSV \
myotherproject:mydataset.mytable \
./mydata.csv \
qtr:STRING,sales:FLOAT,year:STRING
Con el siguiente comando, se carga un archivo CSV local (mydata.csv
) en una tabla llamada mytable
en mydataset
en tu proyecto predeterminado. El esquema se define mediante la detección automática de esquemas.
bq load \
--autodetect \
--source_format=CSV \
mydataset.mytable \
./mydata.csv
C#
Antes de probar este ejemplo, sigue las instrucciones de configuración para C# incluidas en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Si deseas obtener más información, consulta la documentación de referencia de la API de C# de BigQuery.
El siguiente código demuestra cómo cargar un archivo CSV local en una tabla de BigQuery nueva. Si deseas cargar un archivo local con otro formato, usa la clase de opciones de actualización para el formato adecuado desde la clase de base JobCreationOptions en vez deUploadCsvOptions
.
Go
Antes de probar este ejemplo, sigue las instrucciones de configuración para Go que se encuentran en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Si deseas obtener más información, consulta la documentación de referencia de la API de Go de BigQuery.
El siguiente código demuestra cómo cargar un archivo CSV local en una tabla de BigQuery nueva. Para cargar un archivo local con otro formato, configura la propiedad DataFormat deNewReaderSource
con el formato adecuado.
Java
Antes de probar este ejemplo, sigue las instrucciones de configuración para Java que se encuentran en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para Java.
El siguiente código demuestra cómo cargar un archivo CSV local en una tabla de BigQuery nueva. Para cargar un archivo local con otro formato, configura la propiedad FormatOptions con el formato adecuado.
Node.js
Antes de probar este ejemplo, sigue las instrucciones de configuración para Node.js que se encuentran en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Para obtener más información, consulta la Documentación de referencia de la API de Node.js de BigQuery.
El siguiente código demuestra cómo cargar un archivo CSV local en una tabla de BigQuery nueva. Para cargar un archivo local con otro formato, configura el parámetrometadata
de la función subir con el formato adecuado.
PHP
Antes de probar este ejemplo, sigue las instrucciones de configuración para PHP incluidas en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Si deseas obtener más información, consulta la documentación de referencia de la API de PHP de BigQuery.
El siguiente código demuestra cómo cargar un archivo CSV local en una tabla de BigQuery nueva. Para cargar un archivo local con otro formato, configura la propiedad sourceFormat con el formato adecuado.
Python
Antes de probar esta muestra, sigue las instrucciones de configuración para Python incluidas en la Guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Si deseas obtener más información, consulta la documentación de referencia de la API de Python de BigQuery.
El siguiente código demuestra cómo cargar un archivo CSV local en una tabla de BigQuery nueva. Para cargar un archivo local con otro formato, configura la propiedad LoadJobConfig.source_format con el formato adecuado.
Ruby
Antes de probar este ejemplo, sigue las instrucciones de configuración para Ruby incluidas en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. A fin de obtener más información, consulta la documentación de referencia de la API de BigQuery para Ruby.
El siguiente código demuestra cómo cargar un archivo CSV local en una tabla de BigQuery nueva. Para cargar un archivo local con otro formato, configura el parámetroformat
del método Table#load_job con el formato adecuado.
Limitaciones
La carga de datos desde una fuente de datos local está sujeta a las siguientes limitaciones:
- Los comodines y las listas separadas por comas no son compatibles cuando cargas archivos desde una fuente de datos local. Los archivos se deben cargar por separado.
- Cuando utilizas la IU web clásica de BigQuery, los archivos que se cargan desde una fuente de datos local deben pesar 10 MB o menos, y contener menos de 16,000 filas.
Carga datos comprimidos y sin comprimir
Se prefiere el formato binario Avro para cargar datos comprimidos y sin comprimir. Los datos Avro se cargan más rápido, porque pueden leerse en paralelo, incluso cuando los bloques de datos están comprimidos. Los archivos Avro comprimidos no son compatibles, pero los bloques de datos comprimidos sí lo son. BigQuery admite los códecs DEFLATE y Snappy para bloques de datos comprimidos en archivos Avro.
El formato binario Parquet también es una buena opción, ya que brinda una codificación eficiente y por columna que suele generar un mejor índice de compresión y archivos más pequeños. Además, los archivos Parquet usan técnicas de compresión que permiten cargar archivos en paralelo. Los archivos comprimidos Parquet no son compatibles, pero los bloques de datos comprimidos sí lo son. BigQuery es compatible con los códecs Snappy, GZip y LZO_1X para bloques de datos comprimidos en archivos Parquet.
El formato binario ORC ofrece beneficios similares a los del formato Parquet. Los datos en los archivos ORC se cargan rápido, ya que las franjas de datos se pueden leer en paralelo. Las filas en cada franja de datos se cargan de manera secuencial. A fin de optimizar el tiempo de carga, usa franjas de datos con un tamaño aproximado de 256 MB o menos. Los archivos ORC comprimidos no son compatibles, pero las franjas y pies de página de archivos comprimidos sí lo son. BigQuery es compatible con la compresión Zlib, Snappy, LZO y LZ4 para franjas y pies de página de archivos ORC.
Para otros formatos de datos, como CSV y JSON, BigQuery puede cargar archivos sin comprimir mucho más rápido que archivos comprimidos, ya que los archivos sin comprimir se pueden leer en paralelo. Debido a que los archivos sin comprimir son más grandes, su uso puede llevar a limitaciones en el ancho de banda y a mayores costos de Cloud Storage para los datos almacenados en Cloud Storage antes de su carga en BigQuery. Ten en cuenta que el orden de las líneas no está garantizado para archivos comprimidos o sin comprimir. Es importante considerar estas cuestiones según tu caso práctico.
En general, si el ancho de banda es limitado, debes comprimir tus archivos CSV y JSON mediante gzip antes de subirlos a Cloud Storage. En la actualidad, cuando se cargan datos en BigQuery, gzip es el único tipo de compresión de archivos compatible con archivos CSV y JSON. Si la velocidad de carga es importante en tu app y tienes mucho ancho de banda para cargar tus datos, no comprimas los archivos.
Anexa o reemplaza una tabla
Puedes cargar datos adicionales en una tabla desde archivos de origen o cuando adjuntas resultados de consultas. Si el esquema de los datos no coincide con el esquema de la tabla o partición de destino, puedes actualizar el esquema cuando agregues datos o reemplaces los existentes.
Si actualizas el esquema cuando agregas datos, BigQuery te permitirá realizar las siguientes acciones:
- Agregar campos nuevos
- Cambiar los campos
REQUIRED
porNULLABLE
Si reemplazas una tabla, el esquema siempre se reemplaza. Las actualizaciones de esquema no están restringidas cuando reemplazas una tabla.
En Cloud Console, usa la opción de Preferencia de escritura para especificar qué acción se debe tomar cuando cargues datos desde un archivo de origen o desde un resultado de consulta. La herramienta de línea de comandos de bq
y la API incluyen las siguientes opciones:
Opción de Console | Marca de la herramienta de bq |
Propiedad de la API de BigQuery | Descripción |
---|---|---|---|
Escribir si está vacía | Ninguna | WRITE_EMPTY | Solo escribe los datos si la tabla está vacía. |
Agregar a la tabla | --noreplace o --replace=false ; si --replace no está especificado, la opción predeterminada es agregar |
WRITE_APPEND | (Predeterminado) Adjunta los datos al final de la tabla. |
Reemplazar tabla | --replace o --replace=true |
WRITE_TRUNCATE | Borra todos los datos existentes de una tabla antes de escribir los datos nuevos. |
Política de cuotas
Si deseas obtener información sobre la política de cuotas para cargar datos por lotes, consulta Trabajos de carga en la página Cuotas y límites.
Precios
En este momento, se aplican cargos por cargar datos en BigQuery. Para obtener más información, consulta la página de precios.