使用参数化 Dataflow SQL 查询

本页介绍如何运行参数化 Dataflow SQL 查询

Dataflow SQL 支持命名和位置查询参数。使用以下语法指定查询参数:

  • 命名参数包含 @ 字符,后跟一个标识符,例如 @param_name
  • 位置参数包含 ? 字符

您可以在查询中使用命名参数或位置参数,但不能同时使用这两者。

运行参数化查询

如需运行参数化查询,请定义查询参数的数据类型和值。查询参数的类型和值必须与参数所表示的数据库对象的类型相匹配。

您可以使用 Cloud Console 或 gcloud 命令行工具定义查询参数:

Console

如需定义查询参数,请使用 Dataflow SQL 界面:

  1. 转到 Dataflow SQL 界面。

    转到 Dataflow SQL 界面

  2. 在查询编辑器中输入 Dataflow SQL 查询。

    例如,以下查询选择费用至少为指定价格的出租车行程:

    SELECT *
    FROM pubsub.topic.`pubsub-public-data`.`taxirides-realtime`
    WHERE
     ride_status = "dropoff"
     AND meter_reading >= @price_min
    
  3. 点击创建 Cloud Dataflow 作业,打开作业选项面板。

  4. 在该面板的 SQL 查询参数部分,填写名称类型字段。示例中的参数名称为 price_min,类型为 FLOAT64

    如果参数为位置参数,则省略名称字段。

  5. (可选)如果查询包含更多参数,请点击添加参数

Cloud Console 不支持 ARRAYSTRUCT 参数。如需指定 ARRAYSTRUCT 参数,请使用 gcloud 命令行工具。

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"]

Console

Dataflow SQL 界面不支持在 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)'

如需了解详情,请参阅 ARRAY 类型的 Dataflow SQL 参考。

在参数化查询中使用时间戳

如需在查询参数中使用时间戳,请将类型设置为 STRING,但以规范时间戳格式构造值。

Console

如需定义时间戳参数,请使用 Dataflow SQL 界面:

  1. 转到 Dataflow SQL 界面。

    转到 Dataflow SQL 界面

  2. 在查询编辑器中输入 Dataflow SQL 查询。

    例如,以下查询会选择在指定日期之后发生的出租车行程:

    SELECT *
    FROM pubsub.topic.`pubsub-public-data`.`taxirides-realtime`
    WHERE
      event_timestamp >= TIMESTAMP (@date_min)
    
  3. 点击创建 Cloud Dataflow 作业,打开作业选项面板。

  4. SQL 查询参数部分,点击添加参数

  5. 类型字段中,选择 STRING

  6. 字段中,输入时间戳。

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

Console

Dataflow SQL 界面不支持在 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 参考。