本頁說明如何執行參數化 Dataflow SQL 查詢。
Dataflow SQL 支援具名和位置查詢參數。使用下列語法指定查詢參數:
- 具名參數,開頭為
@
字元,後面加上 ID,例如@param_name
- 使用
?
字元的位置參數
查詢中可以使用具名或位置參數,但不得同時使用兩者。
執行參數化查詢
如要執行參數化查詢,請定義查詢參數的資料類型和值。查詢參數的類型和值必須與參數代表的資料庫物件類型相符。
您可以使用 Google Cloud 控制台或 Google Cloud CLI 定義查詢參數:
控制台
如要定義查詢參數,請使用 Dataflow SQL UI:
前往 Dataflow SQL UI。
在查詢編輯器中輸入 Dataflow SQL 查詢。
舉例來說,下列查詢會選取車資至少為指定價格的計程車行程:
SELECT * FROM pubsub.topic.`pubsub-public-data`.`taxirides-realtime` WHERE ride_status = "dropoff" AND meter_reading >= @price_min
按一下「Create Cloud Dataflow job」(建立 Cloud Dataflow 工作),開啟工作選項面板。
在面板的「SQL query parameters」(SQL 查詢參數) 區段中,填入「Name」(名稱)、「Type」(類型) 和「Value」(值) 欄位。範例中的參數名稱為
price_min
,類型為FLOAT64
。如果參數是位置參數,請省略「名稱」欄位。
(選用) 如果查詢包含更多參數,請按一下「新增參數」。
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:
前往 Dataflow SQL UI。
在查詢編輯器中輸入 Dataflow SQL 查詢。
舉例來說,下列查詢會選取指定日期之後發生的計程車行程:
SELECT * FROM pubsub.topic.`pubsub-public-data`.`taxirides-realtime` WHERE event_timestamp >= TIMESTAMP (@date_min)
按一下「Create Cloud Dataflow job」(建立 Cloud Dataflow 工作),開啟工作選項面板。
在「SQL query parameters」(SQL 查詢參數) 區段中,按一下「Add parameter」(新增參數)。
在「類型」欄位中,選取「
STRING
」。在「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 參考資料。