Utilizzo di query Dataflow SQL con parametri

Questa pagina spiega come eseguire query SQL di 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, ad esempio @param_name
  • Parametri posizionali con il carattere ?

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

Esecuzione di query con parametri

Per eseguire una query con parametri, definisci il tipo di dati e il valore dei parametri della query. Il tipo e il valore dei parametri di ricerca devono corrispondere al tipo degli oggetti del database rappresentati dai parametri.

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

Console

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

  1. Vai all'interfaccia utente di Dataflow SQL.

    Vai all'interfaccia utente di Dataflow SQL

  2. Inserisci la query SQL di Dataflow nell'editor delle query.

    Ad esempio, la seguente query seleziona le 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

  3. Fai clic su Crea job Cloud Dataflow per aprire un riquadro di opzioni per i job.

  4. 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.

  5. (Facoltativo) Se la query contiene altri 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 query. Imposta ogni --parameter su name:type:value.

Il seguente comando esegue una query con parametri su uno stream 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.

Utilizzo di array nelle query con parametri

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

Console

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

gcloud

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

Il seguente comando esegue una query con un parametro array denominato su uno stream 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 ulteriori informazioni, consulta il riferimento di Dataflow SQL per i tipi ARRAY.

Utilizzo dei timestamp nelle query con parametri

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

Console

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

  1. Vai all'interfaccia utente di Dataflow SQL.

    Vai all'interfaccia utente di Dataflow SQL

  2. Inserisci la query SQL di Dataflow nell'editor delle query.

    Ad esempio, la seguente query seleziona le corse in taxi avvenute dopo la data specificata:

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

  3. Fai clic su Crea job Cloud Dataflow per aprire un riquadro di opzioni per i job.

  4. Nella sezione Parametri di query SQL, fai clic su Aggiungi parametro.

  5. Nel campo Tipo, seleziona STRING.

  6. Nel campo Valore, inserisci un timestamp.

gcloud

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

Il seguente comando esegue una query con un parametro timestamp denominato su uno stream 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 ulteriori informazioni, consulta la documentazione di riferimento di Dataflow SQL per i tipi TIMESTAMP.

Utilizzo di struct nelle query con parametri

Per utilizzare una struttura in un parametro di query, imposta il tipo su STRUCT<field-name data-type, ...>. Costruisci il valore come elenco di coppie chiave-valore separate da virgole.

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

Console

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

gcloud

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

Il seguente comando esegue una query con un parametro struct denominato su uno stream 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 ulteriori informazioni, consulta la documentazione di riferimento di Dataflow SQL per i tipi STRUCT.