Usar consultas SQL do Dataflow parametrizadas

Esta página explica como executar consultas SQL do Dataflow parametrizadas.

O SQL do Dataflow suporta parâmetros de consulta posicionais e com nome. Especifique os parâmetros de consulta com a seguinte sintaxe:

  • Parâmetros com nome com o caráter @ seguido de um identificador, como @param_name
  • Parâmetros posicionais com o caráter ?

Pode usar parâmetros com nome ou posicionais numa consulta, mas não ambos.

Executar consultas parametrizadas

Para executar uma consulta parametrizada, defina o tipo de dados e o valor dos parâmetros de consulta. O tipo e o valor dos parâmetros de consulta têm de corresponder ao tipo dos objetos da base de dados que os parâmetros representam.

Pode definir parâmetros de consulta através da Google Cloud consola ou da CLI Google Cloud:

Consola

Para definir parâmetros de consulta, use a IU do SQL do Dataflow:

  1. Aceda à IU do Dataflow SQL.

    Aceda à IU do Dataflow SQL

  2. Introduza a consulta SQL do Dataflow no editor de consultas.

    Por exemplo, a seguinte consulta seleciona viagens de táxi que custam, pelo menos, o preço especificado:

    SELECT *
FROM pubsub.topic.`pubsub-public-data`.`taxirides-realtime`
WHERE
 ride_status = "dropoff"
 AND meter_reading >= @price_min

  3. Clique em Criar tarefa do Cloud Dataflow para abrir um painel de opções de tarefas.

  4. Na secção Parâmetros de consulta SQL do painel, preencha os campos Nome, Tipo e Valor. O nome do parâmetro no exemplo é price_min e o tipo é FLOAT64.

    Se o parâmetro for posicional, omita o campo Nome.

  5. (Opcional) Se a consulta contiver mais parâmetros, clique em Adicionar parâmetro.

A Google Cloud consola não suporta parâmetros ARRAY nem STRUCT. Para especificar parâmetros ARRAY ou STRUCT, use a CLI do Google Cloud.

gcloud

Para definir parâmetros de consulta, use o comando gcloud dataflow sql query e as flags --parameter.

Pode repetir a flag --parameter para cada parâmetro de consulta. Defina cada sinalizador --parameter como name:type:value.

O comando seguinte executa uma consulta parametrizada num stream do Pub/Sub de viagens de táxi:

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'

Se o parâmetro for posicional, defina as flags --parameter como :type:value.

Usar matrizes em consultas parametrizadas

Para usar um tipo de matriz num parâmetro de consulta, defina o tipo como ARRAY<data-type>. Construa o valor como uma lista de elementos separados por vírgulas entre parênteses retos, como ["pickup", "enroute", "dropoff"].

Consola

A IU do Dataflow SQL não suporta parâmetros ARRAY em consultas do Dataflow SQL.

gcloud

Para definir um parâmetro de matriz, defina o sinalizador --parameter do comando gcloud dataflow sql query como name:ARRAY<data-type>:value

O comando seguinte executa uma consulta com um parâmetro de matriz com nome num fluxo do Pub/Sub de viagens de táxi:

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 mais informações, consulte a referência do SQL do Dataflow para os tipos ARRAY.

Usar datas/horas nas consultas parametrizadas

Para usar uma data/hora num parâmetro de consulta, defina o tipo como STRING, mas crie o valor no formato de data/hora canónico.

Consola

Para definir parâmetros de data/hora, use a IU SQL do Dataflow:

  1. Aceda à IU do Dataflow SQL.

    Aceda à IU do Dataflow SQL

  2. Introduza a consulta SQL do Dataflow no editor de consultas.

    Por exemplo, a seguinte consulta seleciona viagens de táxi que ocorreram após a data especificada:

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

  3. Clique em Criar tarefa do Cloud Dataflow para abrir um painel de opções de tarefas.

  4. Na secção Parâmetros de consulta SQL, clique em Adicionar parâmetro.

  5. No campo Tipo, selecione STRING.

  6. No campo Valor, introduza uma data/hora.

gcloud

Para definir um parâmetro de indicação de tempo, defina o sinalizador --parameter do comando gcloud dataflow sql query como name:STRING:value

O comando seguinte executa uma consulta com um parâmetro de data/hora com nome numa stream do Pub/Sub de viagens de táxi:

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 mais informações, consulte a referência de SQL do Dataflow para os tipos TIMESTAMP.

Usar structs em consultas parametrizadas

Para usar uma struct num parâmetro de consulta, defina o tipo como STRUCT<field-name data-type, ...>. Construa o valor como uma lista separada por vírgulas de pares de chave-valor.

Por exemplo, STRUCT<date_min TIMESTAMP, status STRING> define uma struct com um campo denominado date_min do tipo TIMESTAMP e um campo denominado status do tipo STRING.

Consola

A IU do Dataflow SQL não suporta parâmetros STRUCT em consultas do Dataflow SQL.

gcloud

Para definir um parâmetro de matriz, defina o sinalizador --parameter do comando gcloud dataflow sql query como name:STRUCT<field-name data-type, ...>:value

O comando seguinte executa uma consulta com um parâmetro struct denominado numa stream do Pub/Sub de viagens de táxi:

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 mais informações, consulte a referência de SQL do Dataflow para os tipos STRUCT.