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.

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

    3.

  3. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

    4.
  4. BigQuery se habilita automáticamente en proyectos nuevos. Para activar BigQuery en un proyecto preexistente, ve a

    Enable the BigQuery API.

    Enable the API

    .
  5. 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.

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 comando
  • ARGUMENT: 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:

  1. Incluye la consulta en un comando bq query de la siguiente manera: bq query --use_legacy_sql=false 'QUERY'. Reemplaza QUERY por la consulta.

  2. 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 como stdout para imprimir el resultado de depuración en la consola de Google Cloud.
  • La marca global --format se configura como prettyjson para mostrar el resultado del comando en un formato JSON legible.
  • La marca global --location se configuró en la ubicación multirregión US.

  • La marca --use_legacy_sql específica del comando query se configura como false para que GoogleSQL sea la sintaxis de consulta predeterminada.

  • La marca --max_rows específica del comando query se configura como 100 para controlar la cantidad de filas en el resultado de la consulta.

  • La marca --maximum_bytes_billed específica del comando query 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 comando load se configura como projects/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:

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:

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:

Carga 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:

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:

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:

Exporta 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:

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. Reemplaza PATH_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 - o stdout en lugar de una ruta de acceso imprime el registro en la consola de Google Cloud. La configuración de --apilog como stderr da como resultado el archivo de error estándar. Para registrar más solicitudes, usa la marca --httplib2_debuglevel=LOG_LEVEL. Un LOG_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 propiedad reason. Puedes usar la propiedad reason 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.