Usar consultas de Dataflow SQL con parámetros

En esta página se explica cómo ejecutar consultas de Dataflow SQL con parámetros.

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

  • Parámetros con nombre que incluyen el carácter @ seguido de un identificador, como en el ejemplo siguiente: @param_name
  • Parámetros posicionales con el carácter ?

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

Realizar consultas con parámetros

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

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

Consola

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

  1. Ve a la interfaz de usuario de Dataflow SQL.

    Ir a la interfaz de usuario de Dataflow SQL

  2. Introduce la consulta de Dataflow SQL en el editor de consultas.

    Por ejemplo, la siguiente consulta selecciona los 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

  3. Haz clic en Crear tarea de Cloud Dataflow para abrir un panel con las opciones de la tarea.

  4. En la sección Parámetros de consulta SQL del panel, rellena los campos Nombre, Tipo y Valor. El nombre del parámetro del ejemplo es price_min y el tipo es FLOAT64.

    Si el parámetro es posicional, omita el campo Nombre.

  5. (Opcional) Si la consulta contiene más parámetros, haga clic en Añadir parámetro.

La consola Google Cloud no admite 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. Define cada marca --parameter como name:type:value.

El siguiente comando ejecuta una consulta con parámetros en un flujo 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, asigna el valor :type:value a las marcas --parameter.

Usar matrices en consultas con parámetros

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

Consola

La interfaz de usuario de Dataflow SQL no admite parámetros ARRAY en las consultas de Dataflow SQL.

gcloud

Para definir un parámetro de matriz, asigna el valor name:ARRAY<data-type>:value a la marca --parameter del comando gcloud dataflow sql query.

El siguiente comando ejecuta una consulta con un parámetro de array con nombre en un flujo 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)'

Para obtener más información, consulta la referencia de Dataflow SQL sobre los tipos ARRAY.

Usar marcas de tiempo en consultas con parámetros

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

Consola

Para definir los parámetros de marca de tiempo, usa la interfaz de usuario de Dataflow SQL:

  1. Ve a la interfaz de usuario de Dataflow SQL.

    Ir a la interfaz de usuario de Dataflow SQL

  2. Introduce la consulta de Dataflow SQL en el editor de consultas.

    Por ejemplo, la siguiente consulta selecciona los viajes en taxi que se produjeron después de la fecha especificada:

    SELECT *
FROM pubsub.topic.`pubsub-public-data`.`taxirides-realtime`
WHERE
  event_timestamp >= TIMESTAMP (@date_min)

  3. Haz clic en Crear tarea de Cloud Dataflow para abrir un panel con las opciones de la tarea.

  4. En la sección Parámetros de consulta SQL, haga clic en Añadir parámetro.

  5. En el campo Type (Tipo), selecciona STRING.

  6. En el campo Valor, introduce una marca de tiempo.

gcloud

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

El siguiente comando ejecuta una consulta con un parámetro de marca de tiempo con nombre en un flujo 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)'

Para obtener más información, consulta la referencia de Dataflow SQL sobre los tipos TIMESTAMP.

Usar structs en consultas con parámetros

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

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

Consola

La interfaz de usuario de Dataflow SQL no admite parámetros STRUCT en las consultas de Dataflow SQL.

gcloud

Para definir un parámetro de matriz, asigna el valor name:STRUCT<field-name data-type, ...>:value a la marca --parameter del comando gcloud dataflow sql query.

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

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'

Para obtener más información, consulta la referencia de Dataflow SQL sobre los tipos STRUCT.