Usa 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 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 Google Cloud Console para crear o seleccionar un proyecto.

  1. 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.
  2. En la página del selector de proyectos de Google Cloud Console, selecciona o crea un proyecto de Google Cloud.

    Ir al selector de proyectos

  3. En la página del selector de proyectos de Google Cloud Console, selecciona o crea un proyecto de Google Cloud.

    Ir al selector de proyectos

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

    Habilita la 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.

Ingresa comandos de bq en Cloud Shell

Puedes ingresar los comandos de la herramienta de línea de comandos de bq en Cloud Shell desde Google Cloud Console o desde el SDK de Cloud.

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 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 de comandos. 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: Es 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'

Como alternativa, para especificar false como el argumento de la marca, puedes ingresar el siguiente comando:

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 Google Cloud Console 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. Reemplaza las comillas simples (') en la consulta con comillas dobles (").
  3. Quita los comentarios de la consulta.

Por ejemplo, transforma la siguiente consulta de Google Cloud Console:

-- 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 bq, .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 establecen valores predeterminados para las siguientes marcas:

  • La marca global --apilog se configura como stdout para imprimir el resultado de depuración en Cloud Console.
  • La marca global --format se configura como prettyjson para mostrar el resultado del comando en un formato JSON legible.
  • La marca global --location se establece en la ubicación multirregión US.
  • La marca --use_legacy_sql específica del comando query se configura como false para que SQL estándar sea la sintaxis de consulta predeterminada.

  • La marca --max_rows específica del comando query se establece en 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 una shell interactiva

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 una secuencia de comandos, como lo harías con un comando de herramienta de línea de comandos de gcloud. 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

Para ejecutar comandos de bq con una cuenta de servicio, debes autorizar el acceso a Google Cloud desde la cuenta de servicio. Para obtener más información, consulta gcloud auth activate-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. A continuación, se proporcionan vínculos a 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 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:

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:

Cargar 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 el SDK de Cloud actualizado

Si usas la herramienta de línea de comandos de bq desde el SDK de Cloud, asegúrate de tener la funcionalidad y correcciones más recientes para la herramienta de línea de comandos de bq. Para ello, mantén tu instalación de SDK de Cloud actualizada. Para verificar si ejecutas la versión más reciente del SDK de Cloud, 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 tu instalación actual del SDK de Cloud y el número de versión del SDK de Cloud más reciente. Si descubres que la versión está desactualizada, puedes actualizar la instalación del SDK de Cloud 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 basada en REST estándar, que pueden ser útiles de ver. También es útil adjuntar este registro cuando se informa sobre problemas. El uso de - o stdout en lugar de una ruta de acceso imprime el registro en Google Cloud Console. La configuración de --apilog como stderr da como resultado el archivo de error estándar.

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