Utilizzo di query SQL di Dataflow con parametri

Questa pagina spiega come eseguire query SQL Dataflow con parametri.

Dataflow SQL supporta parametri di ricerca denominati e posizionali. Specifica i parametri di query con la seguente sintassi:

Parametri denominati con il carattere @ seguito da un identificatore, come @param_name
Parametri posizionali con carattere ?

In una query puoi utilizzare parametri denominati o di posizionamento, ma non entrambi.

Esecuzione di query con parametri

Per eseguire una query con parametri, definisci il tipo di dati e il valore dei parametri di query. Il tipo e il valore dei parametri di ricerca devono corrispondere al tipo di oggetti di database che i parametri rappresentano.

Puoi definire parametri di ricerca utilizzando la console Google Cloud o Google Cloud CLI:

Console

Per definire parametri di ricerca, utilizza l'interfaccia utente SQL di Dataflow:

Vai all'interfaccia utente SQL di Dataflow.

Vai all'interfaccia utente SQL di Dataflow
Inserisci la query SQL di Dataflow nell'Editor query.

Ad esempio, la seguente query seleziona corse in taxi che costano almeno il prezzo specificato:
```
SELECT *
FROM pubsub.topic.`pubsub-public-data`.`taxirides-realtime`
WHERE
 ride_status = "dropoff"
 AND meter_reading >= @price_min
```
Fai clic su Crea job Cloud Dataflow per aprire un riquadro di opzioni per i job.
Nella sezione Parametri di query SQL del riquadro, compila i campi Nome, Tipo e Valore. Il nome del parametro nell'esempio è price_min e il tipo è FLOAT64.

Se il parametro è posizionale, ometti il campo Nome.
(Facoltativo) Se la query contiene più parametri, fai clic su Aggiungi parametro.

La console Google Cloud non supporta i parametri ARRAY o STRUCT. Per specificare i parametri ARRAY o STRUCT, utilizza Google Cloud CLI.

gcloud

Per definire parametri di ricerca, utilizza il comando gcloud dataflow sql query e i flag --parameter.

Puoi ripetere il flag --parameter per ogni parametro di ricerca. Imposta ogni flag --parameter su name:type:value.

Il seguente comando esegue una query con parametri su un flusso Pub/Sub di corse in 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'

Se il parametro è posizionale, imposta i flag --parameter su :type:value.

Utilizzare array nelle query con parametri

Per utilizzare un tipo di array in un parametro di ricerca, imposta il tipo su ARRAY<data-type>. Crea il valore come un elenco separato da virgole di elementi racchiusi tra parentesi quadre, ad esempio ["pickup", "enroute", "dropoff"].

Console

L'interfaccia utente SQL di Dataflow non supporta i parametri ARRAY nelle query SQL di Dataflow.

gcloud

Per definire un parametro dell'array, imposta il flag --parameter del comando gcloud dataflow sql query su name:ARRAY<data-type>:value

Il seguente comando esegue una query con un parametro array denominato su un flusso Pub/Sub di corse in 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)'

Per maggiori informazioni, consulta la pagina di riferimento di Dataflow SQL per i tipi di ARRAY.

Utilizzare i timestamp nelle query con parametri

Per utilizzare un timestamp in un parametro di ricerca, imposta il tipo su STRING, ma costruisci il valore nel formato timestamp canonico.

Console

Per definire i parametri dei timestamp, utilizza l'interfaccia utente SQL di Dataflow:

Vai all'interfaccia utente SQL di Dataflow.

Vai all'interfaccia utente SQL di Dataflow
Inserisci la query SQL di Dataflow nell'Editor query.

Ad esempio, la seguente query seleziona le corse di taxi che si sono verificate dopo la data specificata:
```
SELECT *
FROM pubsub.topic.`pubsub-public-data`.`taxirides-realtime`
WHERE
  event_timestamp >= TIMESTAMP (@date_min)
```
Fai clic su Crea job Cloud Dataflow per aprire un riquadro di opzioni per i job.
Nella sezione Parametri di query SQL, fai clic su Aggiungi parametro.
Nel campo Tipo, seleziona STRING.
Nel campo Valore, inserisci un timestamp.

gcloud

Per definire un parametro timestamp, imposta il flag --parameter del comando gcloud dataflow sql query su name:STRING:value

Il seguente comando esegue una query con un parametro timestamp denominato su un flusso Pub/Sub di corse in 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)'

Per saperne di più, consulta il riferimento SQL di Dataflow per i tipi di TIMESTAMP.

Utilizzo di struct nelle query con parametri

Per utilizzare uno struct in un parametro di query, imposta il tipo su STRUCT<field-name data-type, ...>. Crea il valore come un elenco separato da virgole di coppie chiave/valore.

Ad esempio, STRUCT<date_min TIMESTAMP, status STRING> definisce uno struct con un campo denominato date_min di tipo TIMESTAMP e un campo denominato status di tipo STRING.

Console

L'interfaccia utente SQL di Dataflow non supporta i parametri STRUCT nelle query SQL di Dataflow.

gcloud

Per definire un parametro dell'array, imposta il flag --parameter del comando gcloud dataflow sql query su name:STRUCT<field-name data-type, ...>:value

Il seguente comando esegue una query con un parametro struct denominato su un flusso Pub/Sub di corse in 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'

Per saperne di più, consulta il riferimento SQL di Dataflow per i tipi di STRUCT.