Explora la herramienta de línea de comandos de bq
La herramienta de línea de comandos de bq es una herramienta de línea de comandos para BigQuery basada en Python. Esta página contiene información general sobre el uso de la herramienta de línea de comandos de bq.
Para obtener una referencia completa de todos los comandos y marcas de bq
, consulta la referencia de la herramienta de línea de comandos de bq.
Antes de comenzar
Antes de usar la herramienta de línea de comandos de bq, debes usar la consola de Google Cloud para crear o seleccionar un proyecto.
- Accede a tu cuenta de Google Cloud. Si eres nuevo en Google Cloud, crea una cuenta para evaluar el rendimiento de nuestros productos en situaciones reales. Los clientes nuevos también obtienen $300 en créditos gratuitos para ejecutar, probar y, además, implementar cargas de trabajo.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
- BigQuery se habilita automáticamente en proyectos nuevos.
Para activar BigQuery en un proyecto preexistente, ve a
Enable the BigQuery API.
. - Opcional: Habilita la facturación para el proyecto. Si no deseas habilitar la facturación ni proporcionar una tarjeta de crédito, los pasos que se indican en este documento seguirán funcionando. BigQuery proporciona una zona de pruebas para realizar los pasos. Para obtener más información, consulta Habilita la zona de pruebas de BigQuery.
Ingresa comandos de bq
en Cloud Shell
Puedes ingresar los comandos de la herramienta de línea de comandos de Cloud Shell , ya sea desde la consola de Google Cloud o desde Google Cloud CLI.
Para usar la herramienta de línea de comandos de bq desde la consola de Google Cloud, activa Cloud Shell:
Para usar la herramienta de línea de comandos de CLI de gcloud instala y configura la CLI de gcloud.
Coloca marcas y argumentos
La herramienta de línea de comandos de bq admite dos tipos de marcas:
- Las marcas globales se pueden usar en todos los comandos.
- Las marcas específicas de comando se aplican a un comando específico.
Para obtener una lista de las marcas globales y específicas de comando disponibles, consulta la referencia de la herramienta de línea de comandos de bq.
Coloca las marcas globales antes del comando bq
y, luego, incluye las marcas específicas del comando. Puedes incluir varias marcas globales o específicas del comando. Por ejemplo:
bq --location=us mk --reservation --project_id=project reservation_name
Puedes especificar argumentos de comando de las siguientes maneras:
--FLAG ARGUMENT
(como se muestra en los ejemplos anteriores)--FLAG=ARGUMENT
--FLAG='ARGUMENT'
--FLAG="ARGUMENT"
--FLAG 'ARGUMENT'
--FLAG "ARGUMENT"
Reemplaza lo siguiente:
FLAG
: una marca global o específica de comandoARGUMENT
: el argumento de la marca
Algunos comandos requieren el uso de comillas simples o dobles alrededor de los argumentos. Esto suele ser verdadero cuando el argumento contiene espacios, comas o algunos otros caracteres especiales. Por ejemplo:
bq query --nouse_legacy_sql \ 'SELECT COUNT(*) FROM `bigquery-public-data`.samples.shakespeare'
Las marcas con valores booleanos se pueden especificar sin un argumento. Si especificas true
o false
, debes usar el formato FLAG=ARGUMENT
.
Por ejemplo, en este comando se especifica “false” para la marca booleana --use_legacy_sql
porque se coloca no
al frente de la marca:
bq query --nouse_legacy_sql \ 'SELECT COUNT(*) FROM `bigquery-public-data`.samples.shakespeare'
De manera alternativa, para especificar false
como el argumento de la marca, puedes ingresar lo siguiente:
bq query --use_legacy_sql=false \ 'SELECT COUNT(*) FROM `bigquery-public-data`.samples.shakespeare'
Ejecuta consultas desde la herramienta de línea de comandos de bq
Para tomar una consulta que desarrollaste en la consola de Google Cloud y ejecutarla desde la herramienta de línea de comandos de bq, haz lo siguiente:
Incluye la consulta en un comando
bq query
de la siguiente manera:bq query --use_legacy_sql=false 'QUERY'
. ReemplazaQUERY
por la consulta.Da formato a la cadena de consulta.
Si necesitas usar literales de cadena adicionales dentro de la consulta, debes seguir las reglas de uso comillas para la shell que usas, como Bash o PowerShell.
En el siguiente ejemplo, se muestra un enfoque típico en Bash, que consiste en usar comillas dobles para denotar los literales de cadena en la consulta y, luego, encerrar la consulta entre comillas simples:
'SELECT * FROM mydataset.mytable WHERE column1 = "value";'
Si copias la consulta desde otra ubicación, también debes quitar cualquier comentario en la consulta.
Por ejemplo, transforma la siguiente consulta de la consola de Google Cloud:
-- count Shakespeare's use of the string "raisin" SELECT word, SUM(word_count) AS count FROM `bigquery-public-data`.samples.shakespeare WHERE word LIKE '%raisin%' GROUP BY word
en una consulta de la herramienta de línea de comandos de bq de la siguiente manera:
bq query --use_legacy_sql=false \ 'SELECT word, SUM(word_count) AS count FROM `bigquery-public-data`.samples.shakespeare WHERE word LIKE "%raisin%" GROUP BY word'
Para obtener más información, consulta Ejecuta trabajos de consulta interactivos y por lotes.
Obtén ayuda
Para obtener ayuda con la herramienta de línea de comandos de bq, puedes ingresar los siguientes comandos:
- Para la versión instalada de la herramienta de línea de comandos de bq, ingresa
bq version
. - Para obtener una lista completa de comandos, ingresa
bq help
. - Para obtener una lista de marcas globales, ingresa
bq --help
. - Para obtener ayuda sobre un comando específico, ingresa
bq help COMMAND
. - Para obtener ayuda sobre un comando específico más una lista de marcas globales, ingresa
bq COMMAND --help
.
Reemplaza COMMAND
por el comando con el que necesitas ayuda.
Configura los valores predeterminados para marcas de línea de comandos
Puedes configurar valores predeterminados para las marcas de línea de comandos si los incluyes en el archivo de configuración de la herramienta de línea de comandos de .bigqueryrc
. Antes de configurar tus opciones predeterminadas, debes crear un archivo .bigqueryrc
. Puedes usar tu editor de texto preferido para crear el archivo. Luego de crear el archivo .bigqueryrc
, puedes especificar la ruta al archivo con la marca global --bigqueryrc
.
Si no se especifica la marca --bigqueryrc
, se usa la variable de entorno BIGQUERYRC
. Si no se especifica la variable, se usa la ruta de acceso ~/.bigqueryrc
. La ruta predeterminada es $HOME/.bigqueryrc
.
Agrega marcas a .bigqueryrc
A fin de agregar valores predeterminados para las marcas de línea de comandos a .bigqueryrc
, haz lo siguiente:
- Coloca las marcas globales en la parte superior del archivo sin un encabezado.
- Para las marcas específicas de comando, ingresa el nombre del comando (entre paréntesis) y agrega las marcas específicas de comando (una por línea) después del nombre del comando.
Por ejemplo:
--apilog=stdout --format=prettyjson --location=US [query] --use_legacy_sql=false --max_rows=100 --maximum_bytes_billed=10000000 [load] --destination_kms_key=projects/myproject/locations/mylocation/keyRings/myRing/cryptoKeys/myKey
En el ejemplo anterior, se configuran valores predeterminados para las siguientes marcas:
- La marca global
--apilog
se configura comostdout
para imprimir el resultado de depuración en la consola de Google Cloud. - La marca global
--format
se configura comoprettyjson
para mostrar el resultado del comando en un formato JSON legible. - La marca global
--location
se configuró en la ubicación multirregiónUS
. La marca
--use_legacy_sql
específica del comandoquery
se configura comofalse
para que GoogleSQL sea la sintaxis de consulta predeterminada.La marca
--max_rows
específica del comandoquery
se configura como100
para controlar la cantidad de filas en el resultado de la consulta.La marca
--maximum_bytes_billed
específica del comandoquery
se configura en 10,000,000 bytes (10 MB) para que fallen las consultas que leen más de 10 MB de datos.La marca
--destination_kms_key
específica del comandoload
se configura comoprojects/myproject/locations/mylocation/keyRings/myRing/cryptoKeys/myKey
.
Ejecuta la herramienta de línea de comandos de bq en un shell interactivo
Puedes ejecutar la herramienta de línea de comandos de bq en una shell interactiva en la que no necesites insertar prefijos para los comandos con bq
. Para iniciar el modo interactivo, ingresa bq shell
.
Después de iniciar la shell, el indicador cambia al ID de tu proyecto predeterminado.
Para salir del modo interactivo, ingresa exit
.
Ejecuta la herramienta de línea de comandos de bq en una secuencia de comandos
Puedes ejecutar la herramienta de línea de comandos de bq en un script, tal como lo harías con un comando de Google Cloud CLI. El siguiente es un ejemplo de los comandos de gcloud
y bq
en una secuencia de comandos de bash:
#!/bin/bash
gcloud config set project myProject
bq query --use_legacy_sql=false --destination_table=myDataset.myTable \
'SELECT
word,
SUM(word_count) AS count
FROM
`bigquery-public-data`.samples.shakespeare
WHERE
word LIKE "%raisin%"
GROUP BY
word'
Ejecuta comandos de bq
desde una cuenta de servicio
Puedes usar una cuenta de servicio para realizar llamadas autorizadas a la API o ejecutar trabajos de consulta en tu nombre. Para usar una cuenta de servicio en la herramienta de línea de comandos de bq, autoriza el acceso a Google Cloud desde la cuenta de servicio. Para obtener más información, consulta gcloud auth activate-service-account.
Para comenzar a ejecutar comandos de bq
mediante el uso de la identidad de la cuenta de servicio, ejecuta el siguiente comando:
gcloud config set auth/impersonate_service_account SERVICE_ACCOUNT_NAME
Reemplaza SERVICE_ACCOUNT_NAME
por el nombre de tu cuenta de servicio.
Los comandos de bq
que ejecutas ahora usan las credenciales de la cuenta de servicio.
Para dejar de ejecutar los comandos de bq
desde una cuenta de servicio, ejecuta el siguiente comando:
gcloud config unset auth/impersonate_service_account
Ejemplos
Puedes encontrar ejemplos de línea de comandos en la sección de guías prácticas de la documentación de BigQuery. En esta sección, se enumeran los vínculos a las tareas comunes de la línea de comandos, como crear, obtener, enumerar, borrar y modificar recursos de BigQuery.
Crea recursos
A fin de obtener información sobre el uso de la herramienta de línea de comandos de bq para crear recursos, consulta los siguientes vínculos:
- Crea un conjunto de datos
- Crea una tabla vacía con una definición de esquema
- Crea una tabla a partir de un resultado de consulta
- Crea una tabla particionada por tiempo de transferencia
- Crea vistas
Para ver ejemplos de cómo crear una tabla con un archivo de datos, consulta Carga datos.
Obtén información sobre los recursos
A fin de aprender más sobre cómo usar la herramienta de línea de comandos de bq para obtener información sobre los recursos, consulta los siguientes vínculos:
- Obtén información sobre los conjuntos de datos
- Obtén información sobre las tablas
- Obtén información sobre las vistas
Haz una lista de recursos
Si deseas obtener información sobre el uso de la herramienta de línea de comandos de bq para actualizar recursos, consulta los siguientes vínculos:
Enumera trabajos
Si deseas obtener información sobre el uso de la herramienta de línea de comandos de bq para mostrar listas de trabajos, consulta los siguientes vínculos:
Actualiza recursos
Si deseas obtener información sobre el uso de la herramienta de línea de comandos de bq para actualizar recursos, consulta los siguientes vínculos:
- Actualiza las propiedades del conjunto de datos
- Actualiza las propiedades de las tablas
- Actualiza propiedades de la vista
Cargando datos
Si deseas obtener información sobre el uso de la herramienta de línea de comandos de bq para cargar datos, consulta los siguientes vínculos:
- Carga datos de Avro desde Cloud Storage
- Carga datos de JSON desde Cloud Storage
- Carga datos de CSV desde Cloud Storage
- Carga datos desde un archivo local
Consulta datos
A fin de obtener información sobre el uso de la herramienta de línea de comandos de bq para exportar datos, consulta los siguientes vínculos:
- Cómo ejecutar consultas interactivas
- Escribe resultados de consultas
- Ejecuta consultas con parámetros
Usa fuentes de datos externas
A fin de obtener información sobre el uso de la herramienta de línea de comandos de bq para consultar datos en fuentes de datos externas, consulta los siguientes vínculos:
- Crea una definición de tabla con un archivo de esquema JSON
- Consulta datos de Cloud Bigtable con tablas externas permanentes
- Consulta datos de Cloud Storage con tablas externas permanentes
- Consulta datos de Google Drive con tablas externas permanentes
Exportar datos
A fin de obtener información sobre el uso de la herramienta de línea de comandos de bq para exportar datos, consulta los siguientes vínculos:
Usar el servicio de BigQuery Data Transfer
Si deseas obtener información sobre el uso de la herramienta de línea de comandos de bq con el Servicio de transferencia de datos de BigQuery, consulta los siguientes vínculos:
- Configura una transferencia de Amazon S3
- Configura una transferencia de Campaign Manager
- Configura una transferencia de Cloud Storage
- Configura una transferencia de Google Ad Manager
- Configura una transferencia de Google Ads
- Configura una transferencia de Google Merchant Center (Beta).
- Configura una transferencia de Google Play
- Configura una transferencia de Search Ads 360 (beta)
- Configura una transferencia de canal de YouTube
- Configura una transferencia del propietario del contenido de YouTube
- Migra datos desde Amazon Redshift
- Migra datos desde Teradata
- Obtén información sobre las opciones de configuración de transferencias.
- Lista de opciones de configuración de transferencias
- Consulta el historial de ejecución
- Consulta detalles de ejecución de transferencia y mensajes de registro
- Actualiza una transferencia
Soluciona problemas de la herramienta de línea de comandos de bq
En esta sección, se muestra cómo resolver problemas con la herramienta de línea de comandos de bq.
Mantén actualizada la CLI de gcloud
Si usas la herramienta de línea de comandos de bq desde Google Cloud CLI, asegúrate de tener la funcionalidad y las correcciones más recientes para la herramienta de línea de comandos de bq. Para ello, mantén actualizada tu instalación de la CLI de gcloud. Para verificar si ejecutas la versión más reciente de la CLI de gcloud, ingresa el siguiente comando en Cloud Shell:
gcloud components list
En las dos primeras líneas del resultado, se muestra el número de versión de la instalación actual de la CLI de gcloud y el número de la versión más reciente de la CLI de gcloud. Si descubres que la versión está desactualizada, puedes actualizar la instalación de la CLI de gcloud a la versión más reciente si ingresas el siguiente comando en Cloud Shell:
gcloud components update
Depuración
Puedes ingresar los siguientes comandos para depurar la herramienta de línea de comandos de bq:
Consulta las solicitudes enviadas y recibidas. Agrega la marca
--apilog=PATH_TO_FILE
para guardar un registro de operaciones en un archivo local. ReemplazaPATH_TO_FILE
por la ruta de acceso en la que deseas guardar el registro. La herramienta de línea de comandos de bq funciona mediante llamadas a la API basadas en REST estándar, que pueden ser útiles de ver. También es útil adjuntar este registro cuando informas sobre problemas. El uso de-
ostdout
en lugar de una ruta de acceso imprime el registro en la consola de Google Cloud. La configuración de--apilog
comostderr
da como resultado el archivo de error estándar. Para registrar más solicitudes, usa la marca--httplib2_debuglevel=LOG_LEVEL
. UnLOG_LEVEL
superior registra más información sobre las solicitudes HTTP.Soluciona errores. Ingresa la marca
--format=prettyjson
cuando obtengas el estado de un trabajo o cuando veas información detallada sobre recursos, como tablas y conjuntos de datos. El uso de esta marca genera la respuesta en formato JSON, incluida la propiedadreason
. Puedes usar la propiedadreason
a fin de buscar los pasos para solucionar problemas. Para obtener más información acerca de cualquier error durante la ejecución, usa la marca--debug_mode
.