Como usar consultas parametrizadas do Dataflow SQL

Nesta página, você verá como executar consultas SQL parametrizadas do Dataflow.

O Dataflow SQL é compatível com parâmetros de consulta nomeados e posicionais. Especifique os parâmetros de consulta com a seguinte sintaxe:

Parâmetros nomeados com o caractere @ seguido porum identificador, como @param_name.
Parâmetros posicionais com o caractere ?.

É possível usar parâmetros nomeados ou posicionais em uma consulta, mas não ambos.

Como 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 precisam corresponder ao tipo de objetos de banco de dados que os parâmetros representam.

Defina os parâmetros de consulta usando o Console do Google Cloud ou a Google Cloud CLI:

Console

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

Acesse a IU do Dataflow SQL.

Acessar a IU do Dataflow SQL
Digite a consulta SQL do Dataflow no editor de consultas.

Por exemplo, a consulta a seguir 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
```
Clique em Criar job do Cloud Dataflow para abrir um painel de opções de job.
Na seçã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.
(Opcional) Se a consulta tiver mais parâmetros, clique em Adicionar parâmetro.

O Console do Google Cloud não é compatível com os parâmetros ARRAY ou STRUCT. Para especificar os 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 sinalizações --parameter.

Repita a sinalização --parameter para cada parâmetro de consulta. Defina cada sinalização --parameter como name:type:value.

O comando a seguir executa uma consulta parametrizada em um 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: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 sinalizações --parameter como :type:value.

Como usar matrizes em consultas parametrizadas

Para usar um tipo de matriz em um parâmetro de consulta, defina o tipo como ARRAY<data-type>. Crie o valor como uma lista separada por vírgulas dos elementos, entre colchetes, como ["pickup", "enroute", "dropoff"].

Console

A IU do Dataflow SQL não é compatível com parâmetros ARRAY em consultas SQL do Dataflow.

gcloud

Para configurar um parâmetro de matriz, defina a sinalização --parameter do comando gcloud dataflow sql query como name:ARRAY<data-type>:value.

O comando a seguir executa uma consulta com um parâmetro de matriz nomeado em um 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 Dataflow SQL para tipos ARRAY.

Como usar carimbos de data/hora em consultas parametrizadas

Para usar um carimbo de data/hora em um parâmetro de consulta, defina o tipo como STRING, mas crie o valor no formato de carimbo de data/hora canônico.

Console

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

Acesse a IU do Dataflow SQL.

Acessar a IU do Dataflow SQL
Digite a consulta SQL do Dataflow no editor de consultas.

Por exemplo, a consulta a seguir 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)
```
Clique em Criar job do Cloud Dataflow para abrir um painel de opções de job.
Na seção Parâmetros de consulta SQL, clique em Adicionar parâmetro.
No campo Tipo, selecione STRING.
No campo Valor, insira um carimbo de data/hora.

gcloud

Para definir um parâmetro de carimbo de data/hora, defina a sinalização --parameter do comando gcloud dataflow sql query como name:STRING:value.

O comando a seguir executa uma consulta com um parâmetro de carimbo de data/hora nomeado em um 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='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 do Dataflow SQL para tipos TIMESTAMP.

Como usar estruturas em consultas parametrizadas

Para usar uma estrutura em um 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 estrutura com um campo chamado date_min do tipo TIMESTAMP e um campo denominado status do tipo STRING.

Console

A IU do Dataflow SQL não é compatível com parâmetros STRUCT em consultas SQL do Dataflow.

gcloud

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

O comando a seguir executa uma consulta com um parâmetro de estrutura nomeado em um 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='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 do Dataflow SQL para tipos STRUCT.