Explorar la herramienta de línea de comandos bq

La herramienta de línea de comandos bq es una herramienta de línea de comandos basada en Python para BigQuery. En esta página se incluye información general sobre el uso de la herramienta de línea de comandos bq.

Para consultar una referencia completa de todos los comandos y las marcas de bq, consulta la referencia de la herramienta de línea de comandos bq.

Antes de empezar

Antes de poder usar la herramienta de línea de comandos bq, debes usar la consola Google Cloud para crear o seleccionar un proyecto.

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.

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

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

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

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

1. BigQuery se habilita automáticamente en los proyectos nuevos. Para activar BigQuery en un proyecto que ya tengas, ve a

   Enable the BigQuery API.

   Roles required to enable APIs

   To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

   Enable the API

2. Opcional: Habilita la facturación del proyecto. Si no quieres habilitar la facturación ni proporcionar una tarjeta de crédito, puedes seguir los pasos que se indican en este documento. BigQuery te ofrece un entorno aislado para llevar a cabo los pasos. Para obtener más información, consulta Habilitar el entorno aislado de BigQuery.

Introducir comandos de bq en Cloud Shell

Puedes introducir comandos de la herramienta de línea de comandos bq en Cloud Shell desde la consola Google Cloud o desde la CLI de Google Cloud.

• Para usar la herramienta de línea de comandos bq desde la consola, activa Cloud Shell: Google Cloud

  Activar Cloud Shell

• Para usar la herramienta de línea de comandos bq desde gcloud CLI, instala y configura gcloud CLI.

Marcas y argumentos de posicionamiento

La herramienta de línea de comandos bq admite dos tipos de marcas:

• Las marcas globales se pueden usar en todos los comandos.
• Las marcas específicas de un comando se aplican a un comando concreto.

Para ver una lista de las marcas globales y específicas de los comandos disponibles, consulta la referencia de la herramienta de línea de comandos bq.

Coloca las marcas globales antes del comando bq y, a continuación, incluye las marcas específicas del comando. Puedes incluir varias marcas globales o específicas de un comando. Por ejemplo:

bq --location=us mk --reservation --project_id=project reservation_name

Puedes especificar argumentos de comando de las siguientes formas:

• --FLAG ARGUMENT (como se muestra en los ejemplos anteriores)
• --FLAG=ARGUMENT
• --FLAG='ARGUMENT'
• --FLAG="ARGUMENT"
• --FLAG 'ARGUMENT'
• --FLAG "ARGUMENT"

Haz los cambios siguientes:

• FLAG: una marca global o específica de un comando
• ARGUMENT: el argumento de la marca

Algunos comandos requieren que los argumentos se escriban entre comillas simples o dobles. Esto suele ocurrir cuando el argumento contiene espacios, comas u 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, este comando especifica el valor "false" para la marca booleana --use_legacy_sql colocando no delante de la marca:

bq query --nouse_legacy_sql \
'SELECT
   COUNT(*)
 FROM
   `bigquery-public-data`.samples.shakespeare'

También puedes introducir lo siguiente para especificar false como argumento de la marca:

bq query --use_legacy_sql=false \
'SELECT
   COUNT(*)
 FROM
   `bigquery-public-data`.samples.shakespeare'

Ejecutar consultas desde la herramienta de línea de comandos bq

Para tomar una consulta que hayas desarrollado en la Google Cloud consola y ejecutarla desde la herramienta de línea de comandos bq, haz lo siguiente:

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

2. Da formato a la cadena de consulta.

   Si necesitas usar literales de cadena adicionales en la consulta, debes seguir las reglas de comillas del shell que estés usando, como Bash o PowerShell.

   En el siguiente ejemplo se muestra un enfoque habitual en Bash, que consiste en usar comillas dobles para indicar los literales de cadena en la consulta y, a continuación, incluir la consulta en comillas simples:

   'SELECT * FROM mydataset.mytable WHERE column1 = "value";'
   

   Si copias la consulta de otra ubicación, también debes eliminar los comentarios que contenga.

   Por ejemplo, transforma la siguiente consulta de la consola 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 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 Ejecutar tareas de consulta interactivas y por lotes.

Cómo obtener ayuda

Para obtener ayuda sobre la herramienta de línea de comandos bq, puedes introducir los siguientes comandos:

• Para ver la versión instalada de la herramienta de línea de comandos bq, introduce bq version.
• Para ver una lista completa de comandos, introduce bq help.
• Para ver una lista de las marcas globales, introduce bq --help.
• Si necesitas ayuda con un comando específico, escribe bq help COMMAND.
• Para obtener ayuda sobre un comando específico y una lista de marcas globales, introduce bq COMMAND --help.

Sustituye COMMAND por el comando con el que necesitas ayuda.

Definir valores predeterminados para las marcas de línea de comandos

Puedes definir valores predeterminados para las marcas de línea de comandos incluyéndolos en el archivo de configuración de la herramienta de línea de comandos bq, .bigqueryrc. Antes de configurar las opciones predeterminadas, debes crear un archivo .bigqueryrc. Puedes usar el editor de texto que prefieras para crear el archivo. Una vez que hayas creado el archivo .bigqueryrc, puedes especificar la ruta al archivo mediante la marca global --bigqueryrc.

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

Añadir marcas a .bigqueryrc

Para añadir valores predeterminados a las marcas de la línea de comandos en .bigqueryrc, sigue estos pasos:

• Coloca las marcas globales en la parte superior del archivo sin encabezado.
• Para las marcas específicas de un comando, introduce el nombre del comando (entre corchetes) y añade las marcas específicas del 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 definen los valores predeterminados de las siguientes marcas:

• La marca global --apilog se define como stdout para imprimir la salida de depuración en la Google Cloud consola.
• La marca global --format se define como prettyjson para mostrar la salida del comando en un formato JSON legible por humanos.
• La marca global --location se asigna a la ubicación multirregional US.

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

• La marca query específica del comando --max_rows se define como 100 para controlar el número de filas del resultado de la consulta.

• La marca específica del comando query --maximum_bytes_billed se ha definido en 10.000.000 bytes (10 MB) para que las consultas que lean más de 10 MB de datos fallen.

• La marca específica del comando load --destination_kms_key se define como projects/myproject/locations/mylocation/keyRings/myRing/cryptoKeys/myKey.

Ejecutar la herramienta de línea de comandos bq en un shell interactivo

Puedes ejecutar la herramienta de línea de comandos bq en un shell interactivo en el que no tengas que añadir el prefijo bq a los comandos. Para iniciar el modo interactivo, introduce bq shell. Después de iniciar la shell, la petición cambia al ID de tu proyecto predeterminado. Para salir del modo interactivo, introduce exit.

Ejecutar la herramienta de línea de comandos bq en una secuencia de comandos

Puedes ejecutar la herramienta de línea de comandos bq en una secuencia de comandos, como lo harías con un comando de la CLI de Google Cloud. A continuación se muestra un ejemplo de comandos 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'

Ejecutar comandos de bq desde una cuenta de servicio

Puedes usar una cuenta de servicio para hacer llamadas a la API autorizadas o ejecutar trabajos de consulta en tu nombre. Para usar una cuenta de servicio en la herramienta de línea de comandos 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 empezar a ejecutar comandos bq mediante la suplantación de identidad de cuenta de servicio, ejecuta el siguiente comando:

gcloud config set auth/impersonate_service_account SERVICE_ACCOUNT_NAME

Sustituye SERVICE_ACCOUNT_NAME por el nombre de tu cuenta de servicio.

Los comandos bq que ejecutes ahora usarán las credenciales de la cuenta de servicio.

Para dejar de ejecutar comandos bq desde una cuenta de servicio, ejecuta el siguiente comando:

gcloud config unset auth/impersonate_service_account

Ejemplos

Encontrará ejemplos de líneas de comandos en la sección Guías prácticas de la documentación de BigQuery. En esta sección se incluyen enlaces a tareas habituales de la línea de comandos, como crear, obtener, enumerar, eliminar y modificar recursos de BigQuery.

Crear recursos

Para obtener información sobre cómo usar la herramienta de línea de comandos bq para crear recursos, consulta los siguientes artículos:

• Crear un conjunto de datos
• Crear una tabla vacía con una definición de esquema
• Crear una tabla a partir del resultado de una consulta
• Crear una tabla con particiones por hora de ingestión
• Crear una vista

Para ver ejemplos de cómo crear una tabla con un archivo de datos, consulta Cargar datos.

Obtener información sobre los recursos

Para obtener información sobre cómo usar la herramienta de línea de comandos bq para obtener información sobre recursos, consulta los siguientes artículos:

• Obtener información sobre los conjuntos de datos
• Obtener información sobre las tablas
• Obtener información sobre las vistas

Mostrar recursos

Para obtener información sobre cómo usar la herramienta de línea de comandos bq para enumerar recursos, consulta lo siguiente:

• Listar conjuntos de datos
• Tablas de listado
• Vistas de listas

Mostrar tareas

Para obtener información sobre cómo usar la herramienta de línea de comandos bq para enumerar trabajos, consulta lo siguiente:

• Listar trabajos

Actualizar recursos

Para obtener información sobre cómo usar la herramienta de línea de comandos bq para actualizar recursos, consulta los siguientes artículos:

• Actualizar propiedades de los conjuntos de datos
• Actualizar las propiedades de una tabla
• Actualizar propiedades de vista

Cargando datos

Para obtener información sobre cómo usar la herramienta de línea de comandos bq para cargar datos, consulta los siguientes artículos:

• Cargar datos de Avro desde Cloud Storage
• Cargar datos de JSON desde Cloud Storage
• Cargar datos CSV de Cloud Storage
• Cargar datos desde un archivo local

Consultar datos

Para obtener información sobre cómo usar la herramienta de línea de comandos bq para consultar datos, consulta los siguientes artículos:

• Ejecutar consultas
• Escribir resultados de consultas
• Realizar consultas con parámetros

Utilizar fuentes de datos externas

Para obtener información sobre cómo usar la herramienta de línea de comandos bq para consultar datos de fuentes de datos externas, consulta los siguientes artículos:

• Crear una definición de tabla con un archivo de esquema JSON
• Consultar datos de Bigtable
• Consultar datos de Cloud Storage
• Consultar datos de Google Drive

Exportar datos

Para obtener información sobre cómo usar la herramienta de línea de comandos bq para exportar datos, consulta los siguientes artículos:

• Exportar datos almacenados en BigQuery

Utilizar el servicio de transferencia de datos de BigQuery

Para obtener información sobre cómo usar la herramienta de línea de comandos bq con BigQuery Data Transfer Service, consulta los siguientes artículos:

• Configurar una transferencia de Amazon S3
• Configurar una transferencia de Campaign Manager
• Configurar una transferencia de Cloud Storage
• Configurar una transferencia de Google Ad Manager
• Configurar una transferencia de Google Ads
• Configurar una transferencia de Google Merchant Center (beta)
• Configurar una transferencia de Google Play
• Configurar una transferencia de Search Ads 360 (beta)
• Configurar una transferencia de canal de YouTube
• Configurar una transferencia de propietario de contenido de YouTube
• Migrar datos desde Amazon Redshift
• Migrar datos de Teradata
• Gestionar transferencias

Solucionar problemas de la herramienta de línea de comandos bq

En esta sección se explica cómo resolver problemas con la herramienta de línea de comandos bq.

Mantener actualizada la herramienta de línea de comandos gcloud

Si usas la herramienta de línea de comandos bq de Google Cloud CLI, asegúrate de tener las funciones y las correcciones más recientes de la herramienta de línea de comandos bq manteniendo actualizada la instalación de gcloud CLI. Para ver si estás usando la versión más reciente de gcloud CLI, introduce 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 versión de la CLI de gcloud más reciente. Si detectas que tu versión está obsoleta, puedes actualizar tu instalación de la CLI de gcloud a la versión más reciente introduciendo el siguiente comando en Cloud Shell:

gcloud components update

Depuración

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

• Consulta las solicitudes enviadas y recibidas. Añade la marca --apilog=PATH_TO_FILE para guardar un registro de las operaciones en un archivo local. Sustituye PATH_TO_FILE por la ruta en la que quieras guardar el registro. La herramienta de línea de comandos bq funciona haciendo llamadas a APIs estándar basadas en REST, que pueden ser útiles. También es útil adjuntar este registro cuando informes de problemas. Si usas - o stdout en lugar de una ruta, el registro se imprimirá en la consola Google Cloud . Si asignas el valor --apilog a stderr, se generará un archivo de error estándar. Para registrar más solicitudes, usa la marca --httplib2_debuglevel=LOG_LEVEL. Un valor más alto de LOG_LEVEL registra más información sobre las solicitudes HTTP.

• Soluciona los errores. Introduce la marca --format=prettyjson cuando quieras obtener el estado de un trabajo o ver información detallada sobre recursos, como tablas y conjuntos de datos. Si se usa esta marca, la respuesta se muestra en formato JSON, incluida la propiedad reason. Puedes usar la propiedad reason para buscar los pasos para solucionar problemas. Para obtener más información sobre los errores que se produzcan durante la ejecución, usa la marca --debug_mode.