使用参数化 Dataflow SQL 查询

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

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

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

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

运行参数化查询

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

您可以使用 Google Cloud 控制台或 Google Cloud CLI 来定义查询参数：

控制台

如需定义查询参数，请使用 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. （可选）如果查询包含更多参数，请点击添加参数。

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 界面不支持在 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，但以规范时间戳格式构造值。

控制台

如需定义时间戳参数，请使用 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。

控制台

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 参考。