En este documento, se explica cómo escribir o guardar resultados de consultas.
Tablas temporales y permanentes
BigQuery guarda todos los resultados de las consultas en una tabla, que puede ser permanente o temporal.
BigQuery usa tablas temporales para almacenar en caché los resultados de las consultas que no se escriben en una tabla permanente. Las tablas se crean en un conjunto de datos especial y se les asigna un nombre al azar. También puedes crear tablas temporales para tu propio uso. Para obtener más información, consulta Tablas temporales.
Una vez que finaliza una consulta, la tabla temporal existe por hasta 24 horas. Para ver los datos y la estructura de la tabla, ve a Consola de BigQuery, haz clic en Historial de consultas y elige la consulta que creó la tabla temporal. Luego, en la fila Tabla de destino, haz clic en Tabla temporal.
No puedes consultar ni compartir tablas temporales, y estas no son visibles con ninguno de los métodos de lista estándar o de manipulación de tablas. No se te cobrará por almacenar tablas temporales.
Las tablas permanentes pueden ser tablas nuevas o existentes en cualquier conjunto de datos al que tengas acceso. Si escribes los resultados de las consultas en una tabla nueva, se te cobrará por almacenar los datos. Cuando escribes los resultados de las consultas en una tabla permanente, las tablas que consultas deben estar en la misma ubicación que el conjunto de datos que contiene la tabla de destino.
Permisos necesarios
Como mínimo, para escribir los resultados de las consultas en una tabla, debes tener los siguientes permisos:
bigquery.tables.create
para crear una tabla nuevabigquery.tables.updateData
para escribir datos en una tabla nueva, reemplazar una tabla o agregar datos a una tablabigquery.jobs.create
para ejecutar un trabajo de consulta
Es posible que se requieran permisos adicionales como bigquery.tables.getData
para acceder a los datos que consultas.
En las siguientes funciones predefinidas de IAM, se 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.
Con el acceso bigquery.dataOwner
, el usuario puede crear y actualizar tablas en el conjunto de datos.
Para obtener más información sobre las funciones y los permisos de IAM en BigQuery, consulta Funciones y permisos predefinidos.
Escribe los resultados de las consultas en una tabla permanente
Cuando escribes los resultados de las consultas en una tabla permanente, puedes crear una tabla nueva, agregar los resultados en una tabla existente o reemplazar una tabla existente. Puedes escribir los resultados de las consultas en una tabla permanente de las siguientes maneras:
- Usa Cloud Console.
- Usa el comando
bq
de la herramienta de línea de comandosbq query
- Llama al método
jobs.insert
de la API y la configuración de un trabajoquery
. - Usa las bibliotecas cliente.
Escribe resultados de consultas
Usa el siguiente procedimiento para escribir los resultados de las consultas en una tabla permanente. Para ayudar a controlar los costos, puedes obtener una vista previa de los datos antes de ejecutar la consulta.
Console
Abre la página de BigQuery en Cloud Console.
En el panel Explorador, expande tu proyecto y selecciona un conjunto de datos.
Si el editor de consultas está oculto, haz clic en Mostrar editor, en la parte superior derecha de la ventana.
Ingresa una consulta de SQL válida en el área de texto del Editor de consultas.
Haz clic en Más (More) y, luego, selecciona Opciones de consulta (Query Options).
Marca la casilla Establecer una tabla de destino para los resultados de la consulta (Set a destination table for query results).
En la sección Destino (Destination), selecciona el Nombre del proyecto y el Nombre del conjunto de datos adecuados en los que se creará la tabla, y elige un Nombre de tabla.
En la sección Preferencia de escritura para la tabla de destino, elige una de las siguientes opciones:
- Escribir si está vacía: escribe los resultados de las consultas en la tabla solo si está vacía.
- Agregar a la tabla: Agrega los resultados de las consultas a una tabla existente.
- Reemplazar la tabla: reemplaza una tabla existente que tiene el mismo nombre con los resultados de las consultas.
Opcional: En Ubicación de procesamiento, haz clic en Selección automática y elige tu ubicación.
Haz clic en Ejecutar consulta. Esta acción crea un trabajo de consulta que escribe los resultados de las consultas en la tabla que especificaste.
Como alternativa, si te olvidas de especificar una tabla de destino antes de ejecutar la consulta, puedes hacer clic en el botón Guardar los resultados debajo del editor para copiar la tabla de resultados almacenados en caché en una tabla permanente.
SQL
Las declaraciones del lenguaje de definición de datos (DDL) te permiten crear y modificar tablas con la sintaxis de consultas de SQL estándar.
Para obtener más información, consulta la sección Instrucción CREATE TABLE
y el ejemplo de CREATE TABLE
: Crear una tabla nueva a partir de una tabla existente.
bq
Ingresa el comando bq query
y especifica la marca --destination_table
para crear una tabla permanente basada en los resultados de las consultas. Especifica la marca use_legacy_sql=false
para usar la sintaxis SQL estándar. Para escribir los resultados de las consultas en una tabla que no se encuentra en tu proyecto predeterminado, agrega el ID del proyecto al nombre del conjunto de datos con el formato siguiente: project_id:dataset
.
Opcional: Proporciona la marca --location
y configura el valor en tu ubicación.
Para controlar la disposición de escritura de una tabla de destino existente, especifica una de las marcas opcionales siguientes:
--append_table
: Si existe la tabla de destino, los resultados de las consultas se agregan a esta tabla.--replace
: Si existe la tabla de destino, se reemplaza por los resultados de las consultas.
bq --location=location query \ --destination_table project_id:dataset.table \ --use_legacy_sql=false 'query'
Reemplaza lo siguiente:
location
es el nombre de la ubicación que se usa para procesar la consulta. La marca--location
es opcional. Por ejemplo, si usas BigQuery en la región de Tokio, puedes configurar el valor de la marca comoasia-northeast1
. Puedes configurar un valor predeterminado para la ubicación mediante el archivo.bigqueryrc
.project_id
es el ID del proyecto.dataset
es el nombre del conjunto de datos que contiene la tabla en la que escribes los resultados de la consulta.table
es el nombre de la tabla en la que escribes los resultados de las consultas.query
es una consulta en la sintaxis de SQL estándar.
Si no se especifica una marca de disposición de escritura, el comportamiento predeterminado es escribir los resultados en la tabla solo si está vacía. Si la tabla existe y no está vacía, se muestra el error siguiente: Error de BigQuery en la operación de consulta: error durante el procesamiento del trabajo project_id:bqjob_123abc456789_00000e1234f_1': Already
Exists: Table project_id:dataset.table
.
Ejemplos:
Ingresa el comando siguiente para escribir los resultados de las consultas en una tabla de destino llamada mytable
en mydataset
. El conjunto de datos se encuentra en tu proyecto predeterminado.
Debido a que no se especifica ninguna marca de disposición de escritura en el comando, la tabla debe ser nueva o estar vacía. De lo contrario, se muestra un error Already exists
. Con la consulta, se recuperan datos del conjunto de datos públicos Datos de nombres de EE.UU.
bq query \ --destination_table mydataset.mytable \ --use_legacy_sql=false \ 'SELECT name, number FROM `bigquery-public-data`.usa_names.usa_1910_current WHERE gender = "M" ORDER BY number DESC'
Ingresa el comando siguiente para usar los resultados de las consultas a fin de reemplazar una tabla de destino llamada mytable
en mydataset
. El conjunto de datos se encuentra en tu proyecto predeterminado. En el comando, se usa la marca --replace
para reemplazar la tabla de destino.
bq query \ --destination_table mydataset.mytable \ --replace \ --use_legacy_sql=false \ 'SELECT name, number FROM `bigquery-public-data`.usa_names.usa_1910_current WHERE gender = "M" ORDER BY number DESC'
Ingresa el comando siguiente para agregar los resultados de las consultas a una tabla de destino llamada mytable
en mydataset
. El conjunto de datos está en my-other-project
, no en tu proyecto predeterminado. En el comando, se usa la marca --append_table
para agregar los resultados de las consultas a la tabla de destino.
bq query \ --append_table \ --use_legacy_sql=false \ --destination_table my-other-project:mydataset.mytable \ 'SELECT name, number FROM `bigquery-public-data`.usa_names.usa_1910_current WHERE gender = "M" ORDER BY number DESC'
El resultado de cada uno de estos ejemplos se verá de la manera siguiente. Para facilitar la lectura, algunos resultados se truncaron.
Waiting on bqjob_r123abc456_000001234567_1 ... (2s) Current status: DONE +---------+--------+ | name | number | +---------+--------+ | Robert | 10021 | | John | 9636 | | Robert | 9297 | | ... | +---------+--------+
API
Si deseas guardar los resultados de las consultas en una tabla permanente, realiza una llamada al método jobs.insert
, configura un trabajo query
y, por último, incluye un valor para la propiedad destinationTable
. Para controlar la disposición de escritura de una tabla de destino existente, configura la propiedad writeDisposition
.
Si deseas controlar la ubicación de procesamiento para el trabajo de consulta, especifica la propiedad location
en la sección jobReference
del recurso de trabajo.
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.
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.
Para guardar los resultados de las consultas en una tabla permanente, configura la tabla de destino con el valor TableId que desees en una QueryJobConfiguration.
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.
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.
Para guardar los resultados de las consultas en una tabla permanente, crea una QueryJobConfig y configura el destino con el valor TableReference que desees. Pasa la configuración del trabajo al método de consulta.Cómo escribir resultados de consultas grandes
Por lo general, las consultas tienen un tamaño de respuesta máximo. Si planeas ejecutar una consulta que podría mostrar resultados más grandes, puedes realizar una de las siguientes acciones:
- En SQL estándar, especifica una tabla de destino para los resultados de las consultas.
- En SQL heredado, especifica una tabla de destino y configura la opción
allowLargeResults
.
Cuando especificas una tabla de destino para los resultados de las consultas grandes, se te cobra por almacenar los datos.
Limitaciones
En SQL heredado, la escritura de resultados grandes está sujeta a las siguientes limitaciones:
- Debes especificar una tabla de destino.
- No puedes especificar una cláusula de nivel superior
ORDER BY
,TOP
oLIMIT
. Si lo haces, se anula el beneficio de usarallowLargeResults
porque el resultado de la consulta ya no se puede procesar en paralelo. - Con las funciones analíticas, se pueden mostrar los resultados de las consultas grandes solo si se usan junto con una cláusula
PARTITION BY
.
Escribe resultados grandes con SQL heredado
Para escribir conjuntos de resultados grandes mediante SQL heredado, sigue estos pasos:
Console
En Cloud Console, abre la página de BigQuery.
Haz clic en Redactar consulta nueva.
Ingresa una consulta de SQL válida en el área de texto del Editor de consultas. Usa el prefijo
#legacySQL
o asegúrate de que la opción Usa SQL heredado esté marcada en la configuración de la consulta.Haz clic en More (Más) y selecciona Query settings (Configuración de consulta).
En Destination (Destino), marca Set a destination table for query results (Establecer una tabla de destino para los resultados de la consulta).
En Nombre del proyecto, elige el proyecto en el que se creará la tabla de destino.
En Nombre del conjunto de datos, elige el conjunto de datos en el que se almacenará la tabla.
En el campo Nombre de la tabla, ingresa un nombre de tabla.
Si escribes un conjunto de resultados grandes en una tabla existente, puedes usar las opciones Preferencia de escritura para la tabla de destino (Destination table write preference) a fin de controlar la disposición de escritura de la tabla de destino:
- Escribir si está vacía: Se escriben los resultados de las consultas en la tabla solo si está vacía.
- Agregar a la tabla: Agrega los resultados de las consultas a una tabla existente.
- Reemplazar la tabla: Se reemplaza una tabla existente con el mismo nombre mediante los resultados de las consultas.
En Results size (Tamaño de los resultados), marca Allow Large Results (no size limit) (Permitir resultados grandes [sin límite de tamaño]).
Opcional: En Processing Location (Ubicación de procesamiento), haz clic en Auto-select (Selección automática) y elige la ubicación de tus datos.
Haz clic en Guardar para actualizar la configuración de la consulta.
Haz clic en Ejecutar. Esta acción crea un trabajo de consulta que escribe el conjunto de resultados grandes en la tabla que especificaste.
bq
Usa la marca --allow_large_results
con la marca --destination_table
para crear una tabla de destino que contenga el conjunto de resultados grandes. Debido a que la opción --
allow_large_results
solo se aplica al SQL heredado, también debes especificar la marca --use_legacy_sql=true
. Para escribir los resultados de las consultas en una tabla que no se encuentra en tu proyecto predeterminado, agrega el ID del proyecto al nombre del conjunto de datos con el formato siguiente: PROJECT_ID:DATASET
.
Proporciona la marca --location
y configura el valor en tu ubicación.
Para controlar la disposición de escritura de una tabla de destino existente, especifica una de las marcas opcionales siguientes:
--append_table
: Si existe la tabla de destino, los resultados de las consultas se agregan a esta tabla.--replace
: Si existe la tabla de destino, se reemplaza por los resultados de las consultas.
bq --location=location query \ --destination_table PROJECT_ID:DATASET.TABLE \ --use_legacy_sql=true \ --allow_large_results "QUERY"
Reemplaza lo siguiente:
LOCATION
es el nombre de la ubicación que se usa para procesar la consulta. La marca--location
es opcional. Por ejemplo, si usas BigQuery en la región de Tokio, puedes configurar el valor de la marca comoasia-northeast1
. Puedes establecer un valor predeterminado para la ubicación con el archivo.bigqueryrc
.PROJECT_ID
es el ID del proyecto.DATASET
es el nombre del conjunto de datos que contiene la tabla en la que escribes los resultados de la consulta.TABLE
es el nombre de la tabla en la que escribes los resultados de las consultas.QUERY
es una consulta en la sintaxis de SQL heredado.
Ejemplos:
Ingresa el comando siguiente para escribir los resultados de las consultas grandes en una tabla de destino llamada mytable
en mydataset
. El conjunto de datos se encuentra en tu proyecto predeterminado. Debido a que no se especifica ninguna marca de disposición de escritura en el comando, la tabla debe ser nueva o estar vacía. De lo contrario, se muestra un error Already exists
. Con la consulta, se recuperan datos del conjunto de datos públicos Datos de nombres de EE.UU.
Esta consulta se usa solo como ejemplo. El conjunto de resultados que se muestra no excede el tamaño de respuesta máximo.
bq query \
--destination_table mydataset.mytable \
--use_legacy_sql=true \
--allow_large_results \
"SELECT
name,
number
FROM
[bigquery-public-data:usa_names.usa_1910_current]
WHERE
gender = 'M'
ORDER BY
number DESC"
Ingresa el comando siguiente para usar los resultados de las consultas grandes a fin de reemplazar una tabla de destino llamada mytable
en mydataset
. El conjunto de datos está en myotherproject
, no en tu proyecto predeterminado. En el comando, se usa la marca --replace
para reemplazar la tabla de destino.
bq query \
--destination_table mydataset.mytable \
--replace \
--use_legacy_sql=true \
--allow_large_results \
"SELECT
name,
number
FROM
[bigquery-public-data:usa_names.usa_1910_current]
WHERE
gender = 'M'
ORDER BY
number DESC"
Ingresa el comando siguiente para agregar los resultados de las consultas grandes a una tabla de destino llamada mytable
en mydataset
. El conjunto de datos está en myotherproject
, no en tu proyecto predeterminado. En el comando, se usa la marca --append_table
para agregar los resultados de las consultas a la tabla de destino.
bq query \
--destination_table myotherproject:mydataset.mytable \
--append_table \
--use_legacy_sql=true \
--allow_large_results \
"SELECT
name,
number
FROM
[bigquery-public-data:usa_names.usa_1910_current]
WHERE
gender = 'M'
ORDER BY
number DESC"
API
Para escribir resultados grandes en una tabla de destino, realiza una llamada al método jobs.insert
y, luego, configura un trabajo query
y la propiedad allowLargeResults
como true
.
Especifica la tabla de destino con la propiedad destinationTable
. Para controlar la disposición de escritura de una tabla de destino existente, configura la propiedad writeDisposition
.
Especifica tu ubicación en la propiedad location
en la sección jobReference
del recurso de trabajo.
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.
Java
Para habilitar resultados grandes, configura Permitir resultados grandes como true
y la Tabla de destino con el valor TableId que desees en una QueryJobConfiguration.
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.
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.
Descarga y guarda los resultados de las consultas desde Cloud Console
Después de ejecutar una consulta de SQL con Cloud Console, puedes guardar los resultados en otra ubicación. Puedes usar Cloud Console para descargar los resultados de las consultas en un archivo local, Hojas de cálculo o Drive. La herramienta de línea de comandos de bq
o la API no admiten que se guarden los resultados en un archivo local, en Hojas de cálculo o en Drive.
Limitaciones
Si quieres descargar y guardar los resultados de las consultas, debes tener en cuenta las siguientes limitaciones:
- Solo puedes descargar los resultados de las consultas localmente en formato CSV o JSON delimitado por saltos de línea.
- No puedes descargar resultados de consultas que contengan datos anidados y repetidos en formato CSV.
- No puedes guardar resultados de consultas que contengan datos anidados y repetidos en Hojas de cálculo.
- Para guardar los resultados de las consultas en Drive con Cloud Console, el conjunto de resultados debe ocupar 1 GB o menos y 16,000 filas o menos. Si tus resultados son mayores que esos límites, puedes guardarlos en una tabla.
- Solo puedes guardar los resultados de las consultas en Drive en formato CSV o JSON delimitado por saltos de línea.
Descarga los resultados de las consultas en un archivo local
La herramienta de línea de comandos bq
y la API no admiten la descarga de resultados de consultas en un archivo local.
Para descargar los resultados de las consultas como un archivo CSV o JSON delimitado por saltos de línea, usa Cloud Console:
Console
En Cloud Console, abre la página de BigQuery.
Haz clic en Redactar consulta nueva.
Ingresa una consulta de SQL válida en el área de texto del Editor de consultas.
Para cambiar la ubicación de procesamiento, haz clic en Más y selecciona Configuración de consulta (opcional). En Ubicación de procesamiento, haz clic en Selección automática y elige la ubicación de tus datos.
Haz clic en Ejecutar.
Cuando se muestren los resultados, haz clic en Guardar resultados y selecciona el formato o la ubicación en los que desees guardarlos.
El archivo se descarga en la ubicación de descarga predeterminada de tu navegador.
Guarda los resultados de las consultas en Drive
La herramienta de línea de comandos de bq
o la API no admiten que los resultados de las consultas se guarden en Drive.
Para guardar los resultados de las consultas en Drive, usa Cloud Console:
Console
En Cloud Console, abre la página de BigQuery.
Ingresa una consulta de SQL válida en el área de texto del Editor de consultas.
Haz clic en Ejecutar.
Cuando se muestren los resultados, haz clic en Save Results (Guardar resultados).
Selecciona CSV (Google Drive) o JSON (Google Drive). Cuando guardas los resultados en Drive, no puedes elegir la ubicación. Los resultados siempre se guardan en la ubicación raíz “Mi unidad”.
Guardar los resultados en Drive puede llevar unos minutos. Cuando se guardan los resultados, recibes un mensaje emergente que incluye el nombre del archivo:
bq-results-[TIMESTAMP]-[RANDOM_CHARACTERS].[CSV or JSON]
.En el mensaje emergente, haz clic en Abrir (Open) para abrir el archivo o navega hasta Drive y haz clic en Mi unidad.
Guarda los resultados de las consultas en Hojas de cálculo
La herramienta de línea de comandos de bq
o la API no admiten que los resultados de las consultas se guarden en Hojas de cálculo.
Para guardar los resultados de las consultas en Hojas de cálculo, usa Cloud Console:
Console
En Cloud Console, abre la página de BigQuery.
Haz clic en Redactar consulta nueva.
Ingresa una consulta de SQL válida en el área de texto del Editor de consultas.
Para cambiar la ubicación de procesamiento, haz clic en Más y selecciona Configuración de consulta (opcional). En Ubicación de procesamiento, haz clic en Selección automática y elige la ubicación de tus datos.
Haz clic en Ejecutar.
Cuando se muestren los resultados, haz clic en Guardar los resultados y selecciona Hojas de cálculo de Google.
Si es necesario, sigue las indicaciones para acceder a tu Cuenta de Google y haz clic en Permitir a fin de permitir que se escriban los datos en tu carpeta
MY Drive
de Drive con BigQuery.Tras seguir las indicaciones, deberías recibir un correo electrónico con el asunto “BigQuery Client Tools connected to your Google Account” (Herramientas cliente de BigQuery conectadas a tu Cuenta de Google). El correo electrónico contiene información sobre los permisos que otorgaste y los pasos que tienes que seguir para quitarlos.
Cuando se guardan los resultados, debajo de los resultados de las consultas aparece un mensaje similar al siguiente en Cloud Console:
Saved to Sheets as "results-20190225-103531. Open
. Haz clic en el vínculo del mensaje para ver tus resultados en Hojas de cálculo o navega a tu carpetaMy Drive
y abre el archivo de forma manual.Cuando guardas los resultados de las consultas en Hojas de cálculo, el nombre del archivo comienza con
results-[DATE]
, en el que[DATE]
es la fecha de ese día en el formatoYYYYMMDD
.