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

# 场景发现查询语言参考
<a name="sd-query-language"></a>

## 查询工作流程
<a name="sd-query-workflow"></a>

场景发现使用具有三个 API 操作的异步查询模型：
+ **StartQuery**— 针对工作空间提交 SQL 查询。返回 a `queryId` 和初始状态`SUBMITTED`。
+ **DescribeQuery**— 使用轮询查询状态`queryId`。状态通过以下方式发展：`SUBMITTED``RUNNING`→`COMPLETED`（或`FAILED`/`CANCELING`/`CANCELED`）。
+ **GetQueryResults**— 查询完成后检索列元数据和分页结果行。`COMPLETED`设置`maxResults`为 10,000 以获得最佳性能。

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

### 工作流示例
<a name="sd-query-workflow-example"></a>

```
# 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": "..." }
```

## 查询限制
<a name="sd-query-constraints"></a>


| 参数 | 约束 | 
| --- | --- | 
| workspaceName | 1—64 个字符，图案 ^[a-zA-Z0-9\_-]\+$ | 
| queryStatement | 1—10,240 个字符 | 
| clientToken | 36—64 个字符（可选，用于熵等性） | 
| maxResults | 的分页页面大小 GetQueryResults （推荐：10,000） | 

## 查询状态
<a name="sd-query-statuses"></a>


| Status | 说明 | 
| --- | --- | 
| SUBMITTED | 查询已接受，正在等待执行 | 
| RUNNING | 查询正在执行 | 
| COMPLETED | 查询成功完成-结果可用 | 
| FAILED | 查询失败-检查错误消息 | 
| CANCELED | 用户取消了查询 | 
| CANCELING | 已收到取消请求，查询正在停止 | 

## 参考表
<a name="sd-query-reference-tables"></a>

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

### raw\_time\_series
<a name="sd-query-table-raw-time-series"></a>

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


| 列 | 数据类型 | 描述 | 
| --- | --- | --- | 
| dataset\_id | string | 包含此数据的数据集的 ID | 
| series\_id | string | 时间序列 ID (UUID) | 
| alias | string | 属性别名路径（例如，/sensor/temperature） | 
| event\_timestamp | TIMESTAMP | 数据点的时间戳 | 
| nanosecond\_offset | INTEGER | Sub-microsecond 以纳秒为单位的偏移量 | 
| version | INTEGER | 数据版本号 | 
| data\_type | string | 值类型（例如，JSON、DOUBLE、STRING） | 
| string\_value | string | 字符串值（当 data\_type 为 STRING 时） | 
| long\_value | BIGINT | 长整数值 | 
| double\_value | DOUBLE | 双精度浮点值 | 
| boolean\_value | BOOLEAN | 布尔值 | 
| binary\_value | BINARY | 二进制值 | 
| array\_value | 变体 | 数组值（半结构化数据） | 
| struct\_value | 变体 | Struct/object 价值（半结构化数据） | 

### annotations
<a name="sd-query-table-annotations"></a>

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


| 列 | 数据类型 | 描述 | 
| --- | --- | --- | 
| dataset\_id | string | 包含此注解的数据集的 ID | 
| series\_id | string | 时间序列 ID (UUID) | 
| alias | string | 属性别名路径（例如，/annotations/front\_left） | 
| event\_timestamp | TIMESTAMP | 注释帧的时间戳 | 
| nanosecond\_offset | INTEGER | Sub-microsecond 以纳秒为单位的偏移量 | 
| frame\_id | string | 帧标识符 | 
| openlabel\_version | string | OpenLabel 架构版本 | 
| streams | 变体 | 流元数据（半结构化） | 
| objects | 变体 | 检测到的具有边界框、类型和属性的对象（半结构化） | 
| contexts | 变体 | 场景上下文信息（半结构化） | 
| updated\_at | TIMESTAMP | 上次更新时间戳 | 

### 数据集
<a name="sd-query-table-dataset"></a>

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


| 列 | 数据类型 | 描述 | 
| --- | --- | --- | 
| dataset\_id | string | 数据集 ID (UUID) | 
| dataset\_external\_id | string | 外部标识符 | 
| dataset\_type | string | 数据集类型（例如 SESSION、CURATED） | 
| dataset\_payload | 变体 | 数据集配置负载（半结构化） | 
| dataset\_source | string | 数据集源类型 | 
| name | string | 数据集名称 | 
| description | string | 数据集描述 | 
| version | INTEGER | 数据集版本号 | 
| created\_at | TIMESTAMP | 创建时间戳 | 
| updated\_at | TIMESTAMP | 上次更新时间戳 | 
| metadata | 变体 | User-defined 元数据键值对 | 

### 数据段
<a name="sd-query-table-datasegment"></a>

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


| 列 | 数据类型 | 描述 | 
| --- | --- | --- | 
| source\_dataset\_id | string | 源 SESSION 数据集的 ID | 
| dataset\_id | string | 此分段所属数据集的 ID | 
| timeseries\_id | string | 时间序列 ID (UUID) | 
| start\_time | TIMESTAMP | 分段开始时间戳 | 
| end\_time | TIMESTAMP | 分段结束时间戳 | 
| alias | string | 属性别名路径 | 
| data\_type | string | 数据类型（例如，视频、注解、JSON） | 
| start\_time\_nanosecond\_offset | INTEGER | Sub-microsecond 以纳秒为单位的偏移量 | 
| end\_time\_nanosecond\_offset | INTEGER | Sub-microsecond 以纳秒为单位的偏移量 | 

## 支持的数据类型
<a name="sd-query-data-types"></a>


| 数据类型 | 描述 | 
| --- | --- | 
| string | 最大长度为 1024 字节的字符串 | 
| INTEGER | 带符号的 32 位整数 | 
| BIGINT | 带符号的 64 位整数 | 
| DOUBLE | IEEE 754 双精度浮点运算 | 
| BOOLEAN | true 或 false | 
| TIMESTAMP | ISO-8601 兼容的时间戳 | 
| 变体 | Semi-structured 数据（JSON 对象、数组）。使用变体函数或点表示法提取值 | 
| MAP | Key-value 对 | 

时间戳格式：

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

## 支持的 SQL 子句
<a name="sd-query-sql-clauses"></a>

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


| 子句 | 说明 | 
| --- | --- | 
| SELECT | 要返回的列或表达式 | 
| FROM | 要查询的表。支持逗号分隔的表和显式 JOIN | 
| WHERE | 筛选条件 | 
| GROUP BY | 对行进行分组以进行聚合 | 
| HAVING | 聚合后筛选群组 | 
| ORDER BY | 对结果进行排序。使用 ASC 或 DESC，可选 NULLS FIRST FIRST/NULLS LAST | 
| LIMIT | 限制结果数（0 到 2,147,483,647） | 
| 加入/内部连接 | 合并多个表中的行 | 
| 联盟/联盟全部 | 合并来自多个查询的结果 | 
| 子选择 | 在 WHERE 或 FROM 内嵌套选择 | 

## 变体函数和点表示法
<a name="sd-query-variant-functions"></a>

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

### 点符号（推荐用于简单访问）
<a name="sd-query-dot-notation"></a>

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

```
-- 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
```

### 变体提取
<a name="sd-query-variant-extract"></a>

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

签名：`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
```

### 变体提取嵌套
<a name="sd-query-variant-extract-nested"></a>

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

签名：`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
<a name="sd-query-to-json"></a>

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

签名：`to_json(variant_expr)`

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

### UNNEST 用于阵列
<a name="sd-query-unnest"></a>

使用 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
```

## 运算符和函数
<a name="sd-query-operators-functions"></a>

### 逻辑运算符
<a name="sd-query-logical-operators"></a>


| 运算符 | 说明 | 
| --- | --- | 
| AND | 这两个条件都必须成立 | 
| 或 | 任一条件都必须为真 | 
| NOT | 否定条件 | 

### 比较运算符
<a name="sd-query-comparison-operators"></a>


| 运算符 | 说明 | 
| --- | --- | 
| = | 等于 | 
| <> 或 \!= | 不等于 | 
| < | Less than | 
| > | Greater than | 
| <= | 小于或等于 | 
| >= | 大于或等于 | 
| BETWEEN | 在一定范围内（包括） | 
| IN | 匹配列表中的任何值 | 
| LIKE | 使用% 和 \_ 通配符进行模式匹配 | 
| 为空/不为空 | 空支票 | 

### 聚合函数
<a name="sd-query-aggregate-functions"></a>


| 函数 | 说明 | 
| --- | --- | 
| 计数 (\*) /计数 (expr) | 计算行数 | 
| SUM（expr） | 值的总和 | 
| 平均值（expr） | 平均值 | 
| 最小值（过期） | 最小值 | 
| 最大值（expr） | 最大值 | 

### 类型转换
<a name="sd-query-type-conversion"></a>


| 函数 | 说明 | 
| --- | --- | 
| CAST（expr AS 类型） | 将值转换为指定类型 | 

## 示例查询
<a name="sd-query-examples"></a>

### 基本遥测查询
<a name="sd-query-examples-telemetry"></a>

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

```
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
```

### 注释查询
<a name="sd-query-examples-annotations"></a>

列出数据集的注释：

```
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
```

### 数据集和数据段查询
<a name="sd-query-examples-datasets"></a>

列出所有数据集：

```
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 查询
<a name="sd-query-examples-cross-table"></a>

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

```
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
```

## 问题排查
<a name="sd-query-troubleshooting"></a>

### ValidationException 上 StartQuery
<a name="sd-query-ts-validation"></a>
+ 验证您`queryStatement`的 SQL 是否有效，且字符数不超过 10,240 个。
+ 验证`workspaceName`匹配模式`^[a-zA-Z0-9_-]+$`。
+ 检查表名和列名是否有效（参见参考表）。

### 查询停滞在运行中
<a name="sd-query-ts-stuck"></a>
+ `CancelQuery`在查询花费太长时间时使用。
+ 15 分钟后查询自动超时。

### ResourceNotFoundException 上 GetQueryResults
<a name="sd-query-ts-not-found"></a>
+ 验证是否`queryId`存在并属于指定的工作空间。
+ 查询 ID 的范围仅限于账户和工作空间。

### 查询返回失败
<a name="sd-query-ts-failed"></a>
+ `DescribeQuery`用于检查`completedAt`时间戳和错误详细信息。
+ 常见原因：SQL 语法无效、引用不存在的列、CAST 表达式中的类型不匹配。

### 结果为空
<a name="sd-query-ts-empty"></a>
+ 验证数据是否已摄入工作空间（`list-time-series`用于检查）。
+ 验证查询是否标记为`COMPLETED`通过`DescribeQuery`。
+ 检查您的 WHERE 子句时间范围是否与摄取的数据的时间戳相匹配。
+ 确保您正在查询正确的工作空间。

### 分页速度慢
<a name="sd-query-ts-slow"></a>
+ 设置`maxResults`为 10,000 英寸`GetQueryResults`以获得最佳性能。
+ 用于`nextToken`对大型结果集进行分页。