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 y, luego, instalar el SDK de Cloud.
- Accede a tu Cuenta de Google.
Si todavía no tienes una cuenta, regístrate para obtener una nueva.
-
En la página del selector de proyectos de Google Cloud Console, selecciona o crea un proyecto de Google Cloud.
- Instala e inicializa el SDK de Cloud.
- BigQuery se habilita de forma automática en proyectos nuevos. Para activar BigQuery en un proyecto existente, ve a Habilita la API BigQuery. .
- 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.
En lugar de descargar el SDK de Cloud para instalarlo, puedes usar una versión preinstalada del SDK de Cloud en Google Cloud Shell.
Uso general
Posicionamiento de marcas
bq
admite dos tipos de marcas: marcas globales y marcas de comando.
Deben usarse en el orden que se muestra aquí:
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 =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, debes ingresar el siguiente comando:
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 para obtener ayuda relacionada con la herramienta de línea de comandos de bq
:
- Para obtener la versión instalada de
bq
, ingresabq 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, haz lo siguiente:
- Agrega la marca
--apilog=path_to_file
para guardar un registro de operaciones en un archivo local.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-
ostdout
en lugar de una ruta de archivo imprimirá el registro en la consola. La configuración de--apilog
comostderr
da como resultado el archivo de error estándar.
- Para ayudar a solucionar 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 propiedadreason
. Puedes usar la propiedadreason
a fin de buscar los pasos para solucionar problemas.
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 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 eso no se especifica, se usa la ruta ~/.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) debajo de este en el siguiente formato:
command --command-specific_flag=argument --command-specific_flag=argument
Cuando ingresas las marcas 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 deben actualizarse de inmediato. Cuando ejecutes bq en el modo interactivo (bq shell
), debes reiniciar la shell para que los cambios se apliquen.
Ejemplo
En este ejemplo, se configuran valores predeterminados para las siguientes marcas globales:
--apilog
se configura comostdout
para imprimir el resultado de depuración en la consola.--format
se configura comoprettyjson
para mostrar el resultado del comando en un formato JSON legible.--location
se configura en la ubicación multirregiónUS
.
En este ejemplo, se configuran los valores predeterminados para las siguientes marcas específicas de comando query
:
--use_legacy_sql
se configura comofalse
para que SQL estándar sea la sintaxis de consulta predeterminada.--max_rows
se establece en 100 para controlar el número de filas en el resultado de la consulta.--maximum_bytes_billed
se configura en 10,000,000 bytes (10 MB) para que fallen las consultas que leen más de 10 MB de datos.
En este ejemplo, se configura un valor predeterminado para la siguiente marca específica de comando load
:
--destination_kms_key
se configura comoprojects/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 una shell interactiva
Puedes ejecutar 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
.
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 bq
para crear recursos, consulta los siguientes vínculos:
- 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 por tiempo de transferencia
- Crea vistas
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:
- Obtén información sobre los conjuntos de datos
- Obtén información sobre las tablas
- Obtén información sobre las vistas
Haz una lista de recursos
A fin de obtener información sobre el uso de la herramienta de línea de comandos bq
para crear una lista de recursos, consulta los siguientes vínculos:
Actualiza recursos
Si deseas obtener información sobre el uso de la herramienta de línea de comandos bq
para actualizar recursos, consulta los siguientes vínculos:
- Actualiza las propiedades del conjunto de datos
- Actualiza las propiedades de las tablas
- Actualiza propiedades de la vista
Cargar datos
Si deseas obtener información sobre el uso de la herramienta de línea de comandos bq
para cargar datos, consulta los siguientes vínculos:
- 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 bq
para consultar datos, revisa los siguientes vínculos:
- Cómo ejecutar consultas interactivas
- 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 bq
para consultar datos en fuentes de datos externas, consulta los siguientes vínculos:
- 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
Exportar datos
A fin de obtener información sobre el uso de la herramienta de línea de comandos 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 bq
con el Servicio de transferencia de datos de BigQuery, consulta los siguientes vínculos:
- Configura una transferencia de Campaign Manager.
- Configura una transferencia de Cloud Storage.
- Configura una transferencia de Google Ad Manager.
- Configura una transferencia de Google Ads.
- Configura una transferencia de Google Merchant Center (Beta)
- Configura una transferencia de Google Play.
- Configura una transferencia de Search Ads 360 (Beta).
- Configura una transferencia de canal de YouTube
- Configura una transferencia de propietario de contenido de YouTube
- Obtén información sobre las opciones de configuración de transferencias
- Lista de opciones de configuración de transferencias
- Consulta el historial de ejecución
- Consulta detalles de ejecución de transferencia y mensajes de registro
- Actualiza una transferencia