Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 中国的 Amazon Web Services 服务入门 (PDF)。

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

场景发现查询语言参考

查询工作流程

场景发现使用具有三个 API 操作的异步查询模型：

您还可以使用CancelQuery取消正在运行的查询，以及列ListQueries出工作空间的查询。

工作流示例

# 1. Start a query
aws iotsitewise start-query \
  --region $REGION \
  --workspace-name "my-workspace" \
  --query-statement "SELECT * FROM raw_time_series LIMIT 10"
# Response: { "queryId": "abc-123", "status": "SUBMITTED" }

# 2. Poll for completion
aws iotsitewise describe-query \
  --region $REGION \
  --workspace-name "my-workspace" \
  --query-id "abc-123"
# Response: { "queryId": "abc-123", "status": "COMPLETED", ... }

# 3. Get results (paginated)
aws iotsitewise get-query-results \
  --region $REGION \
  --workspace-name "my-workspace" \
  --query-id "abc-123" \
  --max-results 10000
# Response: { "columnInfo": [...], "rows": [...], "nextToken": "..." }

查询限制

查询状态

参考表

场景发现在每个工作空间内提供四个可查询的表。所有查询的范围都限于StartQuery请求中指定的工作空间。

raw_time_series

包含采集到工作空间的带时间戳的遥测数据。

annotations

包含与视频或传感器流相关的 OpenLabel 注释数据。每行对应于单个视频帧的注释数据。

数据集

包含有关工作空间中数据集的元数据。

数据段

包含有关数据集内数据段（时间序列引用）的元数据。

支持的数据类型

时间戳格式：

TIMESTAMP '2025-12-21 23:59:58.123'
TIMESTAMP '2025-12-21 23:59:58'
TIMESTAMP '2025-12-21'

支持的 SQL 子句

SELECT expression [, ...]
  [ FROM table_name [AS alias] [, ...] ]
  [ WHERE condition ]
  [ GROUP BY expression [, ...] ]
  [ HAVING condition ]
  [ ORDER BY expression [ ASC | DESC ] [ NULLS FIRST | NULLS LAST ] [, ...] ]
  [ LIMIT count ]

变体函数和点表示法

场景发现支持两种处理变体列（半结构化 JSON 数据）的方法。

点符号（推荐用于简单访问）

使用点表示法直接访问变体列上的嵌套字段：

-- Access nested struct fields
SELECT t.struct_value.observation.state.max_speed
FROM raw_time_series t
LIMIT 10

-- Filter on nested values
SELECT DISTINCT t.dataset_id, t.series_id, t.event_timestamp
FROM raw_time_series t
WHERE CAST(t.struct_value.observation.state.max_speed AS INT) > 0

-- Access annotation context fields
SELECT a.contexts.road_type, a.contexts.weather
FROM annotations a
LIMIT 10

变体提取

通过键名从变体对象中提取值。返回一个你可以进一步访问或施放的变体。

签名：variant_extract(variant_expr, key)

SELECT
    variant_extract(obj, 'object_type'),
    variant_extract(obj, 'object_name'),
    variant_extract_nested(obj, 'attributes.confidence')
FROM annotations a,
UNNEST(CAST(a.objects AS VARIANT ARRAY)) AS t(obj)
WHERE a.dataset_id = 'my-dataset-id'
LIMIT 50

变体提取嵌套

使用以点分隔的路径字符串提取嵌套值。第二个参数必须是字符串文字。

签名：variant_extract_nested(variant_expr, 'dotted.path.key')

SELECT
    variant_extract(obj, 'object_type'),
    variant_extract_nested(obj, 'attributes.confidence')
FROM annotations a,
UNNEST(CAST(a.objects AS VARIANT ARRAY)) AS t(obj)
WHERE a.dataset_id = 'my-dataset-id'
    AND CAST(variant_extract_nested(obj, 'attributes.confidence') AS DOUBLE) >= 0.7
LIMIT 50

to_json

将变体值转换为 JSON 字符串。

签名：to_json(variant_expr)

SELECT to_json(a.objects) FROM annotations a LIMIT 5

UNNEST 用于阵列

使用 UNNEST 将 VARIANT 数组扩展为行：

SELECT
    a.dataset_id,
    a.series_id,
    a.frame_id,
    a.event_timestamp,
    variant_extract(obj, 'object_type'),
    variant_extract(obj, 'object_name'),
    variant_extract_nested(obj, 'attributes.confidence')
FROM annotations a,
UNNEST(CAST(a.objects AS VARIANT ARRAY)) AS t(obj)
WHERE a.dataset_id = 'my-dataset-id'
    AND CAST(variant_extract_nested(obj, 'attributes.confidence') AS DOUBLE) >= 0.7
ORDER BY a.dataset_id
LIMIT 50

运算符和函数

逻辑运算符

比较运算符

聚合函数

类型转换

示例查询

基本遥测查询

列出所有遥测数据（有限）：

SELECT * FROM raw_time_series LIMIT 10

按时间范围筛选：

SELECT alias, event_timestamp, double_value
FROM raw_time_series
WHERE event_timestamp > TIMESTAMP '2025-01-01 00:00:00'
  AND event_timestamp < TIMESTAMP '2025-01-02 00:00:00'
LIMIT 100

汇总遥测值：

SELECT
    alias,
    COUNT(*) AS data_points,
    AVG(double_value) AS avg_value,
    MAX(double_value) AS max_value,
    MIN(double_value) AS min_value
FROM raw_time_series
GROUP BY alias
ORDER BY data_points DESC

使用点表示法查询结构遥测：

SELECT DISTINCT t.dataset_id, t.series_id, t.event_timestamp
FROM raw_time_series t
WHERE CAST(t.struct_value.observation.state.max_speed AS INT) > 0

注释查询

列出数据集的注释：

SELECT dataset_id, series_id, frame_id, event_timestamp
FROM annotations
WHERE dataset_id = 'my-dataset-id'
ORDER BY event_timestamp
LIMIT 100

通过放心过滤提取检测到的对象：

SELECT
    a.dataset_id,
    a.series_id,
    a.frame_id,
    a.event_timestamp,
    variant_extract(obj, 'object_type'),
    variant_extract(obj, 'object_name'),
    variant_extract_nested(obj, 'attributes.confidence')
FROM annotations a,
UNNEST(CAST(a.objects AS VARIANT ARRAY)) AS t(obj)
WHERE a.dataset_id = 'my-dataset-id'
    AND CAST(variant_extract_nested(obj, 'attributes.confidence') AS DOUBLE) >= 0.7
ORDER BY a.event_timestamp
LIMIT 50

使用点表示法查询注释上下文：

SELECT
    a.dataset_id,
    a.frame_id,
    a.contexts.road_type,
    a.contexts.weather,
    a.contexts.time_of_day
FROM annotations a
WHERE a.dataset_id = 'my-dataset-id'
LIMIT 100

数据集和数据段查询

列出所有数据集：

SELECT dataset_id, name, dataset_type, version, created_at
FROM dataset
ORDER BY created_at DESC

列出数据集的数据段：

SELECT source_dataset_id, dataset_id, timeseries_id, alias, data_type, start_time, end_time
FROM datasegment
WHERE dataset_id = 'my-dataset-id'

按类型对数据段进行计数：

SELECT data_type, COUNT(*) AS segment_count
FROM datasegment
GROUP BY data_type

Cross-table 查询

查找特定数据集分段的遥测数据：

SELECT t.alias, t.event_timestamp, t.double_value
FROM raw_time_series t, datasegment ds
WHERE t.dataset_id = ds.dataset_id
  AND t.series_id = ds.timeseries_id
  AND ds.data_type = 'JSON'
LIMIT 100

问题排查

ValidationException 上 StartQuery

查询停滞在运行中

ResourceNotFoundException 上 GetQueryResults

查询返回失败

结果为空

分页速度慢