Utilizzo di query Dataflow SQL con parametri

Questa pagina spiega come eseguire query Dataflow SQL parametrizzate.

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

  • Parametri denominati con il carattere @ seguito da un identificatore, ad esempio @param_name
  • Parametri posizionali con il carattere ?

Puoi utilizzare parametri denominati o posizionali in una query, 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 di database che 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 di Dataflow SQL:

  1. Vai all'interfaccia utente di Dataflow SQL.

    Vai all'interfaccia utente di Dataflow SQL

  2. Inserisci la query Dataflow SQL nell'editor di 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 del job.

  4. Nella sezione Parametri 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 Google Cloud console 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 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.

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 un elenco separato da virgole di elementi racchiusi tra parentesi quadre, ad esempio ["pickup", "enroute", "dropoff"].

Console

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

gcloud

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

Il comando seguente esegue la 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 saperne di più, consulta il riferimento SQL di Dataflow 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 crea 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 Dataflow SQL nell'editor di 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 del job.

  4. Nella sezione Parametri 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 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 a Dataflow SQL per i tipi TIMESTAMP.

Utilizzo di struct nelle query con parametri

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

Ad esempio, STRUCT<date_min TIMESTAMP, status STRING> definisce una struct 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 Dataflow SQL.

gcloud

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

Il seguente comando esegue la 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 a Dataflow SQL per i tipi STRUCT.