Menggunakan kueri Dataflow SQL berparameter

Halaman ini menjelaskan cara menjalankan kueri Dataflow SQL yang diberi parameter.

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

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

Anda dapat menggunakan parameter bernama atau parameter 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 oleh parameter.

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

Konsol

Untuk menentukan parameter kueri, gunakan UI Dataflow SQL:

  1. Buka UI Dataflow SQL.

    Buka UI Dataflow SQL

  2. Masukkan kueri Dataflow SQL ke editor kueri.

    Misalnya, kueri berikut memilih perjalanan taksi yang harganya minimal harga yang ditentukan:

    SELECT *
FROM pubsub.topic.`pubsub-public-data`.`taxirides-realtime`
WHERE
 ride_status = "dropoff"
 AND meter_reading >= @price_min

  3. Klik Create Cloud Dataflow job untuk membuka panel opsi tugas.

  4. Di bagian SQL query parameters pada panel, isi kolom Name, Type, dan Value. Nama parameter dalam contoh adalah price_min dan jenisnya adalah FLOAT64.

    Jika parameter bersifat posisional, hapus kolom Name.

  5. (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 tanda --parameter untuk setiap parameter kueri. Tetapkan setiap --parameter flag ke name:type:value.

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

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 posisional, tetapkan tanda --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 yang 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 tanda --parameter dari perintah gcloud dataflow sql query ke name:ARRAY<data-type>:value

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

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:

  1. Buka UI Dataflow SQL.

    Buka UI Dataflow SQL

  2. Masukkan kueri Dataflow SQL ke editor kueri.

    Misalnya, kueri berikut memilih perjalanan taksi yang terjadi setelah tanggal yang ditentukan:

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

  3. Klik Create Cloud Dataflow job untuk membuka panel opsi tugas.

  4. Di bagian Parameter kueri SQL, klik Tambahkan parameter.

  5. Di kolom Type, pilih STRING.

  6. Di kolom Nilai, masukkan stempel waktu.

gcloud

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

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

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, tetapkan jenis ke STRUCT<field-name data-type, ...>. Buat nilai sebagai daftar pasangan nilai kunci 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 tanda --parameter dari perintah gcloud dataflow sql query ke name:STRUCT<field-name data-type, ...>:value

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

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.