En este documento, se describe cómo ejecutar consultas con parámetros en BigQuery.
Ejecuta consultas con parámetros
BigQuery admite parámetros de consulta para ayudar a evitar la inyección de SQL cuando las consultas se construyen con entradas del usuario. Esta función solo está disponible con la sintaxis de SQL estándar. Los parámetros de consulta pueden usarse como sustitutos de expresiones arbitrarias. Los parámetros no se pueden usar como sustitutos de los identificadores, nombres de columnas, nombres de tablas ni otras partes de la consulta.
Para especificar un parámetro con nombre, usa el carácter @
seguido de un identificador, como @param_name
. Por ejemplo, esta consulta encuentra todas las palabras en un corpus específico de Shakespeare, con conteos que son al menos el valor especificado.
#standardSQL SELECT word, word_count FROM `bigquery-public-data.samples.shakespeare` WHERE corpus = @corpus AND word_count >= @min_word_count ORDER BY word_count DESC
Como alternativa, puedes usar el valor de marcador de posición ?
para especificar un parámetro posicional.
Ten en cuenta que una consulta puede usar parámetros posicionales o con nombre, pero no ambos.
Console
Las consultas con parámetros no son compatibles con GCP Console.IU web
Las consultas con parámetros no son compatibles con la IU web de BigQuery.Línea de comandos
Usa--parameter
a fin de proporcionar valores para los parámetros con el formato name:type:value
. Un nombre vacío produce un parámetro posicional. Se puede omitir el tipo para que se suponga STRING
.
La marca --parameter
se debe usar en conjunto con la marca --use_legacy_sql=false
para especificar la sintaxis de SQL estándar.
Especifica tu ubicación mediante la marca --location
(opcional).
bq query \ --use_legacy_sql=false \ --parameter=corpus::romeoandjuliet \ --parameter=min_word_count:INT64:250 \ 'SELECT word, word_count FROM `bigquery-public-data.samples.shakespeare` WHERE corpus = @corpus AND word_count >= @min_word_count ORDER BY word_count DESC'
API
Para usar parámetros con nombre, estableceparameterMode
como NAMED
en la configuración del trabajo de query
.
Propaga queryParameters
con la lista de parámetros de la configuración del trabajo de query
. Configura el name
de cada parámetro con el @param_name
usado en la consulta.
Para habilitar la sintaxis de SQL estándar, configura useLegacySql
como false
.
{
"query": "SELECT word, word_count FROM `bigquery-public-data.samples.shakespeare` WHERE corpus = @corpus AND word_count >= @min_word_count ORDER BY word_count DESC;",
"queryParameters": [
{
"parameterType": {
"type": "STRING"
},
"parameterValue": {
"value": "romeoandjuliet"
},
"name": "corpus"
},
{
"parameterType": {
"type": "INT64"
},
"parameterValue": {
"value": "250"
},
"name": "min_word_count"
}
],
"useLegacySql": false,
"parameterMode": "NAMED"
}
Pruébalo en el Explorador de API de Google.
Para usar parámetros posicionales, configura parameterMode
como POSITIONAL
en la configuración del trabajo de query
.
Go
Antes de probar este ejemplo, sigue las instrucciones de configuración de Go incluidas en la Guía de inicio rápido de BigQuery con bibliotecas cliente. A fin de obtener más información, consulta la Documentación de referencia de la API de Go de BigQuery.
Para usar parámetros con nombre, ingresa el siguiente comando: Para usar parámetros posicionales, ingresa el siguiente comando:Java
Antes de probar este ejemplo, sigue las instrucciones de configuración de Java incluidas en la Guía de inicio rápido de BigQuery con bibliotecas cliente. A fin de obtener más información, consulta la documentación de referencia de la API de BigQuery para Java.
Python
Antes de probar este ejemplo, sigue las instrucciones de configuración de Python incluidas en la Guía de inicio rápido de BigQuery con bibliotecas cliente. A fin de obtener más información, consulta la Documentación de referencia de la API de Python de BigQuery.
Para usar parámetros con nombre, ingresa el siguiente comando: Para usar parámetros posicionales, ingresa el siguiente comando:Node.js
Antes de probar esta muestra, sigue las instrucciones de configuración para Node.js que se encuentran en la Guía de inicio rápido de BigQuery con bibliotecas cliente. A fin de obtener más información, consulta la documentación de referencia de la API de BigQuery para Node.js.
Para usar parámetros con nombre, ingresa el siguiente comando: Para usar parámetros posicionales, ingresa el siguiente comando:Cómo usar arreglos en consultas con parámetros
Para usar un tipo de arreglo en un parámetro de consulta, configura el tipo en ARRAY<T>
donde T
es el tipo de elementos en el arreglo. Construye el valor como una lista separada por comas de elementos encerrados entre corchetes, por ejemplo, [1, 2,
3]
.
Consulta la referencia de los tipos de datos para obtener más información sobre el tipo de arreglo.
Console
Las consultas con parámetros no son compatibles con GCP Console.IU clásica
Las consultas con parámetros no son compatibles con la IU web clásica de BigQuery.Línea de comandos
En esta consulta, se seleccionan los nombres más populares para los bebés varones nacidos en los estados de EE.UU. que comienzan con la letra W.bq query \ --use_legacy_sql=false \ --parameter='gender::M' \ --parameter='states:ARRAY<STRING>:["WA", "WI", "WV", "WY"]' \ 'SELECT name, SUM(number) AS count FROM `bigquery-public-data.usa_names.usa_1910_2013` WHERE gender = @gender AND state IN UNNEST(@states) GROUP BY name ORDER BY count DESC LIMIT 10'
Asegúrate de encerrar la declaración del tipo de arreglo entre comillas simples para que el resultado del comando no se redirija por accidente a un archivo mediante el carácter >
.
API
Para usar un parámetro con valor de arreglo, configuraparameterType
como ARRAY
en la configuración del trabajo de query
.
Si los valores del arreglo son escalares, configura parameterType
como el tipo de valores, por ejemplo, STRING
. Si los valores del arreglo son estructuras, configúralo como STRUCT
y agrega las definiciones de campo necesarias a structTypes
.
Por ejemplo, en esta consulta, se seleccionan los nombres más populares para los bebés varones nacidos en los estados de EE.UU. que comienzan con la letra W.
{
"query": "SELECT name, sum(number) as count\nFROM `bigquery-public-data.usa_names.usa_1910_2013`\nWHERE gender = @gender\nAND state IN UNNEST(@states)\nGROUP BY name\nORDER BY count DESC\nLIMIT 10;",
"queryParameters": [
{
"parameterType": {
"type": "STRING"
},
"parameterValue": {
"value": "M"
},
"name": "gender"
},
{
"parameterType": {
"type": "ARRAY",
"arrayType": {
"type": "STRING"
}
},
"parameterValue": {
"arrayValues": [
{
"value": "WA"
},
{
"value": "WI"
},
{
"value": "WV"
},
{
"value": "WY"
}
]
},
"name": "states"
}
],
"useLegacySql": false,
"parameterMode": "NAMED"
}
Go
Antes de probar este ejemplo, sigue las instrucciones de configuración de Go incluidas en la Guía de inicio rápido de BigQuery con bibliotecas cliente. A fin de obtener más información, consulta la Documentación de referencia de la API de Go de BigQuery.
Java
Antes de probar este ejemplo, sigue las instrucciones de configuración de Java incluidas en la Guía de inicio rápido de BigQuery con bibliotecas cliente. A fin de obtener más información, consulta la documentación de referencia de la API de BigQuery para Java.
Python
Antes de probar este ejemplo, sigue las instrucciones de configuración de Python incluidas en la Guía de inicio rápido de BigQuery con bibliotecas cliente. A fin de obtener más información, consulta la Documentación de referencia de la API de Python de BigQuery.
Node.js
Antes de probar esta muestra, sigue las instrucciones de configuración para Node.js que se encuentran en la Guía de inicio rápido de BigQuery con bibliotecas cliente. A fin de obtener más información, consulta la documentación de referencia de la API de BigQuery para Node.js.
Cómo usar marcas de tiempo en consultas con parámetros
Para usar una marca de tiempo en un parámetro de consulta, configura el tipo en TIMESTAMP
. El valor debe estar en el formato YYYY-MM-DD HH:MM:SS.DDDDDD time_zone
.
Consulta la referencia de tipos de datos para obtener más información sobre el tipo de marca de tiempo.
Console
Las consultas con parámetros no son compatibles con GCP Console.IU clásica
Las consultas con parámetros no son compatibles con la IU web clásica de BigQuery.Línea de comandos
En esta consulta, se agrega una hora al valor del parámetro de marca de tiempo.bq query \ --use_legacy_sql=false \ --parameter='ts_value:TIMESTAMP:2016-12-07 08:00:00' \ 'SELECT TIMESTAMP_ADD(@ts_value, INTERVAL 1 HOUR)'
API
Para usar un parámetro de marca de tiempo, configuraparameterType
como TIMESTAMP
en la configuración del trabajo de consulta.
En esta consulta, se agrega una hora al valor del parámetro de marca de tiempo.
{
"query": "SELECT TIMESTAMP_ADD(@ts_value, INTERVAL 1 HOUR);",
"queryParameters": [
{
"name": "ts_value",
"parameterType": {
"type": "TIMESTAMP"
},
"parameterValue": {
"value": "2016-12-07 08:00:00"
}
}
],
"useLegacySql": false,
"parameterMode": "NAMED"
}
Go
Antes de probar este ejemplo, sigue las instrucciones de configuración de Go incluidas en la Guía de inicio rápido de BigQuery con bibliotecas cliente. A fin de obtener más información, consulta la Documentación de referencia de la API de Go de BigQuery.
Java
Antes de probar este ejemplo, sigue las instrucciones de configuración de Java incluidas en la Guía de inicio rápido de BigQuery con bibliotecas cliente. A fin de obtener más información, consulta la documentación de referencia de la API de BigQuery para Java.
Python
Antes de probar este ejemplo, sigue las instrucciones de configuración de Python incluidas en la Guía de inicio rápido de BigQuery con bibliotecas cliente. A fin de obtener más información, consulta la Documentación de referencia de la API de Python de BigQuery.
Node.js
Antes de probar esta muestra, sigue las instrucciones de configuración para Node.js que se encuentran en la Guía de inicio rápido de BigQuery con bibliotecas cliente. A fin de obtener más información, consulta la documentación de referencia de la API de BigQuery para Node.js.
Cómo usar structs en consultas con parámetros
Para usar una estructura en un parámetro de consulta, configura el tipo en STRUCT<T>
donde T
define los campos y tipos dentro de la estructura. Las definiciones de los campos están separadas por comas y tienen el formato field_name TF
, donde TF
es el tipo de campo. Por ejemplo, STRUCT<x INT64, y STRING>
define una estructura con un campo llamado x
de tipo INT64
, y un segundo campo llamado y
de tipo STRING
.
Consulta la referencia de los tipos de datos para obtener más información sobre el tipo de struct.
Console
Las consultas con parámetros no son compatibles con GCP Console.IU clásica
Las consultas con parámetros no son compatibles con la IU web de BigQuery.Línea de comandos
Esta consulta trivial demuestra el uso de tipos estructurados devolviendo el valor del parámetro.bq query \ --use_legacy_sql=false \ --parameter='struct_value:STRUCT<x INT64, y STRING>:{"x": 1, "y": "foo"}' \ 'SELECT @struct_value AS s'
API
Para usar un parámetro de struct, configuraparameterType
como STRUCT
en la configuración del trabajo de consulta.
Agrega un objeto para cada campo de struct a structTypes
en el queryParameters
del trabajo.
Si los valores de struct son escalares, configura type
como el tipo de los valores, por ejemplo, STRING
. Si los valores de struct son arreglos, configúralo como ARRAY
y configura el campo arrayType
anidado como el tipo correspondiente. Si los valores de struct son estructuras, establece type
como STRUCT
y agrega los structTypes
necesarios.
Esta consulta trivial demuestra el uso de tipos estructurados devolviendo el valor del parámetro.
{
"query": "SELECT @struct_value AS s;",
"queryParameters": [
{
"name": "struct_value",
"parameterType": {
"type": "STRUCT",
"structTypes": [
{
"name": "x",
"type": {
"type": "INT64"
}
},
{
"name": "y",
"type": {
"type": "STRING"
}
}
]
},
"parameterValue": {
"structValues": {
"x": {
"value": "1"
},
"y": {
"value": "foo"
}
}
}
}
],
"useLegacySql": false,
"parameterMode": "NAMED"
}
Go
Antes de probar este ejemplo, sigue las instrucciones de configuración de Go incluidas en la Guía de inicio rápido de BigQuery con bibliotecas cliente. A fin de obtener más información, consulta la Documentación de referencia de la API de Go de BigQuery.
Python
Antes de probar este ejemplo, sigue las instrucciones de configuración de Python incluidas en la Guía de inicio rápido de BigQuery con bibliotecas cliente. A fin de obtener más información, consulta la Documentación de referencia de la API de Python de BigQuery.
Node.js
Antes de probar esta muestra, sigue las instrucciones de configuración para Node.js que se encuentran en la Guía de inicio rápido de BigQuery con bibliotecas cliente. A fin de obtener más información, consulta la documentación de referencia de la API de BigQuery para Node.js.