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 poder 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 proyecto

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

    Habilita la API

    .
  4. BigQuery proporciona una zona de pruebas si no deseas proporcionar una tarjeta de crédito o habilitar la facturación del proyecto. Los pasos de este tema funcionan para un proyecto, más allá de si el proyecto tiene o no habilitada la facturación. Si deseas habilitar la facturación, consulta cómo habilitar la facturación.

Ingresa los comandos 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.

Cómo colocar 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 de comandos. 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: Es 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 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 realizar una consulta que hayas desarrollado 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 con la consulta.
  2. Reemplaza las comillas simples (') en la consulta por 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 relacionada 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 los 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 configura como 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 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 una shell interactiva

Puedes ejecutar la herramienta de línea de comandos de bq en una shell interactiva en la que no necesitas insertar prefijos en 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 bq en una secuencia de comandos, como ejecutarías un comando de la herramienta de línea de comandos de gcloud. El siguiente es un ejemplo de los comandos gcloud y bq en una secuencia de comandos 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 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 obtener información sobre el uso de 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 quieres obtener información sobre el uso de la herramienta de línea de comandos de bq para enumerar recursos, consulta los siguientes vínculos:

Actualiza recursos

A fin de 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 lo siguiente:

Consulta datos

Si deseas obtener información sobre el uso de la herramienta de línea de comandos de bq para consultar datos, consulta los siguientes vínculos:

Usa fuentes de datos externas

Si deseas obtener información sobre el uso de la herramienta de línea de comandos de bq para consultar datos en fuentes de datos externas, lee los siguientes vínculos:

Exporta datos

Si deseas 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

Para 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 SDK de Cloud. la instalación de la app. Para ver si ejecutas la última versión 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 la instalación actual del SDK de Cloud y el número de versión más reciente. Si descubres que tu versión está desactualizada, ingresa el siguiente comando en Cloud Shell para actualizar la instalación del SDK de Cloud a la versión más reciente:

gcloud components update

Depuración

Puedes ingresar los siguientes comandos para depurar la herramienta de línea de comandos de bq:

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