Usa consultas de Dataflow SQL parametrizadas

En esta página, se explica cómo ejecutar consultas de Dataflow SQL parametrizadas.

Dataflow SQL admite parámetros de consulta con nombre y posicionales. Especifica parámetros de consulta con la siguiente sintaxis:

Parámetros con nombre con el carácter @ seguido de un identificador, como @param_name
Parámetros posicionales con el carácter ?

Puedes usar parámetros con nombre o posicionales en una consulta, pero no ambos.

Ejecuta consultas con parámetros

Para ejecutar una consulta parametrizada, define el tipo de dato y el valor de los parámetros de consulta. El tipo y el valor de los parámetros de consulta deben coincidir con el tipo de objetos de base de datos que los parámetros representan.

Puedes definir parámetros de consulta con la consola de Google Cloud o Google Cloud CLI:

Console

Para definir los parámetros de consulta, usa la IU de Dataflow SQL:

Ve a la IU de Dataflow SQL.

Ir a la IU de Dataflow SQL
Ingresa la consulta de Dataflow SQL en el editor de consultas.

Por ejemplo, la siguiente consulta selecciona viajes en taxi que cuestan al menos el precio especificado:
```
SELECT *
FROM pubsub.topic.`pubsub-public-data`.`taxirides-realtime`
WHERE
 ride_status = "dropoff"
 AND meter_reading >= @price_min
```
Haz clic en Crear trabajo de Cloud Dataflow para abrir un panel de opciones de trabajo.
En la sección Parámetros de consulta de SQL del panel, completa los campos Nombre, Tipo y Valor. El nombre del parámetro en el ejemplo es price_min, y el tipo es FLOAT64.

Si el parámetro es posicional, omite el campo Nombre.
Si la consulta contiene más parámetros, haga clic en Agregar parámetro (Opcional).

La consola de Google Cloud no es compatible con los parámetros ARRAY ni STRUCT. Para especificar los parámetros ARRAY o STRUCT, usa Google Cloud CLI.

gcloud

Para definir los parámetros de consulta, usa el comando gcloud dataflow sql query y las marcas --parameter.

Puedes repetir la marca --parameter para cada parámetro de consulta. Establece cada marca --parameter en name:type:value.

El siguiente comando ejecuta una consulta parametrizada en una transmisión de Pub/Sub de viajes en taxi:

gcloud dataflow sql query \
  --job-name=job-name \
  --region=region \
  --bigquery-dataset=destination-dataset \
  --bigquery-table=destination-table \
  --parameter=status:STRING:dropoff \
  --parameter=price_min:FLOAT64:5.5 \
'SELECT *
FROM pubsub.topic.`pubsub-public-data`.`taxirides-realtime`
WHERE
  ride_status = @status
  AND meter_reading >= @price_min'

Si el parámetro es posicional, configura las marcas --parameter en :type:value.

Usa arreglos en consultas con parámetros

Para usar un tipo de arreglo en un parámetro de consulta, establece el tipo en ARRAY<data-type>. Crea el valor como una lista separada por comas de elementos entre corchetes, como ["pickup", "enroute", "dropoff"].

Console

La IU de Dataflow SQL no admite parámetros ARRAY en consultas de Dataflow SQL.

gcloud

Para definir un parámetro de arreglo, configura la marca --parameter del comando gcloud dataflow sql query en name:ARRAY<data-type>:value.

El siguiente comando ejecuta la consulta con un parámetro de arreglo con nombre en una transmisión de Pub/Sub de viajes en taxi:

gcloud dataflow sql query \
  --job-name=job-name
  --region=region
  --bigquery-dataset=destination-dataset \
  --bigquery-table=destination-table \
  --parameter='status:ARRAY<STRING>:["pickup", "enroute", "dropoff"]' \
'SELECT *
FROM pubsub.topic.`pubsub-public-data`.`taxirides-realtime`
WHERE
  ride_status IN UNNEST(@status)'

A fin de obtener más información, consulta la referencia de Dataflow SQL para tipos ARRAY.

Usa marcas de tiempo en consultas con parámetros

Para usar una marca de tiempo en un parámetro de consulta, establece el tipo en STRING, pero construye el valor en el formato de marca de tiempo canónico.

Console

Para definir parámetros de marcas de tiempo, usa la IU de Dataflow SQL:

Ve a la IU de Dataflow SQL.

Ir a la IU de Dataflow SQL
Ingresa la consulta de Dataflow SQL en el editor de consultas.

Por ejemplo, la siguiente consulta selecciona viajes en taxi que se realizaron después de la fecha especificada:
```
SELECT *
FROM pubsub.topic.`pubsub-public-data`.`taxirides-realtime`
WHERE
  event_timestamp >= TIMESTAMP (@date_min)
```
Haz clic en Crear trabajo de Cloud Dataflow para abrir un panel de opciones de trabajo.
En la sección Parámetros de consulta de SQL, haz clic en Agregar parámetro.
En el campo Tipo, selecciona STRING.
En el campo Valor, ingresa una marca de tiempo.

gcloud

Para definir un parámetro de marca de tiempo, establece la marca --parameter del comando gcloud dataflow sql query en name:STRING:value.

El siguiente comando ejecuta una consulta con un parámetro de marca de tiempo con nombre en una transmisión de Pub/Sub de viajes en taxi:

gcloud dataflow sql query \
  --job-name=job-name \
  --region=region \
  --bigquery-dataset=destination-dataset \
  --bigquery-table=destination-table \
  --parameter='date_min:STRING:2020-01-01 00:00:00.000 UTC' \
'SELECT *
FROM pubsub.topic.`pubsub-public-data`.`taxirides-realtime`
WHERE
  event_timestamp >= TIMESTAMP (@date_min)'

A fin de obtener más información, consulta la referencia de Dataflow SQL para los tipos TIMESTAMP.

Usa structs en consultas con parámetros

Para usar un struct en un parámetro de consulta, establece el tipo en STRUCT<field-name data-type, ...>. Construye el valor como una lista separada por comas de pares clave-valor.

Por ejemplo, STRUCT<date_min TIMESTAMP, status STRING> define una struct con un campo llamado date_min de tipo TIMESTAMP y un campo llamado status de tipo STRING.

Console

La IU de Dataflow SQL no admite parámetros STRUCT en consultas de Dataflow SQL.

gcloud

Para definir un parámetro de arreglo, configura la marca --parameter del comando gcloud dataflow sql query en name:STRUCT<field-name data-type, ...>:value.

El siguiente comando ejecuta una consulta con un parámetro de struct con nombre en una transmisión de Pub/Sub de viajes en taxi:

gcloud dataflow sql query \
  --job-name=job-name \
  --region=region \
  --bigquery-dataset=destination-dataset \
  --bigquery-table=destination-table \
  --parameter='rides:STRUCT<riders_min INT64, status STRING>:
  {"riders_min": 2, "status": "dropoff"}' \
'SELECT *
FROM pubsub.topic.`pubsub-public-data`.`taxirides-realtime`
WHERE
  passenger_count >= @rides.riders_min
  AND ride_status = @rides.status'

A fin de obtener más información, consulta la referencia de Dataflow SQL para los tipos STRUCT.