本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 从中查询数据 AWS IoT SiteWise
您可以使用 AWS IoT SiteWise API 操作来查询资产属性的当前值、历史值以及特定时间间隔内的聚合。 AWS IoT SiteWise 提供多个查询接口以满足不同的集成需求：
+ **直接 API 操作**-针对特定数据检索需求进行简单、有针对性的 API 调用
+ **类似 SQL 的查询语言**-用于复杂数据分析的强大、灵活的查询
+ **ODBC 驱动程序**-与商业智能工具和应用程序集成
使用这些查询功能可以：
+ 实时洞察运营数据
+ 分析历史趋势和模式
+ 计算工业资产的绩效指标
+ 将物联网数据与企业系统和仪表板集成
+ 构建利用工业数据的自定义应用程序
例如，您可以发现所有具有特定财产价值的资产，构建数据的自定义表示形式，或者开发与 AWS IoT SiteWise 资产中存储的工业数据集成的软件解决方案。您还可以在 AWS IoT SiteWise Monitor中实时浏览您的资产数据。要了解如何配置 SiteWise 监控器，请参阅[使用监控数据 AWS IoT SiteWise Monitor](monitor-data.md)。
本节中介绍的操作返回包含时间戳、质量、值（TQV）结构的属性值对象：
+ `timestamp` 包含当前的 Unix 纪元时间（以秒为单位），偏移量为纳秒。
+ `quality` 包含以下字符串之一，用于指示数据点的质量：
+ `GOOD` – 数据不受任何问题的影响。
+ `BAD` – 数据受传感器故障等问题的影响。
+ `UNCERTAIN` – 数据受传感器不准确等问题的影响。
+ `value` 包含下列字段之一，具体取决于属性的类型：
+ `booleanValue`
+ `doubleValue`
+ `integerValue`
+ `stringValue`
+ `nullValue`
**Topics**
+ [在中查询当前资产属性值 AWS IoT SiteWise](current-values.md)
+ [在中查询历史资产属性值 AWS IoT SiteWise](historical-values.md)
+ [在中查询资产属性聚合 AWS IoT SiteWise](aggregates.md)
+ [AWS IoT SiteWise 查询语言](sql.md)
+ [查询优化](query-optimize.md)
+ [ODBC](query-ODBC.md)
# 在中查询当前资产属性值 AWS IoT SiteWise
本教程展示了两种获取资产属性当前值的方法。您可以使用 AWS IoT SiteWise 控制台或在 AWS Command Line Interface (AWS CLI) 中使用 API。
**Topics**
+ [查询资产属性的当前值（控制台）](#query-current-value-console)
+ [查询资产属性的当前值（AWS CLI）](#query-current-value-cli)
## 查询资产属性的当前值（控制台）
您可以使用 AWS IoT SiteWise 控制台查看资产属性的当前值。
**获取资产属性的当前值（控制台）**
1. 导航至 [AWS IoT SiteWise 控制台](https://console.aws.amazon.com/iotsitewise/)。
1. 在导航窗格中，选择**资产**。
1. 选择具有要查询的属性的资产。
1. 选择箭头图标来展开资产层次结构以查找资产。
1. 选择属性类型对应的选项卡。例如，选择 **测量值** 可以查看测量值属性的当前值。
1. 找到要查看的属性。当前值将显示在 **最新值** 列中。
## 查询资产属性的当前值（AWS CLI）
您可以使用 AWS Command Line Interface (AWS CLI) 来查询资产属性的当前值。
使用[GetAssetPropertyValue](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_GetAssetPropertyValue.html)操作查询资产属性的当前值。
要标识资产属性，请指定以下项之一：
+ 向其发送数据的资产属性的 `assetId` 和 `propertyId`。
+ `propertyAlias`，这是一个数据流别名（例如，`/company/windfarm/3/turbine/7/temperature`）。要使用此选项，您必须首先设置资产属性的别名。要设置属性别名，请参阅[管理数据流 AWS IoT SiteWise](manage-data-streams.md)。
**要获取资产属性的当前值（AWS CLI），请执行以下步骤：**
+ 运行以下命令以获取资产属性的当前值。*asset-id*替换为资产的 ID *property-id* 和属性的 ID。
```
aws iotsitewise get-asset-property-value \
--asset-id asset-id \
--property-id property-id
```
此操作将按以下格式返回包含属性当前的 TQV 的响应。
```
{
"propertyValue": {
"value": {
"booleanValue": Boolean,
"doubleValue": Number,
"integerValue": Number,
"stringValue": "String",
"nullValue": {
"valueType": "String"
}
},
"timestamp": {
"timeInSeconds": Number,
"offsetInNanos": Number
},
"quality": "String"
}
}
```
# 在中查询历史资产属性值 AWS IoT SiteWise
您可以使用 AWS IoT SiteWise API [GetAssetPropertyValueHistory](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_GetAssetPropertyValueHistory.html)操作来查询资产属性的历史值。
要标识资产属性，请指定以下项之一：
+ 向其发送数据的资产属性的 `assetId` 和 `propertyId`。
+ `propertyAlias`，这是一个数据流别名（例如，`/company/windfarm/3/turbine/7/temperature`）。要使用此选项，您必须首先设置资产属性的别名。要设置属性别名，请参阅[管理数据流 AWS IoT SiteWise](manage-data-streams.md)。
传递以下参数来优化结果：
+ `startDate`— 查询历史数据范围的唯一起始点，以 Unix 纪元时间（以秒为单位）表示。
+ `endDate` – 查询历史数据范围的结束端，以 Unix 纪元时间（以秒为单位）表示。
+ `maxResults` – 一个请求中要返回的最大结果数。默认为 `20` 结果。
+ `nextToken` – 从此操作的上一次调用返回的分页标记。
+ `timeOrdering` – 应用于返回值的顺序：`ASCENDING` 或 `DESCENDING`。
+ `qualities` – 筛选结果的质量分为：`GOOD`、`BAD` 或 `UNCERTAIN`。
**要查询资产属性的值历史记录（AWS CLI），请执行以下步骤：**
1. 运行以下命令以获取资产属性的值历史记录。此命令将查询特定 10 分钟间隔内的属性历史记录。*asset-id*替换为资产的 ID *property-id* 和属性的 ID。将日期参数替换为要查询的时间间隔。
```
aws iotsitewise get-asset-property-value-history \
--asset-id asset-id \
--property-id property-id \
--start-date 1575216000 \
--end-date 1575216600
```
该操作返回的响应包含该属 TQVs 性的历史记录，格式如下：
```
{
"assetPropertyValueHistory": [
{
"value": {
"booleanValue": Boolean,
"doubleValue": Number,
"integerValue": Number,
"stringValue": "String",
"nullValue": {
"valueType": "String"
}
},
"timestamp": {
"timeInSeconds": Number,
"offsetInNanos": Number
},
"quality": "String"
}
],
"nextToken": "String"
}
```
1. 如果存在更多值条目，则可以将分页令牌从`nextToken`字段传递给后续的[GetAssetPropertyValueHistory](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_GetAssetPropertyValueHistory.html)操作调用。
# 在中查询资产属性聚合 AWS IoT SiteWise
AWS IoT SiteWise 自动计算聚合的资产属性值，这些值是在多个时间间隔内计算出来的一组基本指标。 AWS IoT SiteWise 每分钟、每小时和每天计算您的资产属性的以下聚合：
+ **平均值** – 属性在一个时间间隔内的平均值。
+ **计数** – 属性在一个时间间隔内的数据点数。
+ **最大值** – 属性在一个时间间隔内的最大值。
+ **最小值** – 属性在一个时间间隔内的最小值。
+ **标准偏差** – 属性值在一个时间间隔内的标准偏差。
+ **总和** – 属性值在一个时间间隔内的总和。
对于非数字属性，例如字符串和布尔值，仅 AWS IoT SiteWise 计算计数聚合。
您还可以计算资产数据的自定义指标。借助指标属性，定义特定于操作的聚合。指标属性提供了额外的聚合函数和时间间隔，这些函数和时间间隔不是为 AWS IoT SiteWise API 预先计算的。有关更多信息，请参阅 [聚合来自属性和其他资产（指标）的数据](metrics.md)。
**Topics**
+ [资产属性的聚合（API）](#aggregates-api)
+ [资产属性的聚合（AWS CLI）](#aggregates-cli)
## 资产属性的聚合（API）
使用 AWS IoT SiteWise API 获取资产属性的聚合。
使用[GetAssetPropertyAggregates](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_GetAssetPropertyAggregates.html)操作来查询资产属性的聚合。
要标识资产属性，请指定以下项之一：
+ 向其发送数据的资产属性的 `assetId` 和 `propertyId`。
+ `propertyAlias`，这是一个数据流别名（例如，`/company/windfarm/3/turbine/7/temperature`）。要使用此选项，您必须首先设置资产属性的别名。要设置属性别名，请参阅[管理数据流 AWS IoT SiteWise](manage-data-streams.md)。
您必须传递以下必需参数：
+ `aggregateTypes` – 要检索的聚合的列表。您可以指定 `AVERAGE`、`COUNT`、`MAXIMUM`、`MINIMUM`、`STANDARD_DEVIATION` 和 `SUM` 中的任何一个。
+ `resolution`— 检索指标的时间间隔：`1m`（1 分钟）、`15m`（15 分钟）、`1h`（1 小时）或`1d`（1 天）。
+ `startDate`— 查询历史数据范围的唯一起始点，以 Unix 纪元时间（以秒为单位）表示。
+ `endDate` – 查询历史数据范围的结束端，以 Unix 纪元时间（以秒为单位）表示。
还可以传递以下任何参数来优化结果：
+ `maxResults` – 一个请求中要返回的最大结果数。默认为 `20` 结果。
+ `nextToken` – 从此操作的上一次调用返回的分页标记。
+ `timeOrdering` – 应用于返回值的顺序：`ASCENDING` 或 `DESCENDING`。
+ `qualities` – 筛选结果的质量分为：`GOOD`、`BAD` 或 `UNCERTAIN`。
**注意**
该[GetAssetPropertyAggregates](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_GetAssetPropertyAggregates.html)操作返回的 TQV 格式与本节中描述的其他操作不同。`value` 结构包含请求中每个 `aggregateTypes` 的字段。`timestamp` 包含聚合发生的时间，以 Unix 纪元时间表示（以秒为单位）。
## 资产属性的聚合（AWS CLI）
**要查询资产属性的聚合（AWS CLI），请执行以下步骤：**
1. 运行以下命令以获取资产属性的聚合。此命令会查询特定 1 小时间隔内的平均值和总和（采用 1 小时分辨率）。*asset-id*替换为资产的 ID *property-id* 和属性的 ID。将参数替换为要查询的聚合和时间间隔。
```
aws iotsitewise get-asset-property-aggregates \
--asset-id asset-id \
--property-id property-id \
--start-date 1575216000 \
--end-date 1575219600 \
--aggregate-types AVERAGE SUM \
--resolution 1h
```
该操作返回的响应包含以下格式 TQVs 的属性的历史记录。响应中仅包括请求的聚合。
```
{
"aggregatedValues": [
{
"timestamp": Number,
"quality": "String",
"value": {
"average": Number,
"count": Number,
"maximum": Number,
"minimum": Number,
"standardDeviation": Number,
"sum": Number
}
}
],
"nextToken": "String"
}
```
1. 如果存在更多值条目，则可以将分页令牌从`nextToken`字段传递给后续的[GetAssetPropertyAggregates](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_GetAssetPropertyAggregates.html)操作调用。
**注意**
如果您的查询范围包含`null`值 TQVs，请参阅 [AssetPropertyValue](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_AssetPropertyValue.html)API。除计数之外的所有统计信息都会产生`null`响应，类似于 String 的统计信息 TQVs。如果您的查询范围包含双精`Double.NaN`度类型 TQVs，则除 count 之外的所有计算都将得出`Double.NaN`。
# AWS IoT SiteWise 查询语言
通过 AWS IoT SiteWise 数据检索 [ExecuteQuery](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_ExecuteQuery.html)API 操作，您可以从以下位置检索有关声明式结构定义以及与之关联的时间序列数据的信息：
+ 模型
+ 资产
+ 测量值
+ metrics
+ 转换
+ 聚合
这可以在单个 API 请求中使用类似查询语句的 SQL 来完成。
**注意**
该功能适用于所有可用的区域 AWS IoT SiteWise ，但 AWS GovCloud （美国西部）、加拿大（中部）、中国（北京）和美国东部（俄亥俄州）除外。
**Topics**
+ [查询语言参考 AWS IoT SiteWise](query-reference.md)
# 查询语言参考 AWS IoT SiteWise
AWS IoT SiteWise 支持丰富的查询语言来处理您的数据。以下主题介绍了可用的数据类型、运算符、函数和构造。
[示例查询](sql-examples.md)要使用查询语言编写 AWS IoT SiteWise 查询，请参阅。
**Topics**
+ [查询参考视图](query-reference-views.md)
+ [支持的数据类型](supported-data-types.md)
+ [支持的子句](supported-clauses.md)
+ [逻辑运算符](sql-supported-logical.md)
+ [比较运算符](sql-supported-comparision.md)
+ [SQL 函数](sql-functions.md)
+ [示例查询](sql-examples.md)
# 查询参考视图
本节提供的信息可帮助您理解中的视图 AWS IoT SiteWise，例如流程元数据和遥测数据。
下表提供了视图的视图名称和描述：
**数据模型**
| **视图名称** | **视图描述** |
| --- | --- |
| asset | 包含有关资产和模型派生的信息。 |
| asset\$1property | 包含有关资产属性结构的信息。 |
| raw\$1time\$1series | 包含时间序列的历史数据。 |
| latest\$1value\$1time\$1series | 包含时间序列的最新值。 |
| precomputed\$1aggregates | 包含自动计算的聚合资产属性值。它们是一组按多个时间间隔计算的基本指标。 |
以下视图列出了每个视图的列名和数据类型。
**视图：asset**
| **列名** | **datatype** |
| --- | --- |
| asset\$1id | 字符串 |
| asset\$1name | 字符串 |
| asset\$1description | 字符串 |
| asset\$1model\$1id | 字符串 |
| 父资产标识 | 字符串 |
| asset\$1external\$1id | 字符串 |
| asset\$1model\$1external\$1id | 字符串 |
| 层次结构\$1id | 字符串 |
**视图：asset\$1property**
| **列名** | **datatype** |
| --- | --- |
| asset\$1id | 字符串 |
| property\$1id | 字符串 |
| property\$1name | 字符串 |
| property\$1alias | 字符串 |
| 属性\$1external\$1id | 字符串 |
| asset\$1composite\$1model\$1id | 字符串 |
| 属性\$1类型 | 字符串 |
| property\$1data\$1type | 字符串 |
| int\$1属性\$1值 | 整数 |
| 双重属性值 | double |
| 布尔属性值 | 布尔值 |
| 字符串\$1属性\$1值 | 字符串 |
**视图：raw\$1time\$1series**
| **列名** | **datatype** |
| --- | --- |
| asset\$1id | 字符串 |
| property\$1id | 字符串 |
| property\$1alias | 字符串 |
| event\$1timestamp | timestamp |
| quality | 字符串 |
| boolean\$1value | 布尔值 |
| int\$1value | 整数 |
| double\$1value | double |
| string\$1value | 字符串 |
**视图：latest\$1value\$1time\$1series**
| **列名** | **datatype** |
| --- | --- |
| asset\$1id | 字符串 |
| property\$1id | 字符串 |
| property\$1alias | 字符串 |
| event\$1timestamp | timestamp |
| quality | 字符串 |
| boolean\$1value | 布尔值 |
| int\$1value | 整数 |
| double\$1value | double |
| string\$1value | 字符串 |
**视图：precomputed\$1aggregates**
| **列名** | **datatype** |
| --- | --- |
| asset\$1id | 字符串 |
| property\$1id | 字符串 |
| property\$1alias | 字符串 |
| event\$1timestamp | timestamp |
| quality | 字符串 |
| resolution | 字符串 |
| sum\$1value | double |
| count\$1value | 整数 |
| average\$1value | double |
| maximum\$1value | double |
| minimum\$1value | double |
| stdev\$1value | double |
# 支持的数据类型
AWS IoT SiteWise 查询语言支持以下数据类型。
**标量值**
| **数据类型** | **描述** |
| --- | --- |
| `STRING` | 最大长度为 1024 个字节的字符串。 |
| `INTEGER` | 有符号的 32 位整数，其范围为 `-2,147,483,648 to 2,147,483,647`。 |
| `DOUBLE` | 浮点数`–10^100 to 10^100`，范围为或精`Nan`度为`IEEE 754`双精度。 |
| `BOOLEAN` | `true` 或 `false`。 |
| `TIMESTAMP` | 符合 ISO-8601 标准的时间戳： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/iot-sitewise/latest/userguide/supported-data-types.html) |
**注意**
`Null`：`true`表示缺少已定义数据的布尔值。
**Example**
`TIMESTAMP`值示例：
```
TIMESTAMP '2025-12-21 23:59:59.999Z'
TIMESTAMP '2025-12-21 23:59:59+23:59'
'2025-12-21 23:59:59'
'2025-12-21T23:59:59.123+11:11'
```
**注意**
双精度数据不准确。由于精度有限，有些值无法精确转换，也无法代表所有实数。查询中的浮点数据可能与内部表示的值不同。如果输入数字的精度过高，则该值将被四舍五入。
# 支持的子句
该`SELECT`语句用于从一个或多个视图中检索数据。 AWS IoT SiteWise 支持`JOIN`和`INNER JOIN`操作。
视图使用显式`JOIN`语法或子句中以逗号分隔的符号连接。`FROM`
**Example**
一般性`SELECT`陈述：
```
SELECT expression [, ...]
[ FROM table_name AS alias [, ...] ]
[ WHERE condition ]
[ GROUP BY expression [, ...] ]
[ HAVING condition ]
[ ORDER BY expression [ ASC | DESC ] [ NULLS FIRST | NULLS LAST ] [, ...] ]
[ LIMIT expression ]
```
**Example**
包含不同子句的 SELECT 语句：
```
SELECT
a.asset_name,
a.asset_id,
p.property_type,
p.property_data_type,
p.string_attribute_value,
p.property_name
FROM asset a, asset_property p
WHERE a.asset_description LIKE '%description%'
AND p.property_type IN ('attribute', 'metric')
OR p.property_id IN (
SELECT property_id
FROM raw_time_series
WHERE event_timestamp BETWEEN TIMESTAMP '2025-01-01 00:00:00' AND TIMESTAMP '2025-01-02 00:00:00'
GROUP BY asset_id, property_id
HAVING COUNT(*) > 100
)
GROUP BY p.property_type
HAVING COUNT(*) > 5
ORDER BY a.asset_name ASC
LIMIT 20;
```
**注意**
隐式`JOIN`组合了两个或多个不同的表，而不使用基于 AWS IoT SiteWise的内部架构的`JOIN`关键字。这等效于`JOIN`在元数据表`asset_id`和原始数据表之间对和`property_id`字段执行。当从原始数据表中提取数据时，这种模式允许 SiteWise 在查询中利用任何给定的元数据筛选器，从而减少扫描的总体数据。
**Example 查询的：**
```
SELECT a.asset_name, p.property_name, r.event_timestamp
FROM asset a, asset_property p, raw_time_series r
WHERE a.asset_name='my_asset' AND p.property_name='my_property'
```
上面的示例仅扫描属于指定元数据名称的资产属性的数据。
**Example 与上述查询相比，优化程度较低的等效查询：**
```
SELECT a.asset_name, p.property_name, r.event_timestamp
FROM asset a
JOIN asset_property p ON a.asset_id=p.asset_id
JOIN raw_time_series r ON p.asset_id=r.asset_id AND p.property_id=r.property_id
WHERE a.asset_name='my_asset' AND p.property_name='my_property'
```
下面列出了每个条款的解释及其描述：
| **条款** | **签名** | **描述** |
| --- | --- | --- |
| `LIMIT` | LIMIT { count } | 此子句将结果集限制为指定的行数。您可以使用`LIMIT`带或不带`ORDER BY`和`OFFSET`子句。 `LIMIT`仅适用于 [0,2147483647] 中的非负整数。 |
| `ORDER BY` | ORDER BY expression
[ ASC | DESC ]
[ NULLS FIRST | NULLS LAST ]
| 该`ORDER BY`子句对查询的结果集进行排序。 在`ORDER BY`子句中引用聚合中的选定列时，请使用该列的序数索引，而不是名称或别名。 SELECT AVG(t.double_value)
FROM latest_value_time_series t
GROUP BY t.asset_id
ORDER BY 1
|
| `GROUP BY` | GROUP BY expression [, ...]
| 该`GROUP BY`子句标识查询的分组列。它与聚合表达式一起使用。 |
| `HAVING` | HAVING boolean-expression
| 该`HAVING`子句筛选由 GROUP BY 子句创建的组行。 |
| `SUB SELECT` | SELECT column1, column2
FROM table1
WHERE column3 IN (SELECT column4 FROM table2);
| 嵌入在另一条`SELECT`语句中的`SELECT`语句。 |
| `JOIN` | SELECT column1, column2
FROM table1 JOIN table2
ON table1.column1 = table2.column1;
|
| `INNER JOIN` | SELECT columns
FROM table1
INNER JOIN table2 ON table1.column = table2.column;
| `INNER JOIN`返回两个表中符合联接条件的所有行。 |
| `UNION` | query
{ UNION [ ALL ] }
another_query
| `UNION`运算符计算其两个参数的集合并集，自动从结果集中删除重复的记录。 |
# 逻辑运算符
AWS IoT SiteWise 支持以下逻辑运算符。
| **运算符** | **签名** | **描述** |
| --- | --- | --- |
| `AND` | a `AND` b | 如果两个值都为真，则为 `TRUE` |
| `OR` | a `OR` b | `TRUE`如果一个值为真 |
| `NOT` | `NOT` 表达式 | `TRUE`如果表达式为假，`FALSE`如果表达式为真 |
| `IN` | x `IN` 表达式 | `TRUE`如果表达式中有值 |
| `BETWEEN` | `BETWEEN`a `AND` b | `TRUE`如果值介于上限和下限之间，并且包括两个限制 |
| `LIKE` | `LIKE` 模式 | `TRUE`如果值在模式中 `LIKE`支持通配符。有关示例，请参见下文： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/iot-sitewise/latest/userguide/sql-supported-logical.html) |
所有逻辑运算符的示例：
| **函数** | **示例** |
| --- | --- |
| AND | SELECT a.asset_name
FROM asset AS a, latest_value_time_series AS t
WHERE t.int_value > 30 AND t.event_timestamp > TIMESTAMP '2025-05-15 00:00:01'
|
| 或 | SELECT a.asset_name
FROM asset AS a
WHERE a.asset_name like 'abc' OR a.asset_name like 'pqr'
|
| NOT | SELECT ma.asset_id AS a_id
FROM asset AS ma
WHERE (ma.asset_id NOT LIKE 'some%patterna%' escape 'a') AND ma.asset_id='abc'
|
| IN | SELECT a.asset_name
FROM asset AS a
WHERE a.asset_name IN ('abc', 'pqr')
|
| BETWEEN | SELECT asset_id, int_value, event_timestamp AS i_v
FROM raw_time_series
WHERE event_timestamp BETWEEN TIMESTAMP '2025-04-15 00:00:01' and TIMESTAMP '2025-05-15 00:00:01'
|
| LIKE | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/iot-sitewise/latest/userguide/sql-supported-logical.html) |
# 比较运算符
AWS IoT SiteWise 支持以下比较运算符。所有比较操作都适用于内置数据类型，其计算结果为布尔值。
**逻辑运算符**
| **运算符** | **描述** |
| --- | --- |
| `<` | Less than |
| `>` | Greater than |
| `<=` | 小于或等于 |
| `>=` | 大于或等于 |
| `=` | Equals |
| `!=` | Not equal |
**非数值的比较运算真值表**
| **Type** | **键入 >= x** | **键入 <= x** | **键入 > x** | **键入 < x** | **类型 = x** | **键入！ = x** |
| --- | --- | --- | --- | --- | --- | --- |
| `NULL` | `FALSE` | `FALSE` | `FALSE` | `FALSE` | `FALSE` | `TRUE` |
有些谓词的行为类似于运算符，但语法特殊。请参阅下面的：
**比较谓词**
| **运算符** | **描述** |
| --- | --- |
| `IS NULL` | 测试一个值是否为`NULL`。 |
| `IS NOT NULL` | 测试一个值是否不是`NULL`。 |
## NaN 运算符
`NaN`，或 “Not a Number”，是浮点运算中的一个特殊值。以下是`NaN`比较列表及其工作原理。
+ `NaN`值必须用单引号括起来。例如，'`NaN`'。
+ `NaN`值被认为彼此相等。
+ `NaN`大于其他数值。
+ 在、和`AVG()``STDDEV()`、等聚合函数中`SUM()`，如果有任何值`NaN`，则结果为`NaN`。
+ 在`MAX()`和之类的聚合函数中`MIN()`，`NaN`值包含在计算中。
**NaN 值比较**
| **Comparison**（比较） | **结果** |
| --- | --- |
| `'NaN' ≥ x` | True |
| `'NaN' ≤ x` | 如果 x 等于 NaN 则为真，否则为假 |
| `'NaN' > x` | 如果 x 等于 NaN 则为假，否则为真 |
| `'NaN' < x` | False |
| `'NaN' = x` | 如果 x 等于 NaN 则为真，否则为假 |
| `'NaN' != x` | 如果 x 等于 NaN 则为假，否则为真 |
# SQL 函数
支持的函数组有：
**Topics**
+ [标量函数](sql-functions-scalar.md)
+ [聚合函数](sql-functions-aggregated.md)
# 标量函数
标量函数接受一个或多个输入值并返回单个输出值。它们在 SQL（结构化查询语言）中被广泛用于数据操作和检索，从而提高了数据处理任务的效率。
**Topics**
+ [空数据函数](sql-functions-null.md)
+ [字符串函数](sql-functions-string.md)
+ [数学函数](sql-functions-math.md)
+ [日期时间函数](sql-functions-date.md)
+ [类型转换函数](sql-functions-type-conv.md)
# 空数据函数
Null 数据函数处理或操作 NULL 值，这些值表示缺少值。这些函数允许您 NULLs 用其他值替换、检查值是否为 NULL 或执行以特定 NULLs 方式处理的操作。
| **函数** | **签名** | **描述** |
| --- | --- | --- |
| `COALESCE` | COALESCE（表达式 1、表达式 2、...、expressionN） | 如果所有表达式的计算结果均为空，则 COALESCE 返回空值。表达式的类型必须相同。 |
**Example COALESCE 函数的**
```
SELECT COALESCE (l.double_value, 100) AS non_double_value FROM latest_value_time_series AS l LIMIT 1
```
# 字符串函数
字符串函数是用于操作和处理文本数据的内置工具。它们支持串联、提取、格式化和在字符串中搜索等任务。这些功能对于清理、转换和分析数据库中基于文本的数据至关重要。
**字符串函数**
| **函数** | **签名** | **描述** |
| --- | --- | --- |
| `LENGTH` | 长度（字符串） | 返回字符串的长度。 |
| `CONCAT` | CONCAT（字符串、字符串） | 连接字符串中的参数。 |
| `SUBSTR` | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/iot-sitewise/latest/userguide/sql-functions-string.html) | 返回以下内容之一： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/iot-sitewise/latest/userguide/sql-functions-string.html) 使用基于 1 的索引作为起始参数。 |
| `UPPER` | UPPER（字符串） | 将输入字符串中的字符转换为大写。 |
| `LOWER` | 下限（字符串） | 将输入字符串中的字符转换为小写。 |
| `TRIM` | 修剪（字符串） | 删除字符串开头、结尾或两边的所有空格字符。 |
| `LTRIM` | LTRIM（字符串） | 删除字符串开头的所有空格字符。 |
| `RTRIM` | RTRIM（字符串） | 删除字符串末尾的所有空格字符。 |
| `STR_REPLACE` | STR\$1REPLACE（字符串，从、到） | 用另一个指定的子字符串替换所有出现的指定子字符串。 |
所有功能的示例：
| **函数** | **示例** |
| --- | --- |
| LENGTH | `SELECT LENGTH(a.asset_id) AS asset_id_length FROM asset AS a` |
| CONCAT | `SELECT CONCAT(p.property_id, p.property_name) FROM asset_property AS p` |
| SUBSTR | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/iot-sitewise/latest/userguide/sql-functions-string.html) |
| UPPER | `SELECT UPPER(d.string_value) AS up_string FROM raw_time_series AS d` |
| LOWER | `SELECT LOWER(d.string_value) AS low_string FROM raw_time_series AS d` |
| TRIM | `SELECT TRIM(d.string_value) AS tm_string FROM raw_time_series AS d` |
| LTRIM | `SELECT LTRIM(d.string_value) AS ltrim_string FROM raw_time_series AS d` |
| RTRIM | `SELECT RTRIM(d.string_value) AS rtrim_string FROM raw_time_series AS d` |
| STR\$1REPALE | `SELECT STR_REPLACE(d.string_value, 'abc', 'def') AS replaced_string FROM raw_time_series AS d` |
## 串联运算符
连接运算符或管道运算`||`符将两个字符串连接在一起。它提供了该`CONCAT`函数的替代方案，并且在组合多个字符串时更具可读性。
**Example 的串联运算符**
```
SELECT a.asset_name || ' - ' || p.property_name
AS full_name
FROM asset a, asset_property p
```
# 数学函数
数学函数是预定义的数学运算，用于在 SQL 查询中对数值数据进行计算。它们提供了操作和转换数据的方法，而无需从数据库中提取数据并单独处理数据。
**数学函数**
| **函数** | **签名** | **描述** |
| --- | --- | --- |
| `POWER` | 功率（整数\$1双精度，整数\$1双精度） | 返回第一个参数的值乘以第二个参数的次方。 |
| `ROUND` | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/iot-sitewise/latest/userguide/sql-functions-math.html) | 四舍五入到最接近的整数。 |
| `FLOOR` | 地板 (int\$1double) | 返回不大于给定值的最大整数。 |
所有功能的示例：
| **函数** | **示例** |
| --- | --- |
| POWER | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/iot-sitewise/latest/userguide/sql-functions-math.html) |
| ROUND | `ROUND (32.12435, 3)` |
| FLOOR | `FLOOR (21.2)` |
# 日期时间函数
日期时间函数适用于日期和时间。这些函数允许提取日期的特定组成部分、执行计算和操作日期值。
这些函数中允许使用的标识符是：
+ YEAR
+ MONTH
+ DAY
+ HOUR
+ MINUTE
+ SECOND
| **函数** | **签名** | **描述** |
| --- | --- | --- |
| `NOW` | 现在 () | 返回精度为毫秒的当前时间戳。它提供了在查询中执行时的确切时间。 |
| `DATE_ADD` | DATE\$1ADD（标识符、间隔持续时间、列） | 返回 a date/time 和多个days/hours, or of a date/time and date/time间隔的总和。 |
| `DATE_SUB` | DATE\$1SUB（标识符、间隔持续时间、列） | 返回 a date/time 和多个间days/hours, or between a date/time and date/time隔之间的差。 |
| `TIMESTAMP_ADD` | TIMESTAMP\$1ADD（标识符、间隔持续时间、列） | 在日期时间表达式中添加以给定时间单位为单位的时间间隔。 |
| `TIMESTAMP_SUB` | TIMESTAMP\$1SUB（标识符、间隔持续时间、列） | 从日期时间表达式中减去以给定时间单位为单位的时间间隔。 |
| `CAST` | CAST（表达式为时间戳格式模式） | 使用指定的格式模式将字符串表达式转换为时间戳。常见模式包括`'yyyy-MM-dd HH:mm:ss'`标准日期时间格式。例如，`SELECT CAST('2023-12-25 14:30:00' AS TIMESTAMP) AS converted_timestamp` |
**Example 使用列出的函数进行的 SQL 查询：**
```
SELECT r.asset_id, r.int_value,
date_add(DAY, 7, r.event_timestamp) AS date_in_future,
date_sub(YEAR, 2, r.event_timestamp) AS date_in_past,
timestamp_add(DAY, 2, r.event_timestamp) AS timestamp_in_future,
timestamp_sub(DAY, 2, r.event_timestamp) AS timestamp_in_past,
now() AS time_now
FROM raw_time_series AS r
```
# 类型转换函数
类型转换函数用于将值的数据类型从一种更改为另一种值。它们对于确保数据兼容性和执行需要特定格式数据的操作至关重要。
| **函数** | **签名** | **描述** |
| --- | --- | --- |
| `TO_DATE` | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/iot-sitewise/latest/userguide/sql-functions-type-conv.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/iot-sitewise/latest/userguide/sql-functions-type-conv.html) |
| `TO_TIMESTAMP` | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/iot-sitewise/latest/userguide/sql-functions-type-conv.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/iot-sitewise/latest/userguide/sql-functions-type-conv.html) |
| `TO_TIME` | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/iot-sitewise/latest/userguide/sql-functions-type-conv.html) | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/iot-sitewise/latest/userguide/sql-functions-type-conv.html) |
| `CAST` | 演员阵容（饰演） | 将计算结果为单个值的实体或表达式从一种类型转换为另一种类型。 支持的数据类型包括： [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/iot-sitewise/latest/userguide/sql-functions-type-conv.html) |
**Example 使用列出的函数进行的 SQL 查询：**
```
SELECT TO_TIMESTAMP (100) AS timestamp_value,
TO_DATE(r.event_timestamp) AS date_value,
TO_TIME(r.event_timestamp) AS time_value
FROM raw_time_series AS r
```
# 聚合函数
聚合函数是对多行数据执行计算以生成单个汇总结果的数据库操作。这些函数分析数据集以返回计算值，例如总和、平均值、计数或其他统计度量。
| **函数** | **签名** | **描述** |
| --- | --- | --- |
| `AVG` | 平均值（表达式） | 返回数值表达式的平均值。 |
| `COUNT` | 计数（表达式） | 返回符合给定条件的行数。 |
| `MAX` | 最大值（表达式） | 返回所选表达式的最大值。 |
| `MIN` | MIN（表达式） | 返回所选表达式的最小值。 |
| `SUM` | SUM（表达式） | 返回数值表达式的和。 |
| `STDDEV` | STDDEV（表达式） | 返回样本标准差。 |
| `GROUP BY` | GROUP BY 表达式 | 返回由分组列创建的行。 |
| `HAVING` | 有布尔表达式 | 返回按`GROUP BY`子句筛选的分组行。 |
所有功能的示例：
| **函数** | **示例** |
| --- | --- |
| AVG | SELECT d.asset_id, d.property_id, AVG(d.int_value) FROM raw_time_series AS d
|
| COUNT | SELECT COUNT(d.int_value) FROM raw_time_series AS d
|
| MAX | SELECT MAX(d.int_value) FROM raw_time_series AS d
|
| MIN | SELECT MIN(d.int_value) FROM raw_time_series AS d
|
| SUM | SELECT SUM(d.int_value) FROM raw_time_series AS d
|
| STDDEV | SELECT STDDEV(d.int_value) FROM raw_time_series AS d
|
| [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/iot-sitewise/latest/userguide/sql-functions-aggregated.html) | SELECT MAX(d.int_value) AS max_int_value, d.asset_id
FROM raw_time_series AS d
GROUP BY d.asset_id
HAVING MAX(d.int_value) > 5
|
# 示例查询
## 元数据筛选
以下示例是使用带有 AWS IoT SiteWise 查询语言的语`SELECT`句进行元数据筛选：
```
SELECT a.asset_name, p.property_name
FROM asset a, asset_property p
WHERE a.asset_name LIKE 'Windmill%'
```
## 值筛选
以下是使用带有 AWS IoT SiteWise 查询语言的语`SELECT`句进行值筛选的示例：
```
SELECT a.asset_name, r.int_value
FROM asset a, raw_time_series r
WHERE r.int_value > 30
AND r.event_timestamp > TIMESTAMP '2022-01-05 12:15:00'
AND r.event_timestamp < TIMESTAMP '2022-01-05 12:20:00'
```
# 查询优化
## 元数据过滤器
查询元数据或原始数据时，使用`WHERE`子句按元数据字段进行筛选，以减少扫描的数据量。使用以下运算符来限制元数据扫描：
+ 等于（=）
+ 不等于（\$1=）
+ LIKE
+ IN
+ AND
+ 或
对于属性属性，请使用以下字段筛选结果。 :
+ `double_attribute_value`
+ `int_attribute_value`
+ `boolean_attribute_value`
+ `string_attribute_value`
对于属性类型的资产属性，这些字段的性能优于**最新的 value\$1time\$1series** 表。
**注意**
使用运算符右侧的文字来正确限制数据扫描。例如，以下查询的性能比使用严格的字符串字面量差：
```
SELECT property_id FROM asset_property WHERE property_name = CONCAT('my', 'property')
```
**Example 对于元数据过滤器：**
```
SELECT p.property_name FROM asset_property p
WHERE p.property_type = 'attribute' AND p.string_attribute_value LIKE 'my-property-%'
```
## 原始数据过滤器
**所有原始数据表（**raw\$1time\$1series、latest\$1value\$1time\$1series** **、precomputed\$1aggrates）都有与其行关联的时间戳**。**除了元数据筛选器外，还可以在`event_timestamp`字段上使用`WHERE`子句筛选器来减少扫描的数据量。使用以下操作来限制原始数据扫描：
+ 等于（=）
+ 大于（>）
+ 小于（<）
+ 大于等于（>=）
+ 小于等于（<=）
+ BETWEEN
+ AND
**过滤器示例**：
+ 查询 precom **puted\$1aggregates 表**时，请务必在子句中指定质量过滤器。`WHERE`这样可以减少查询扫描的数据量，尤其是在您要查找`BAD`或`UNCERTAIN`数据时。
**我们还强烈建议在查询 precomputed\$1aggregates 表时使用分辨率过滤器（1m、15m、1h 或 1d）。**如果未指定分辨率过滤器， AWS IoT SiteWise 则默认为对所有分辨率进行全表扫描，这样效率低下。
+ 查询原始数据时，还可以在`WHERE`子句中使用时间戳函数来筛选扫描的数据量。例如，以下查询仅扫描 **raw\$1time\$1** series 表中最近 30 分钟的数据：
```
SELECT r.event_timestamp, r.double_value
FROM raw_time_series r
WHERE r.event_timestamp > TIMESTAMP_SUB(MINUTE, 30, NOW())
```
**注意**
不等于`(!=)`，`OR`运算符通常不会对原始数据扫描应用有意义的过滤器。对原始数据值（字符串值、double\$1value 等）进行筛选也不会限制原始数据扫描。
## 加入优化
AWS IoT SiteWise SQL 支持使用`JOIN`关键字将两个表合并在一起。仅`JOIN`支持主动筛选字段（使用`ON`关键字）的。禁止使用完全笛卡尔联接。
AWS IoT SiteWise 还支持不使用`JOIN`关键字的隐式 `JOIN` s。允许在不同的元数据表之间以及元数据表和原始表之间进行这些操作。例如，此查询：
```
SELECT a.asset_name, p.property_name FROM asset a, asset_property p
```
比这个等效的查询执行得更好：
```
SELECT a.asset_name, p.property_name FROM asset a
JOIN asset_property p ON a.asset_id = p.asset_id
```
允许使用以下隐式联接（允许 O，禁止 X）：
| | asset | asset\$1property | latest\$1value\$1time\$1series | raw\$1time\$1series | precomputed\$1aggregates | subquery |
| --- | --- | --- | --- | --- | --- | --- |
| asset | X | O | O | O | O | X |
| asset\$1property | O | X | O | O | O | X |
| latest\$1value\$1time\$1series | O | O | X | X | X | X |
| raw\$1time\$1series | O | O | X | X | X | X |
| precomputed\$1aggregates | O | O | X | X | X | X |
| subquery | X | X | X | X | X | X |
尽可能使用隐式 `JOIN` s。如果必须使用`JOIN`关键字，请对各个 e `JOIN` d 表应用筛选器以最大限度地减少扫描的数据。例如，用以下查询代替这个查询：
```
SELECT level1.asset_id, level2.asset_id, level3.asset_id
FROM asset AS level1
JOIN asset AS level2 ON level2.parent_asset_id = level1.asset_id
JOIN asset AS level3 ON level3.parent_asset_id = level2.asset_id
WHERE level1.asset_name LIKE 'level1%'
AND level2.asset_name LIKE 'level2%'
AND level3.asset_name LIKE 'level3%'
```
使用这个更有效的查询：
```
SELECT level1.asset_id, level2.asset_id, level3.asset_id
FROM asset AS level1
JOIN (SELECT asset_id, parent_asset_id FROM asset WHERE asset_name LIKE 'level2%') AS level2 ON level2.parent_asset_id = level1.asset_id
JOIN (SELECT asset_id, parent_asset_id FROM asset WHERE asset_name LIKE 'level3%') AS level3 ON level3.parent_asset_id = level2.asset_id
WHERE level1.asset_name LIKE 'level1%'
```
通过将元数据过滤器推送到子查询中，可以确保在扫描过程中对 `JOIN` s中的各个表进行过滤。你也可以在子查询中使用`LIMIT`关键字来达到同样的效果。
## 大型查询
对于生成的行数超过默认值的查询，请将 [ExecuteQuery](https://docs.aws.amazon.com/iot-sitewise/latest/APIReference/API_ExecuteQuery.html)API 的页面大小设置为最大值 20000。这提高了整体查询性能。
使用子`LIMIT`句可以减少为某些查询扫描的数据量。请注意，聚合函数和某些表范围的子句（`GROUP BY`、`ORDER BY`、`JOIN`）需要在应用子句之前进行全面扫描才能完成。`LIMIT`
**注意**
AWS IoT SiteWise 即使应用了`LIMIT`子句，也可以扫描最少量的数据，特别是对于扫描多个属性的原始数据查询。
# ODBC
的开源 [ODBC 驱动程序](https://github.com/awslabs/aws-iotsitewise-odbc-driver)为开发人员 AWS IoT SiteWise 提供了 SQL 关系接口，并支持从 Power BI Desktop 和 Microsoft Excel 等商业智能 (BI) 工具进行连接。 AWS IoT SiteWise AWS IoT SiteWise ODBC 驱动程序目前在 [Windows](https://github.com/awslabs/aws-iotsitewise-odbc-driver/releases) 上可用，支持 Okta 的 SSO 和微软 Azure Active Directory (AD)。
有关更多信息，请参阅[上的AWS IoT SiteWise ODBC 驱动程序文档。 GitHub](https://github.com/awslabs/aws-iotsitewise-odbc-driver/blob/main/docs/markdown/index.md)
**Topics**
+ [ODBC 驱动程序的连接字符串语法及选项](query-ODBC-connecting.md)
+ [AWS IoT SiteWise ODBC 驱动程序的连接字符串示例](query-ODBC-connecting-examples.md)
+ [对 ODBC 驱动程序连接进行故障排除](query-ODBC-connecting-troubleshooting.md)
# ODBC 驱动程序的连接字符串语法及选项
用于指定 ODBC 驱动程序连接字符串选项的语法如下：
```
Driver={AWS IoT SiteWise ODBC Driver};(option)=(value);
```
可用选项如下：
**驱动程序连接选项**
+ **`Driver`** *（必填）*：与 ODBC 结合使用的驱动程序。
默认值为 AWS IoT SiteWise。
+ **`DSN`**：用于配置连接的数据来源名称（DSN）。
默认值为 `NONE`。
+ **`Auth`**：身份验证模式。其必须是以下内容之一：
+ `AWS_PROFILE`：使用默认凭证链。
+ `IAM`— 使用 AWS IAM 证书。
+ `AAD`：使用 Azure Active Directory（AD）身份提供商。
+ `OKTA`：使用 Okta 身份提供商。
默认值为 `AWS_PROFILE`。
**端点配置选项**
+ **`EndpointOverride`**— AWS IoT SiteWise 服务的终端节点覆盖。这是用于覆盖区域的高级选项。例如：
```
iotsitewise.us-east-1.amazonaws.com
```
+ **`Region`**— AWS IoT SiteWise 服务终端节点的签名区域。
默认值为 `us-east-1`。
**凭证提供程序选项**
+ **`ProfileName`**— 配置文件中的 AWS 配置文件名称。
默认值为 `NONE`。
**AWS IAM 身份验证选项**
+ **`UID`**或 **`AccessKeyId`**- AWS 用户访问密钥 ID。如果连接字符串中同时提供 `UID` 和 `AccessKeyId`，则将使用 `UID` 值，除非该值为空。
默认值为 `NONE`。
+ **`PWD`** 或 **`SecretKey`**：AWS 用户秘密访问密钥。如果连接字符串中同时提供 `PWD` 和 `SecretKey`，则将使用带 的 `PWD` 值，除非该值为空。
默认值为 `NONE`。
+ **`SessionToken`**：访问已启用多重身份验证（MFA）的数据库所需的临时会话令牌。请勿在输入中包含尾随 ` = `。
默认值为 `NONE`。
**适用于 Okta 的基于 SAML 的身份验证选项**
+ **`IdPHost`**：指定 IdP 的主机名。
默认值为 `NONE`。
+ **`UID`** 或 **`IdPUserName`**：指定 IdP 账户的用户名。如果连接字符串中同时提供 `UID` 和 `IdPUserName`，则将使用 `UID` 值，除非该值为空。
默认值为 `NONE`。
+ **`PWD`** 或 **`IdPPassword`**：指定 IdP 账户的密码。如果连接字符串中同时提供 `PWD` 和 `IdPPassword`，则将使用 `PWD` 值，除非该值为空。
默认值为 `NONE`。
+ **`OktaApplicationID`**— Okta 提供的与应用程序关联的唯一 ID。 AWS IoT SiteWise 在应用程序元数据中提供的`entityID`字段中可以找到应用程序 ID (AppId)。例如：
```
entityID="http://www.okta.com//(IdPAppID)
```
默认值为 `NONE`。
+ **`RoleARN`**：调用方所代入角色的 Amazon 资源名称（ARN）。
默认值为 `NONE`。
+ **`IdPARN`**：描述 IdP 的 IAM 中 SAML 提供商的 Amazon 资源名称（ARN）。
默认值为 `NONE`。
**适用于 Azure Active Directory 的基于 SAML 的身份验证选项**
+ **`UID`** 或 **`IdPUserName`**：指定 IdP 账户的用户名。
默认值为 `NONE`。
+ **`PWD`** 或 **`IdPPassword`**：指定 IdP 账户的密码。
默认值为 `NONE`。
+ **`AADApplicationID`**：Azure AD 上已注册应用程序的唯一 ID。
默认值为 `NONE`。
+ **`AADClientSecret`**：与 Azure AD 上已注册应用程序关联的客户端密钥，用于授权获取令牌。
默认值为 `NONE`。
+ **`AADTenant`**：Azure AD 租户 ID。
默认值为 `NONE`。
+ **`RoleARN`**：调用方所代入角色的 Amazon 资源名称（ARN）。
默认值为 `NONE`。
+ **`IdPARN`**：描述 IdP 的 IAM 中 SAML 提供商的 Amazon 资源名称（ARN）。
默认值为 `NONE`。
**AWS SDK（高级）选项**
+ **`RequestTimeout`**— AWS SDK 在超时之前等待查询请求的时间（以毫秒为单位）。任何非正值都表示禁用请求超时。
默认值为 `3000`。
+ **`ConnectionTimeout`**— AWS SDK 在超时之前等待通过打开的连接传输数据的时间（以毫秒为单位）。值为 0 时，将禁用连接超时。该值不得为负。
默认值为 `1000`。
+ **`MaxRetryCountClient`**：SDK 中可重试错误（错误代码为 5xx）的最大重试次数。值不得为负。
默认值为 `0`。
+ **`MaxConnections`**— 允许与该 AWS IoT SiteWise 服务同时打开的 HTTP 连接的最大数量。值必须为正。
默认值为 `25`。
**ODBC 驱动程序日志记录选项**
+ **`LogLevel`**：驱动程序日志记录的日志级别。必须为以下值之一：
+ **0**：（关闭）。
+ **1**：（错误）。
+ **2**：（警告）。
+ **3**：（信息）。
+ **4**：（调试）。
默认为 `1`（错误）。
**警告：**使用调试日志记录模式时，驱动程序可能会记录个人信息。
+ **`LogOutput`**：用于存储日志文件的文件夹。
默认为：
+ **Windows：**`%USERPROFILE%`，或者如果不可用，则为 `%HOMEDRIVE%%HOMEPATH%`。
+ **macOS 和 Linux：**`$HOME`，或者如果不可用，则函数 `getpwuid(getuid())` 中的字段 `pw_dir` 返回值。
**SDK 日志记录选项**
S AWS DK 日志级别与 AWS IoT SiteWise ODBC 驱动程序日志级别是分开的。设置其中一个不会影响另一个。
SDK 日志级别使用环境变量 `SW_AWS_LOG_LEVEL` 进行设置。有效值为：
+ `OFF`
+ `ERROR`
+ `WARN`
+ `INFO`
+ `DEBUG`
+ `TRACE`
+ `FATAL`
如果未设置 `SW_AWS_LOG_LEVEL`，则将 SDK 日志级别设置为默认值，即 `WARN`。
## 通过代理进行连接
ODBC 驱动程序支持 AWS IoT SiteWise 通过代理进行连接。要使用此功能，请根据代理设置配置以下环境变量：
+ **`SW_PROXY_HOST`**：代理主机。
+ **`SW_PROXY_PORT`**：代理端口号。
+ **`SW_PROXY_SCHEME`**：代理方案，`http` 或 `https`。
+ **`SW_PROXY_USER`**：代理身份验证的用户名。
+ **`SW_PROXY_PASSWORD`**：代理身份验证的用户密码。
+ **`SW_PROXY_SSL_CERT_PATH`**：用于连接到 HTTPS 代理的 SSL 证书文件。
+ **`SW_PROXY_SSL_CERT_TYPE`**：代理客户端 SSL 证书的类型。
+ **`SW_PROXY_SSL_KEY_PATH`**：用于连接到 HTTPS 代理的私钥文件。
+ **`SW_PROXY_SSL_KEY_TYPE`**：用于连接到 HTTPS 代理的私钥文件类型。
+ **`SW_PROXY_SSL_KEY_PASSWORD`**：用于连接到 HTTPS 代理的私钥文件密码。
# AWS IoT SiteWise ODBC 驱动程序的连接字符串示例
## 使用 IAM 凭证连接到 ODBC 驱动程序的示例
```
Driver={AWS IoT SiteWise ODBC Driver};Auth=IAM;AccessKeyId=(your access key ID);SecretKey=(your secret key);SessionToken=(your session token);Region=us-east-1;
```
## 使用配置文件连接到 ODBC 驱动程序的示例
```
Driver={AWS IoT SiteWise ODBC Driver};ProfileName=(the profile name);region=us-east-1;
```
驱动程序将尝试使用 `~/.aws/credentials` 中提供的凭证进行连接，或者如果在环境变量 `AWS_SHARED_CREDENTIALS_FILE` 中指定文件，则使用该文件中的凭证进行连接。
## 使用 Okta 连接到 ODBC 驱动程序的示例
```
Driver={AWS IoT SiteWise ODBC Driver};Auth=OKTA;region=us-east-1;idPHost=(your host at Okta);idPUsername=(your user name);idPPassword=(your password);OktaApplicationID=(your Okta AppId);roleARN=(your role ARN);idPARN=(your Idp ARN);
```
## 使用 Azure Active Directory（AAD）连接到 ODBC 驱动程序的示例
```
Driver={AWS IoT SiteWise ODBC Driver};Auth=AAD;region=us-east-1;idPUsername=(your user name);idPPassword=(your password);aadApplicationID=(your AAD AppId);aadClientSecret=(your AAD client secret);aadTenant=(your AAD tenant);roleARN=(your role ARN);idPARN=(your idP ARN);
```
## 使用指定端点和日志级别 2（警告）连接到 ODBC 驱动程序的示例
```
Driver={AWS IoT SiteWise ODBC Driver};Auth=IAM;AccessKeyId=(your access key ID);SecretKey=(your secret key);EndpointOverride=iotsitewise.us-east-1.amazonaws.com;Region=us-east-1;LogLevel=2;
```
# 对 ODBC 驱动程序连接进行故障排除
**注意**
如果已在 DSN 中指定了用户名和密码，则在 ODBC 驱动程序管理器要求提供用户名和密码时，不要再次指定它们。
当连接字符串中多次传递连接字符串选项时，就会出现错误代码 `01S02` 并显示消息 `Re-writing (connection string option) (have you specified it several times?)`。多次指定同一选项将引发错误。使用 DSN 和连接字符串建立连接时，如果已在 DSN 中指定连接选项，则无需在连接字符串中再次指定。