使用參數化 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 控制台不支援 ARRAYSTRUCT 參數。如要指定 ARRAYSTRUCT 參數,請使用 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 參考資料。