",
transformationContext="datasource"
).getDynamicFrame()
val ruleset = """
Rules = [
(ColumnValues "age" >= 26) OR (ColumnLength "name" >= 4)
]
"""
val dq_results = EvaluateDataQuality.processRows(
frame=datasource,
ruleset=ruleset,
additionalOptions=JsonOptions("""
{
"compositeRuleEvaluation.method":"ROW"
}
"""
)
)
}
```
在 Amazon Glue Data Catalog 中，您可以在用户界面中轻松配置此选项，如下所示。
![\[屏幕截图显示了一个“复合规则设置”窗口，您可以在其中选择行和列之间的规则评估配置。如果选择“行”，复合规则将作为评估整行的单个规则运行。如果选择“列”，则复合规则将评估整个数据集中的各个规则，然后将结果合并。\]](http://docs.amazonaws.cn/glue/latest/dg/images/composite-rule-settings.png)
设置完成后，复合规则将作为评估整行的单个规则运行。以下示例说明了此行为。
```
# Row Level outcome
+------+------+------------------------------------------------------------+---------------------------+
|myCol1|myCol2|DataQualityRulesPass |DataQualityEvaluationResult|
+------+------+------------------------------------------------------------+---------------------------+
|2 |1 |[(ColumnValues "myCol1" > 1) OR (ColumnValues "myCol2" > 2)]|Passed |
|0 |3 |[(ColumnValues "myCol1" > 1) OR (ColumnValues "myCol2" > 2)]|Passed |
+------+------+------------------------------------------------------------+---------------------------+
```
此功能不支持某些规则，因为其总体结果依赖阈值或比率。不支持的规则列举如下。
依赖比率的规则：
+ 完整性
+ DatasetMatch
+ ReferentialIntegrity
+ 独特性
依赖阈值的规则：
当以下规则包含阈值时，则不支持这些规则。但是，不涉及 `with threshold` 的规则仍受支持。
+ ColumnDataType
+ ColumnValues
+ CustomSQL
### Expressions
如果规则类型不生成布尔响应，则必须提供表达式作为参数才能创建布尔响应。例如，以下规则根据表达式检查列中所有值的均值（平均值），以返回真或假结果。
```
Mean "colA" between 80 and 100
```
某些规则类型（例如 `IsUnique` 和 `IsComplete`）已经返回布尔响应。
下表列出了您可在 DL 规则中使用的表达式。
**支持的 DQDL 表达式**
| Expression | 说明 | 示例 |
| --- | --- | --- |
| =x | 如果规则类型响应等于 x，则解析为 true。 | Completeness "colA" = "1.0",
ColumnValues "colA" = "2022-06-30"
|
| \$1=x | x 如果规则类型响应不等于 x，则解析为 true。 | ColumnValues "colA" != "a",
ColumnValues "colA" != "2022-06-30"
|
| > x | 如果规则类型响应大于 x，则解析为 true。 | ColumnValues "colA" > 10
|
| < x | 如果规则类型响应小于 x，则解析为 true。 | ColumnValues "colA" < 1000,
ColumnValues "colA" < "2022-06-30"
|
| >= x | 如果规则类型响应大于 x，则解析为 true。 | ColumnValues "colA" >= 10
|
| <= x | 如果规则类型响应小于或等于 x，则解析为 true。 | ColumnValues "colA" <= 1000
|
| 介于 x 与 y 之间 | 如果规则类型响应在指定范围内（不包括），则解析为 true。仅将此表达式类型用于数字和日期类型。 | Mean "colA" between 8 and 100,
ColumnValues "colA" between "2022-05-31" and "2022-06-30"
|
| not between x and y | 如果规则类型响应不在指定范围内（包括首尾数），则解析为 true。您只能将此表达式类型用于数字和日期类型。 | ColumnValues "colA" not between "2022-05-31" and "2022-06-30"
|
| 在 [a, b, c, ...] 中 | 如果规则类型响应在指定的集合中，则解析为 true。 | ColumnValues "colA" in [ 1, 2, 3 ],
ColumnValues "colA" in [ "a", "b", "c" ]
|
| not in [a, b, c, ...] | 如果规则类型响应不在指定的集合中，则解析为 true。 | ColumnValues "colA" not in [ 1, 2, 3 ],
ColumnValues "colA" not in [ "a", "b", "c" ]
|
| 匹配 /ab\$1c/i | 如果规则类型响应与正则表达式匹配，则解析为 true。 | ColumnValues "colA" matches "[a-zA-Z]*"
|
| not matches /ab\$1c/i | 如果规则类型响应与正则表达式不匹配，则解析为 true。 | ColumnValues "colA" not matches "[a-zA-Z]*"
|
| now() | 仅适用于创建日期表达式的 ColumnValues 规则类型。 | ColumnValues "load_date" > (now() - 3 days)
|
| matches/in […]/not matches/not in [...] with threshold | 指定符合规则条件的值的百分比。仅适用于 ColumnValues、ColumnDataType 和 CustomSQL 规则类型。 | ColumnValues "colA" in ["A", "B"] with threshold > 0.8,
ColumnValues "colA" matches "[a-zA-Z]*" with threshold between 0.2 and 0.9
ColumnDataType "colA" = "Timestamp" with threshold > 0.9
|
#### NULL、EMPTY 和 WHITESPACE\$1ONLY 的关键字
如果要验证字符串列是否为零、空或属于仅包含空格的字符串，则可以使用以下关键字：
+ NULL/null – 对于字符串列中的 `null` 值，此关键字解析为 true。
如果超过 50% 的数据没有零值，则 `ColumnValues "colA" != NULL with threshold > 0.5` 将返回 true。
对于所有具有零值或长度大于 5 的行，`(ColumnValues "colA" = NULL) or (ColumnLength "colA" > 5)` 都将返回 true。*请注意，这将需要使用“compositeRuleEvaluation.method” = “ROW”选项。*
+ EMPTY/empty – 对于字符串列中的空字符串（“”）值，此关键字将解析为 true。某些数据格式会将字符串列中的零值转换为空字符串。此关键字有助于过滤掉数据中的空字符串。
如果一行为空、“a”或“b”，`(ColumnValues "colA" = EMPTY) or (ColumnValues "colA" in ["a", "b"])` 将返回 true。*请注意，这需要使用“compositeRuleEvaluation.method” = “ROW”选项。*
+ WHITESPACES\$1ONLY /whitespaces\$1only – 对于字符串列中只有空格（“ ”）值的字符串，此关键字解析为 true。
如果一行既不是“a”或“b”，也不只是空格，`ColumnValues "colA" not in ["a", "b", WHITESPACES_ONLY]` 将返回 true。
支持的规则：
+ [ColumnValues](https://docs.amazonaws.cn/glue/latest/dg/dqdl.html#dqdl-rule-types-ColumnValues)
对于基于数值或日期的表达式，如果要验证列是否包含零值，则可以使用以下关键字。
+ NULL/null – 对于字符串列中的零值，此关键字解析为 true。
如果列中的日期为 `2023-01-01` 或零，`ColumnValues "colA" in [NULL, "2023-01-01"]` 将返回 true。
对于所有具有零值或值介于 1 到 9 之间的行，`(ColumnValues "colA" = NULL) or (ColumnValues "colA" between 1 and 9)` 都将返回 true。*请注意，这将需要使用“compositeRuleEvaluation.method” = “ROW”选项。*
支持的规则：
+ [ColumnValues](https://docs.amazonaws.cn/glue/latest/dg/dqdl.html#dqdl-rule-types-ColumnValues)
#### 使用 Where 子句进行筛选
**注意**
仅 Amazon Glue 4.0 中支持 Where 子句。
您可以在编写规则时筛选数据。当您想要应用条件规则时，这会很有用。
```
where " "
```
必须使用 `where` 关键字指定筛选条件，后跟一个用引号 `("")` 括起有效 SparkSQL 语句。
如果您希望将 where 子句添加到具有阈值的规则中，则应在指定阈值条件之前指定 where 子句。
```
where "valid SparkSQL statement>" with threshold
```
您可以使用此语法编写如下规则。
```
Completeness "colA" > 0.5 where "colB = 10"
ColumnValues "colB" in ["A", "B"] where "colC is not null" with threshold > 0.9
ColumnLength "colC" > 10 where "colD != Concat(colE, colF)"
```
我们将验证所提供的 SparkSQL 语句是否有效。如果无效，规则评估将失败，我们将按照以下格式引发 `IllegalArgumentException`：
```
Rule where "" has provided an invalid where clause :
```
**启用行级错误记录识别时的 where 子句行为**
借助 Amazon Glue 数据质量自动监测功能，您可以识别失败的特定记录。将 where 子句应用于支持行级结果的规则时，我们会将 where 子句筛选出的行标记为 `Passed`。
如果您希望将筛选出的行单独标记为 `SKIPPED`，则可以为 ETL 作业设置以下 `additionalOptions`。
```
object GlueApp {
val datasource = glueContext.getCatalogSource(
database="",
tableName="",
transformationContext="datasource"
).getDynamicFrame()
val ruleset = """
Rules = [
IsComplete "att2" where "att1 = 'a'"
]
"""
val dq_results = EvaluateDataQuality.processRows(
frame=datasource,
ruleset=ruleset,
additionalOptions=JsonOptions("""
{
"rowLevelConfiguration.filteredRowLabel":"SKIPPED"
}
"""
)
)
}
```
请参阅以下规则和数据框作为示例：
```
IsComplete att2 where "att1 = 'a'"
```
| id | att1 | att2 | 行级结果（默认） | 行级结果（跳过的选项） | 评论 |
| --- | --- | --- | --- | --- | --- |
| 1 | a | f | PASSED | PASSED | |
| 2 | b | d | PASSED | SKIPPED | 行已被筛选出，因为 att1 不是 "a" |
| 3 | a | null | FAILED | FAILED | |
| 4 | a | f | PASSED | PASSED | |
| 5 | b | null | PASSED | SKIPPED | 行已被筛选出，因为 att1 不是 "a" |
| 6 | a | f | PASSED | PASSED | |
### 常量
在 DQDL 中，您可以定义常量值并在整个脚本中引用这些值。这有助于防止与查询大小限制相关的问题，例如，在处理可能超出允许范围的大型 SQL 语句时。通过将这些值分配给常量，可以简化 DQDL 并避免达到这些限制。
以下示例演示了如何定义并使用常量：
```
mySql = "select count(*) from primary"
Rules = [
CustomSql $mySql between 0 and 100
]
```
在此示例中，将 SQL 查询分配给常量 `mySql`，然后使用 `$` 前缀在规则中引用该常量。
### 标签
标签为组织和分析数据质量结果提供了一种有效的方法。可以按特定标签查询结果，进而识别特定类别中的失败规则，按团队或域统计规则结果，并为不同的利益相关者创建有针对性的报告。
例如，可以使用标签 `"team=finance"` 应用与财务团队有关的所有规则，并生成自定义报告来展示财务团队特定的质量指标。可以将高优先级规则标注为 `"criticality=high"`，进而确定补救工作的优先级。标签可以作为 DQDL 的一部分创作。可以将标签作为规则结果、行级结果和 API 响应的一部分进行查询，从而轻松地与现有的监控和报告工作流程集成。
**注意**
标签仅在 Amazon Glue ETL 中可用，在基于 Amazon Glue Data Catalog 的数据质量自动监测功能中不可用。
#### DQDL 标签的语法
DQDL 支持默认标签和特定于规则的标签。默认标签是在规则集级别定义的，并自动应用于该规则集中的所有规则。各个规则也可以有自己的标签，并且由于标签是作为键值对实现的，因此在使用相同的键时，特定于规则的标签可以覆盖默认标签。
以下示例演示了如何使用默认和特定于规则的标签：
```
DefaultLabels=["frequency"="monthly"]
Rules = [
// Auto includes the default label ["frequency"="monthly"]
ColumnValues "col" > 21,
// Add ["foo"="bar"] to default label. Labels for this rule would be ["frequency"="monthly", "foo"="bar"]
Rule 1 with threshold > 0.8 labels=["foo"="bar"],
// Override default label. Labels for this rule would be ["frequency"="daily", "foo"="bar"]
Rule 2 with threshold > 0.8 labels=["foo"="bar", "frequency"="daily"]
// Labels must be applied to the entire composite rule (parentheses required)
(Rule 1 AND Rule 2) labels=["foo"="bar]
]
```
##### 标签约束
标签具有以下约束：
+ 每个 DQDL 规则最多有 10 个标签。
+ 标签被指定为键值对列表。
+ 标签键和标签值区分大小写。
+ 标签键的最大长度是 128 个字符。标签键不得为空或为 null。
+ 标签值的最大长度是 256 个字符。标签值可以为空或为 null。
#### 检索 DQDL 标签
可以从规则结果、行级结果和 API 响应中检索 DQDL 标签。
##### 规则结果
DQDL 标签在规则结果中始终可见。无需额外配置即可启用这些标签。
##### 行级结果
默认情况下，行级结果中的 DQDL 标签处于禁用状态，但可以使用 `EvaluateDataQuality` 中的 `AdditionalOptions` 启用。
以下示例演示了如何在行级结果中启用标签：
```
val evaluateResult = EvaluateDataQuality.processRows(
frame=AmazonS3_node1754591511068,
ruleset=example_ruleset,
publishingOptions=JsonOptions("""{
"dataQualityEvaluationContext": "evaluateResult",
"enableDataQualityCloudWatchMetrics": "true",
"enableDataQualityResultsPublishing": "true"
}"""),
additionalOptions=JsonOptions("""{
"performanceTuning.caching":"CACHE_NOTHING",
"observations.scope":"ALL",
"rowLevelConfiguration.ruleWithLabels":"ENABLED"
}""")
)
```
启用后，行级结果数据框将包含 `DataQualityRulesPass`、`DataQualityRulesFail` 和 `DataQualityRulesSkip` 列中每条规则的标签。
##### API 响应
DQDL 标签在 API 响应中 `RuleResults` 对象的新字段 `Labels` 下始终可见。
以下示例演示了 API 响应中的标签：
```
{
"ResultId": "dqresult-example",
"ProfileId": "dqprofile-example",
"Score": 0.6666666666666666,
"RulesetName": "EvaluateDataQuality_node1754591514205",
"EvaluationContext": "EvaluateDataQuality_node1754591514205",
"StartedOn": "2025-08-22T19:36:10.448000+00:00",
"CompletedOn": "2025-08-22T19:36:16.368000+00:00",
"JobName": "anniezc-test-labels",
"JobRunId": "jr_068f6d7a45074d9105d14e4dee09db12c3b95664b45f6ee44fa29ed7e5619ba8",
"RuleResults": [
{
"Name": "Rule_0",
"Description": "IsComplete colA",
"EvaluationMessage": "Input data does not include column colA!",
"Result": "FAIL",
"EvaluatedMetrics": {},
"EvaluatedRule": "IsComplete colA",
"Labels": {
"frequency": "monthly"
}
},
{
"Name": "Rule_1",
"Description": "Rule 1 with threshold > 0.8",
"Result": "PASS",
"EvaluatedMetrics": {},
"EvaluatedRule": "Rule 1 with threshold > 0.8",
"Labels": {
"frequency": "monthly",
"foo": "bar"
}
},
{
"Name": "Rule_3",
"Description": "Rule 2 with threshold > 0.8",
"Result": "PASS",
"EvaluatedMetrics": {},
"EvaluatedRule": "Rule 2 with threshold > 0.8",
"Labels": {
"frequency": "daily",
"foo": "bar"
}
}
]
}
```
### 动态规则
**注意**
动态规则仅在 Amazon Glue ETL 中受支持，在 Amazon Glue Data Catalog 中不受支持。
现在，您可以编写动态规则，将规则生成的当前指标与其历史值进行比较。这些历史比较通过在表达式中使用 `last()` 运算符启用。例如，当前运行中的行数大于同一数据集之前最近一次的行数时，`RowCount > last()` 规则就会成功。`last()` 采用一个可选的自然数参数，描述要考虑的先前指标数量；`k >= 1` 将引用的最后一个 `k` 指标 `last(k)`。
+ 如果没有可用的数据点，`last(k)` 将返回默认值 0.0。
+ 如果少于可用的 `k` 指标，则 `last(k)` 将返回所有之前的指标。
要形成有效的表达式，请使用 `last(k)`，其中 `k > 1` 需要聚合函数以将多个历史结果简化为单个数字。例如，`RowCount > avg(last(5))` 将检查当前数据集的行数是否严格大于同一数据集最后五行计数的平均值。`RowCount > last(5)` 将产生错误，因为无法将当前数据集的行数与列表进行有意义的比较。
支持的聚合函数：
+ `avg`
+ `median`
+ `max`
+ `min`
+ `sum`
+ `std`（标准偏差）
+ `abs`（绝对值）
+ `index(last(k), i)` 将允许从最后一个 `k` 中选择第 `i` 最新的值。`i` 为零索引，因此 `index(last(3), 0)` 将返回最新的数据点，并且 `index(last(3), 3)` 将导致错误，因为只有三个数据点，而我们尝试编制第四最新数据点的索引。
**示例表达式**
**ColumnCorrelation**
+ `ColumnCorrelation "colA" "colB" < avg(last(10))`
**DistinctValuesCount**
+ `DistinctValuesCount "colA" between min(last(10))-1 and max(last(10))+1`
大多数具有数字条件或阈值的规则类型都支持动态规则；请参阅提供的[分析器和规则](#dqdl-analyzers-table)表，以确定您的规则类型是否支持动态规则。
**从动态规则中排除统计信息**
有时，您需要从动态规则计算中排除数据统计信息。假设您加载了历史数据，但不希望其影响您的平均值。为此，请在 Amazon Glue ETL 中打开作业并选择**数据质量**选项卡，然后依次选择**统计信息**和要排除的统计信息。您将能够看到趋势图和统计表。选择要排除的值，然后选择**排除统计信息**。排除的统计信息将不会包含在动态规则计算中。
![\[屏幕截图显示选择统计信息后从下拉菜单中排除或包含统计信息的选项。\]](http://docs.amazonaws.cn/glue/latest/dg/images/data-quality-excluding-statistics-from-dynamic-rules.png)
### 分析器
**注意**
Amazon Glue Data Catalog 不支持分析器。
DQDL 规则使用名为*分析器*的功能收集有关您的数据的信息。规则的布尔表达式使用此信息确定规则应该成功还是失败。例如，RowCount 规则 `RowCount > 5 ` 将使用行计数分析器发现数据集中的行数，并将其与表达式 `> 5` 进行比较，以检查当前数据集中是否存在超过五行。
有时，我们建议创建分析器（而不是编写规则），然后让其生成可用于检测异常的统计信息。对于此类实例，您可以创建分析器。分析器在以下方面与规则不同。
| 特征 | 分析器 | Rules |
| --- | --- | --- |
| 规则集的一部分 | 支持 | 是 |
| 生成统计信息 | 支持 | 是 |
| 生成观测值 | 支持 | 是 |
| 可以评估和断言条件 | 否 | 是 |
| 您可以配置操作，例如在失败时停止作业、继续处理作业 | 否 | 是 |
分析器无需规则即可独立存在，因此您可以快速配置分析器并逐步构建数据质量规则。
可以在规则集的 `Analyzers` 块中输入某些规则类型，以运行分析器所需的规则并收集信息，而无需对任何条件进行检查。有些分析器与规则无关，只能在 `Analyzers` 块中输入。下表显示每个项目是作为规则还是作为独立分析器支持，以及每种规则类型的其他详细信息。
**带分析器的示例规则集**
以下规则集使用：
+ 一条动态规则，用于检查数据集在过去三次作业运行中，是否增长超过其尾随平均值
+ `DistinctValuesCount` 分析器，用于记录数据集 `Name` 列中不同值的数量
+ `ColumnLength` 分析器，用于跟踪一段时间内最小和最大 `Name` 大小
可以在作业运行的“数据质量”选项卡中，查看分析器指标结果。
```
Rules = [
RowCount > avg(last(3))
]
Analyzers = [
DistinctValuesCount "Name",
ColumnLength "Name"
]
```
Amazon Glue 数据质量自动监测功能支持以下分析器。
| 分析器名称 | 功能 |
| --- | --- |
| RowCount | 计算数据集的行数 |
| Completeness | 计算列的完整性百分比 |
| Uniqueness | 计算列的唯一性百分比 |
| Mean | 计算数字列的平均值 |
| Sum | 计算数字列的总和 |
| StandardDeviation | 计算数字列的标准差 |
| Entropy | 计算数字列的熵 |
| DistinctValuesCount | 计算列中独特值的数量 |
| UniqueValueRatio | 计算列中的唯一值比率 |
| ColumnCount | 计算数据集中的列数 |
| ColumnLength | 计算列的长度 |
| ColumnValues | 计算数字列的最小值和最大值。计算非数字列的最小列长和最大列长 |
| ColumnCorrelation | 计算给定列的列相关性 |
| CustomSql | 计算 CustomSQL 返回的统计信息 |
| AllStatistics | 计算以下统计信息：[\[See the AWS documentation website for more details\]](http://docs.amazonaws.cn/glue/latest/dg/dqdl.html) |
### 评论
您可以使用“\$1”字符在 DQDL 文档中添加注释。DQDL 会忽略在“\$1”字符之后以及直到行尾的任何内容。
```
Rules = [
# More items should generally mean a higher price, so correlation should be positive
ColumnCorrelation "price" "num_items" > 0
]
```