Usa la herramienta de línea de comandos de BigQuery

bq es una herramienta de línea de comandos basada en Python para BigQuery. 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 poder usar la herramienta de línea de comandos de BigQuery, debes usar la Google Cloud Platform Console para crear o seleccionar un proyecto y habilitar la facturación. También necesitas instalar el SDK de Google Cloud.

1. Sign in to your Google Account.

   If you don't already have one, sign up for a new account.

2. Select or create a GCP project.

   Note: If you don't plan to keep the resources you create in this procedure, create a new project instead of selecting an existing project. After you finish following these steps, you can delete the project, removing all resources associated with the project.

   Go to the Project selector page

3. Comprueba que la facturación esté habilitada en tu proyecto.

   Descubre cómo puedes habilitar la facturación

4. Install and initialize the Cloud SDK.
5. BigQuery se habilita automáticamente en proyectos nuevos. Para activar BigQuery en un proyecto preexistente, ve a Habilita las BigQuery API necesarias.

   Habilita las API

En lugar de descargar y luego instalar el SDK de Google Cloud, puedes usar una versión preinstalada del SDK en Google Cloud Shell.

Uso general

Posicionamiento de la marca

bq admite dos tipos de marcas: marcas globales y marcas de comando. Se deben usar en el orden que se muestra a continuación:

    bq --global_flag [ARGUMENT] bq_command --command-specific_flag [ARGUMENT]

• Las marcas globales (o marcas comunes) se pueden usar en todos los comandos.
• Las marcas específicas de comando se aplican a un comando específico.

Separa múltiples marcas globales o específicas de comando con un espacio. Por ejemplo:

    bq --global_flag [ARGUMENT] --global_flag [ARGUMENT] bq_command --command-specific_flag [ARGUMENT] --command-specific_flag [ARGUMENT]

Puedes especificar argumentos de comando de una de las siguientes maneras:

• --flag=[ARGUMENT]
• --flag='[ARGUMENT]'
• --flag="[ARGUMENT]"
• --flag [ARGUMENT]
• --flag '[ARGUMENT]'
• --flag "[ARGUMENT]"

Cada uno de estos métodos se usa durante toda la documentación de BigQuery.

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 especificar un =[ARGUMENT].

Por ejemplo, este comando especifica falso para la marca booleana --use_legacy_sql cuando colocas 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, debes ingresar lo siguiente:

bq query --use_legacy_sql=false 'select count(*) from `bigquery-public-data.samples.shakespeare`'

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.

Obtén ayuda

Puedes ingresar los siguientes comandos a fin de obtener ayuda para la herramienta de línea de comandos de bq:

• Para la versión instalada 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.

Depuración

Puedes ingresar los siguientes comandos para depurar bq:

• Para ver solicitudes enviadas y recibidas

  Agrega la marca --apilog=[PATH_TO_FILE] para guardar un registro de operaciones en un archivo local. bq funciona haciendo llamadas a la API basadas en REST estándar que pueden ser útiles de ver. También es útil adjuntar este registro cuando se reportan problemas. Usar - o stdout en lugar de una ruta de archivo imprimirá el registro en la consola. La configuración de --apilog en stderr da como resultado el archivo de error estándar.

• Para ayudar a solucionar errores

  Ingresa la marca --format=prettyjson cuando obtengas el estado del trabajo o cuando veas información detallada sobre recursos, como tablas y conjuntos de datos. Usar este indicador genera la respuesta en formato JSON, incluida la propiedad de reason. Puedes usar la propiedad de reason a fin de buscar los pasos para la solución de problemas.

Configura los valores predeterminados para marcas de línea de comandos

Puedes establecer valores predeterminados para las marcas de línea de comandos cuando los incluyes en el archivo de configuración de la herramienta de línea de comandos .bigqueryrc. Antes de configurar tus opciones predeterminadas, primero debes crear un archivo .bigqueryrc. Puedes usar tu editor de texto preferido para crear el archivo. Después de crear el archivo .bigqueryrc, puedes especificar la ruta al archivo usando la marca global --bigqueryrc.

Si la marca --bigqueryrc no se especifica, se usa la variable de entorno BIGQUERYRC. Si eso no se especifica, se usa la ruta ~/.bigqueryrc. La ruta predeterminada es $HOME/.bigqueryrc.

Nota: No se recomienda crear un archivo .bigqueryrc con el comando bq init.

Agrega marcas a .bigqueryrc

A fin de agregar valores predeterminados para las marcas de línea de comandos .bigqueryrc:

• 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) debajo de este en el siguiente formato:

  [COMMAND]
  --command-specific_flag=[ARGUMENT]
  --command-specific_flag=[ARGUMENT]
  

Cuando ingreses la marca de línea de comandos en .bigqueryrc, debes especificar el argumento de la marca en el siguiente formato =[ARGUMENT].

.bigqueryrc se lee cada vez que ejecutas bq por lo que los cambios se deben actualizar de inmediato. Cuando ejecutas bq en modo interactivo (bq shell), debes reiniciar el shell para que los cambios se apliquen.

Ejemplo

Este ejemplo configura valores predeterminados para los siguientes marcadores globales:

• --apilog está configurado en stdout para imprimir la salida de depuración en la consola.
• --format está configurado en prettyjson para mostrar el resultado del comando en un formato JSON legible.
• --location está configurado en la ubicación de varias regiones de US.

Este ejemplo establece valores predeterminados para las siguientes marcas específicas de comando de query:

• --use_legacy_sql está configurado en false para hacer que el SQL estándar sea la sintaxis de consulta predeterminada.

  Nota: No puedes usar --nouse_legacy_sql en .bigqueryrc.

• --max_rows está configurado en 100 para controlar el número de filas en el resultado de la consulta.

• --maximum_bytes_billed está configurado en 10,000,000 bytes (10 MB) para fallar las consultas que leen más de 10 MB de datos.

Este ejemplo configura un valor predeterminado para la siguiente marca específica de comando load:

• --destination_kms_key está configurado en projects/myproject/locations/mylocation/keyRings/myRing/cryptoKeys/myKey.

credential_file = [PATH_TO_CREDENTIAL_FILE]
--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

Para confirmar tu configuración, ingresa el siguiente comando:

cat ~/.bigqueryrc

Ejecuta bq en un shell interactivo

Puedes ejecutar bq en un shell interactivo donde no necesitas prefijar los comandos con bq. Para iniciar el modo interactivo, ingresa bq shell. Después de iniciar el shell, la solicitud cambia al ID de tu proyecto predeterminado. Para salir del modo interactivo, ingresa exit.

Ejemplos

Puedes encontrar ejemplos de la línea de comandos en la sección de instrucciones de la documentación de BigQuery de la Guía práctica. A continuación, se encuentran vínculos a tareas comunes de la línea de comandos, como crear, obtener, listar, 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 para crear recursos, consulta:

• 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 en tiempo de transferencia.
• Crea una vista.

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 para obtener información sobre los recursos, consulta:

• Obtén información sobre los conjuntos de datos.
• Obtén información sobre las tablas.
• Obtén información sobre las vistas.

Muestra una lista de recursos

A fin de obtener información sobre el uso de la herramienta de línea de comandos para listar recursos, consulta:

• Muestra una lista de los conjuntos de datos
• Muestra una lista de tablas
• Muestra una lista de vistas

Actualiza recursos

A fin de obtener información sobre el uso de la herramienta de línea de comandos para actualizar recursos, consulta:

• Actualiza las propiedades del conjunto de datos.
• Actualiza las propiedades de tabla.
• Actualiza las propiedades de las vistas.

Carga datos

A fin de obtener información sobre el uso de la herramienta de línea de comandos para cargar datos, consulta:

• 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 para consultar datos, consulta:

• Consultas en ejecución
• 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 para consultar datos en fuentes de datos externos, consulta:

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

Exporta datos

A fin de obtener información sobre el uso de la herramienta de línea de comandos para exportar datos, consulta:

• Exporta datos almacenados en BigQuery

Usa el servicio de transferencia de datos de BigQuery

A fin obtener información sobre el uso de la herramienta de línea de comandos con el servicio de transferencia de datos de BigQuery, consulta:

• Configura una transferencia de Campaign Manager.
• Configura una transferencia de Cloud Storage (Beta).
• Configura una transferencia de Google Ad Manager.
• Configura una transferencia de Google Ads.
• Configura una transferencia de Google Play (Beta).
• Configura una transferencia de canal de YouTube.
• Configura una transferencia de propietario de contenido de YouTube.

• Obtén información sobre las configuraciones de transferencia.
• Muestra una lista de configuraciones de transferencia.
• Ve el historial de ejecución.
• Ve detalles de ejecución de transferencia y mensajes de registro.
• Actualiza las configuraciones de transferencia.