使用參數化 Dataflow SQL 查詢

本頁說明如何執行參數化 Dataflow SQL 查詢。

Dataflow SQL 支援具名和位置查詢參數。使用下列語法指定查詢參數：

  • 具名參數，開頭為 @ 字元，後面加上 ID，例如 @param_name
  • 使用 ? 字元的位置參數

查詢中可以使用具名或位置參數，但不得同時使用兩者。

執行參數化查詢

如要執行參數化查詢，請定義查詢參數的資料類型和值。查詢參數的類型和值必須與參數代表的資料庫物件類型相符。

您可以使用 Google Cloud 控制台或 Google Cloud CLI 定義查詢參數：

控制台

如要定義查詢參數，請使用 Dataflow SQL UI：

  1. 前往 Dataflow SQL UI。

    前往 Dataflow SQL UI

  2. 在查詢編輯器中輸入 Dataflow SQL 查詢。

    舉例來說，下列查詢會選取車資至少為指定價格的計程車行程：

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

  3. 按一下「Create Cloud Dataflow job」(建立 Cloud Dataflow 工作)，開啟工作選項面板。

  4. 在面板的「SQL query parameters」(SQL 查詢參數) 區段中，填入「Name」(名稱)、「Type」(類型) 和「Value」(值) 欄位。範例中的參數名稱為 price_min，類型為 FLOAT64。

    如果參數是位置參數，請省略「名稱」欄位。

  5. (選用) 如果查詢包含更多參數，請按一下「新增參數」。

Google Cloud 控制台不支援 ARRAY 或 STRUCT 參數。如要指定 ARRAY 或 STRUCT 參數，請使用 Google Cloud CLI。

gcloud

如要定義查詢參數，請使用 gcloud dataflow sql query 指令和 --parameter 標記。

您可以針對每個查詢參數重複使用 --parameter 旗標。將每個 --parameter 標記設為 name:type:value。

下列指令會對計程車行程的 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'

如果參數是位置參數，請將 --parameter 標記設為 :type:value。

在參數化查詢中使用陣列

如要在查詢參數中使用陣列類型，請將類型設為 ARRAY<data-type>。 請將值建構為以方括號括住的元素清單，其中的元素以逗號分隔，例如 ["pickup", "enroute", "dropoff"]。

控制台

Dataflow SQL UI 不支援 Dataflow SQL 查詢中的 ARRAY 參數。

gcloud

如要定義陣列參數，請將 gcloud dataflow sql query 指令的 --parameter 標記設為 name:ARRAY<data-type>:value。

下列指令會在計程車行程的 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)'

詳情請參閱 Dataflow SQL 參考資料的ARRAY類型。

在參數化查詢中使用時間戳記

如要在查詢參數中使用時間戳記，請將類型設為 STRING，但請以標準時間戳記格式建構值。

控制台

如要定義時間戳記參數，請使用 Dataflow SQL UI：

  1. 前往 Dataflow SQL UI。

    前往 Dataflow SQL UI

  2. 在查詢編輯器中輸入 Dataflow SQL 查詢。

    舉例來說，下列查詢會選取指定日期之後發生的計程車行程：

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

  3. 按一下「Create Cloud Dataflow job」(建立 Cloud Dataflow 工作)，開啟工作選項面板。

  4. 在「SQL query parameters」(SQL 查詢參數) 區段中，按一下「Add parameter」(新增參數)。

  5. 在「類型」欄位中，選取「STRING」。

  6. 在「Value」(值) 欄位中，輸入時間戳記。

gcloud

如要定義時間戳記參數，請將 gcloud dataflow sql query 指令的 --parameter 旗標設為 name:STRING:value。

下列指令會在計程車行程的 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)'

詳情請參閱 TIMESTAMP 類型的 Dataflow SQL 參考資料。

在參數化查詢中使用結構

如要在查詢參數中使用結構，請將類型設為 STRUCT<field-name data-type, ...>。 將值建構為以半形逗號分隔的鍵/值組合清單。

舉例來說，STRUCT<date_min TIMESTAMP, status STRING> 會利用名為 date_min 且類型為 TIMESTAMP 的欄位，以及名為 status 且類型為 STRING 的欄位來定義結構。

控制台

Dataflow SQL UI 不支援 Dataflow SQL 查詢中的 STRUCT 參數。

gcloud

如要定義陣列參數，請將 gcloud dataflow sql query 指令的 --parameter 標記設為 name:STRUCT<field-name data-type, ...>:value。

下列指令會在計程車行程的 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'

詳情請參閱 STRUCT 類型的 Dataflow SQL 參考資料。