Menggunakan kueri Dataflow SQL berparameter

Halaman ini menjelaskan cara menjalankan kueri SQL Dataflow berparameter.

Dataflow SQL mendukung parameter kueri bernama dan posisi. Tentukan parameter kueri dengan sintaksis berikut:

Parameter bernama dengan karakter @ yang diikuti dengan ID, seperti @param_name
Parameter posisi dengan karakter ?

Anda dapat menggunakan parameter bernama atau posisi dalam kueri, tetapi tidak keduanya.

Menjalankan kueri berparameter

Untuk menjalankan kueri berparameter, tentukan jenis data dan nilai parameter kueri. Jenis dan nilai parameter kueri harus cocok dengan jenis objek database yang diwakili parameter tersebut.

Anda dapat menentukan parameter kueri menggunakan Google Cloud Console atau Google Cloud CLI:

Konsol

Untuk menentukan parameter kueri, gunakan UI Dataflow SQL:

Buka UI Dataflow SQL.

Buka UI Dataflow SQL
Masukkan kueri Dataflow SQL ke dalam editor kueri.

Misalnya, kueri berikut memilih perjalanan dengan taksi yang setidaknya memiliki harga yang ditentukan:
```
SELECT *
FROM pubsub.topic.`pubsub-public-data`.`taxirides-realtime`
WHERE
 ride_status = "dropoff"
 AND meter_reading >= @price_min
```
Klik Buat tugas Cloud Dataflow untuk membuka panel opsi tugas.
Di bagian Parameter kueri SQL pada panel, isi kolom Name, Type, dan Value. Nama parameter dalam contoh adalah price_min dan jenisnya adalah FLOAT64.

Jika parameter bersifat posisi, hapus kolom Name.
(Opsional) Jika kueri berisi lebih banyak parameter, klik Tambahkan parameter.

Konsol Google Cloud tidak mendukung parameter ARRAY atau STRUCT. Untuk menentukan parameter ARRAY atau STRUCT, gunakan Google Cloud CLI.

gcloud

Untuk menentukan parameter kueri, gunakan perintah gcloud dataflow sql query dan flag --parameter.

Anda dapat mengulangi flag --parameter untuk setiap parameter kueri. Tetapkan setiap flag --parameter ke name:type:value.

Perintah berikut menjalankan kueri berparameter pada aliran Pub/Sub perjalanan taksi:

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'

Jika parameter bersifat posisi, tetapkan flag --parameter ke :type:value.

Menggunakan array dalam kueri berparameter

Untuk menggunakan jenis array dalam parameter kueri, tetapkan jenis ke ARRAY<data-type>. Buat nilai sebagai daftar elemen yang dipisahkan koma dan diapit dalam tanda kurung siku, seperti ["pickup", "enroute", "dropoff"].

Konsol

UI Dataflow SQL tidak mendukung parameter ARRAY dalam kueri Dataflow SQL.

gcloud

Untuk menentukan parameter array, tetapkan flag --parameter dari perintah gcloud dataflow sql query ke name:ARRAY<data-type>:value

Perintah berikut menjalankan kueri dengan parameter array bernama di streaming perjalanan taksi di Pub/Sub:

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)'

Untuk mengetahui informasi selengkapnya, lihat referensi Dataflow SQL untuk jenis ARRAY.

Menggunakan stempel waktu dalam kueri berparameter

Untuk menggunakan stempel waktu dalam parameter kueri, tetapkan jenis ke STRING, tetapi buat nilai dalam format stempel waktu kanonis.

Konsol

Untuk menentukan parameter stempel waktu, gunakan UI Dataflow SQL:

Buka UI Dataflow SQL.

Buka UI Dataflow SQL
Masukkan kueri Dataflow SQL ke dalam editor kueri.

Misalnya, kueri berikut memilih perjalanan dengan taksi yang terjadi setelah tanggal yang ditentukan:
```
SELECT *
FROM pubsub.topic.`pubsub-public-data`.`taxirides-realtime`
WHERE
  event_timestamp >= TIMESTAMP (@date_min)
```
Klik Buat tugas Cloud Dataflow untuk membuka panel opsi tugas.
Di bagian Parameter kueri SQL, klik Tambahkan parameter.
Di kolom Type, pilih STRING.
Di kolom Nilai, masukkan stempel waktu.

gcloud

Untuk menentukan parameter stempel waktu, tetapkan flag --parameter dari perintah gcloud dataflow sql query ke name:STRING:value

Perintah berikut menjalankan kueri dengan parameter stempel waktu yang diberi nama di aliran perjalanan taksi Pub/Sub:

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)'

Untuk mengetahui informasi selengkapnya, lihat referensi Dataflow SQL untuk jenis TIMESTAMP.

Menggunakan struct dalam kueri berparameter

Untuk menggunakan struct dalam parameter kueri, setel jenis ke STRUCT<field-name data-type, ...>. Buat nilai sebagai daftar key-value pair yang dipisahkan koma.

Misalnya, STRUCT<date_min TIMESTAMP, status STRING> menentukan struct dengan kolom bernama date_min dari jenis TIMESTAMP dan kolom bernama status dari jenis STRING.

Konsol

UI Dataflow SQL tidak mendukung parameter STRUCT dalam kueri Dataflow SQL.

gcloud

Untuk menentukan parameter array, tetapkan flag --parameter dari perintah gcloud dataflow sql query ke name:STRUCT<field-name data-type, ...>:value

Perintah berikut menjalankan kueri dengan parameter struct bernama di aliran perjalanan taksi di Pub/Sub:

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'

Untuk mengetahui informasi selengkapnya, lihat referensi Dataflow SQL untuk jenis STRUCT.