",
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"
}
"""
)
)
}
```
AWS Glue Data Catalog では、次に示すように、ユーザーインターフェイスでこのオプションを簡単に設定できます。
![\[このスクリーンショットは、行と列の間でルール評価設定を選択できる複合ルール設定ウィンドウを示しています。[行] を選択した場合、複合ルールは行全体を評価する単一のルールとして動作します。[列] を選択した場合、複合ルールはデータセット全体の個々のルールを評価し、結果を結合します。\]](http://docs.aws.amazon.com/ja_jp/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 |
+------+------+------------------------------------------------------------+---------------------------+
```
一部のルールは全体的な結果がしきい値または比率に依存するため、この機能ではサポートできません。以下に一覧表示します。
比率に依存するルール:
+ Completeness
+ DatasetMatch
+ ReferentialIntegrity
+ Uniqueness
しきい値に依存するルール:
次のルールにしきい値が含まれる場合、ルールはサポートされません。ただし、`with threshold` に関連しないルールは引き続きサポートされます。
+ ColumnDataType
+ ColumnValues
+ CustomSQL
### 表現
ルールタイプがブール型で応答を生成しない場合、この応答を取得するには、パラメータで表現を指定する必要があります。例えば、次のルールでは、表現に対応させながら列内のすべての値の mean 値 (平均) をチェックし、真または偽の結果を返します。
```
Mean "colA" between 80 and 100
```
一部のルールタイプ (`IsUnique` や `IsComplete` など) は、既にブール型の応答を返しています。
次の表に、DQDL ルールで使用できる式を一覧で示します。
**サポートされている DQDL 表現**
| 式 | 説明 | 例 |
| --- | --- | --- |
| =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
|
| between x and y | ルールタイプの応答が指定された範囲内 (除外) にある場合、true を返します。この式のタイプは、数値および日付タイプにのみ使用できます。 | Mean "colA" between 8 and 100,
ColumnValues "colA" between "2022-05-31" and "2022-06-30"
|
| x と y の間ではない | ルールタイプの応答が指定された範囲外 (含有) にある場合、true を返します。この式のタイプは、数値および日付のタイプにのみ使用できます。 | ColumnValues "colA" not between "2022-05-31" and "2022-06-30"
|
| in [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" ]
|
| matches /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、WHITESPACES\$1ONLY のキーワード
文字列の列に null、空、空白のみの文字列があるかどうかを検証する場合、次のキーワードを使用できます。
+ NULL / null – 文字列の列の `null` 値には、このキーワードは true を返します。
50% 以上のデータに null 値が含まれていない場合、`ColumnValues "colA" != NULL with threshold > 0.5` は true を返します。
null 値または長さが 5 を超えるすべての行に対し、`(ColumnValues "colA" = NULL) or (ColumnLength "colA" > 5)` は true を返します。これには、「compositeRuleEvaluation.Method」=「ROW」オプションを使用する必要があることに注意してください。
+ EMPTY / empty – 文字列の列に空の文字列 (“”) の値には、このキーワードは true を返します。一部のデータ形式は、文字列の列に null を空の文字列に変換します。このキーワードは、データの空の文字列を除外するのに便利です。
行が空、「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.aws.amazon.com/glue/latest/dg/dqdl.html#dqdl-rule-types-ColumnValues)
数値または日付ベースの式には、列に null があるかどうかを検証する場合、次のキーワードを使用できます。
+ NULL / null – 文字列の列の null 値には、このキーワードは true を返します。
列の日付が `2023-01-01` または null の場合、`ColumnValues "colA" in [NULL, "2023-01-01"]` は true を返します。
null 値または 1 から 9 までの値が含まれているすべての行に対し、`(ColumnValues "colA" = NULL) or (ColumnValues "colA" between 1 and 9)` は true を返します。これには、「compositeRuleEvaluation.Method」=「ROW」オプションを使用する必要があることに注意してください。
サポートされているルール:
+ [ColumnValues](https://docs.aws.amazon.com/glue/latest/dg/dqdl.html#dqdl-rule-types-ColumnValues)
#### Where 句によるフィルタリング
**注記**
Where 句は AWS Glue 4.0 でのみサポートされています。
ルールの作成時にデータをフィルタリングできます。これは、条件付きルールを適用する場合に便利です。
```
where " "
```
フィルターは `where` キーワード、その後に引用符 `("")` で囲まれた有効な Spark SQL ステートメントを指定する必要があります。
しきい値を持つルールに 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)"
```
提供された Spark SQL ステートメントが有効であることを検証します。無効な場合、ルールの評価は失敗し、次の形式の `IllegalArgumentException` がスローされます。
```
Rule where "" has provided an invalid where clause :
```
**行レベルのエラーレコード識別が有効になっている場合の句の動作**
AWS Glue Data Quality を使用すると、失敗した特定のレコードを識別できます。行レベルの結果をサポートするルールに 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 | ある | f | PASSED | PASSED | |
| 2 | b | d | PASSED | SKIPPED | att1 は "a" ではないため、行はフィルターで除外されます |
| 3 | ある | null | FAILED | FAILED | |
| 4 | ある | f | PASSED | PASSED | |
| 5 | b | null | PASSED | SKIPPED | att1 は "a" ではないため、行はフィルターで除外されます |
| 6 | ある | 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 レスポンスの一部としてラベルをクエリできるため、既存のモニタリングおよびレポートワークフローとの統合が容易になります。
**注記**
ラベルは AWS Glue ETL でのみ使用でき、AWS Glue Data Catalog ベースの Data Quality では利用できません。
#### 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 ラベルは、`RuleResults` オブジェクトの新しいフィールド `Labels` の下の API レスポンスに常に表示されます。
以下に 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"
}
}
]
}
```
### 動的ルール
**注記**
動的ルールは AWS Glue ETL でのみサポートされており、 AWS Glue Data Catalog ではサポートされていません。
動的ルールを作成して、ルールによって生成された現在のメトリクスと履歴値を比較できるようになりました。これらの履歴比較は、式に `last()` 演算子を使用することで可能になります。例えば、現在の実行で行数が同じデータセットの最新の行数よりも多い場合、`RowCount > last()` ルールは成功します。`last()` は、考慮すべき事前メトリクスの数を記述する自然数引数をオプションで取り、`last(k)` では `k >= 1` が直近の `k` メトリクスを参照します。
+ データポイントがない場合、`last(k)` はデフォルト値 0.0 を返します。
+ 利用可能な `k` メトリクスよりも少ない場合は、`last(k)` はそれ以前のメトリクスをすべて返します。
有効な式を作成するには `last(k)` を使用します。`k > 1` では、複数の履歴結果を 1 つの数値にまとめる集計関数が必要です。例えば `RowCount > avg(last(5))` は、現在のデータセットの行数が、同じデータセットの直近の 5 つの行数の平均より真に大きいかどうかを確認します。現在のデータセットの行数をリストと有意に比較できないため、`RowCount > last(5)` はエラーを生成します。
サポートされている集計関数:
+ `avg`
+ `median`
+ `max`
+ `min`
+ `sum`
+ `std` (標準偏差)
+ `abs` (絶対値)
+ `index(last(k), i)` では直近の `k` から `i` 番目に新しい値を選択できます。`i` はゼロインデックスであるため、`index(last(3), 0)` は最新のデータポイントを返しますが、データポイントが 3 つしかなく、4 番目に新しいデータポイントにインデックスを付けようとするため、`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)」の表を参照してください。
**動的ルールからの統計の除外**
場合によっては、動的ルール計算からデータ統計を除外する必要があります。履歴データのロードを行い、それを平均値に影響を与えたくないとします。これを行うには、AWS Glue ETL でジョブを開き、**[データの品質]** タブを選択し、**[統計]** を選択し、除外する統計を選択します。統計の表とともにトレンドチャートを表示できます。除外する値を選択し、**[統計を除外]** を選択します。これで、除外された統計は動的ルール計算に含まれなくなります。
![\[このスクリーンショットは、統計を選択した後にドロップダウンメニューから統計を除外または含めるオプションを示しています。\]](http://docs.aws.amazon.com/ja_jp/glue/latest/dg/images/data-quality-excluding-statistics-from-dynamic-rules.png)
### アナライザー
**注記**
アナライザーは、AWS Glue Data Catalog ではサポートされていません。
DQDL ルールは、アナライザーと呼ばれる関数を使用してデータに関する情報を収集します。この情報をルールのブール式に使用して、ルールが成功するか失敗するかを決定します。例えば、RowCount ルール `RowCount > 5 ` は、行数アナライザーを使用してデータセット内の行数を検出し、その数を式 `> 5` と比較して、現在のデータセットに 5 行以上存在するかどうかを確認します。
ルールを作成する代わりに、アナライザーを作成して、異常の検出に使用できる統計を生成させることを推奨する場合があります。このような場合は、アナライザーを作成できます。アナライザーは、次の点でルールとは異なります。
| 特性 | アナライザー | Rules |
| --- | --- | --- |
| ルールセットの一部 | あり | はい |
| 統計を生成 | あり | はい |
| 観察結果を生成 | あり | はい |
| 条件を評価してアサートできる | いいえ | あり |
| 障害発生時にジョブを停止したり、ジョブの処理を続行したりするなどのアクションを設定できます。 | いいえ | あり |
アナライザーはルールなしで独立して存在できるため、アナライザーをすばやく構成し、データ品質ルールを段階的に構築できます。
ルールセットの `Analyzers` ブロックに入力できるルールタイプもあります。これにより、アナライザーに必要なルールを実行し、条件のチェックを行わずに情報を収集できます。アナライザーの中には、ルールに関連付けられておらず、`Analyzers` ブロックにしか入力できないものもあります。次の表は、各項目がルールとしてサポートされているか、スタンドアロンアナライザーとしてサポートされているか、および各ルールタイプの詳細を示しています。
**アナライザーを使用したルールセットの例**
以下のルールセットでは以下のものが使用されます。
+ 直近の 3 回のジョブ実行で、データセットが平均値を上回っているかどうかを確認する動的ルール
+ データセットの `Name` 列内の異なる値の数を記録する `DistinctValuesCount` アナライザー
+ `Name` の最小サイズと最大サイズを経時的に追跡する `ColumnLength` アナライザー
アナライザーメトリクスの結果は、ジョブ実行の [データ品質] タブで確認できます。
```
Rules = [
RowCount > avg(last(3))
]
Analyzers = [
DistinctValuesCount "Name",
ColumnLength "Name"
]
```
AWS Glue Data Quality は、次のアナライザーをサポートしています。
| アナライザー名 | 機能 |
| --- | --- |
| RowCount | データセットの行数を計算します |
| Completeness | 列の完全性の割合を計算します |
| Uniqueness | 列の一意性の割合を計算します |
| Mean | 数値列の平均を計算します |
| Sum | 数値列の合計を計算します |
| StandardDeviation | 数値列の標準偏差を計算します |
| Entropy | 数値列のエントロピーを計算します |
| DistinctValuesCount | 列内の個別値の数を計算します |
| UniqueValueRatio | 列内の一意の値の比率を計算します |
| ColumnCount | データセット内の列数を計算します |
| ColumnLength | 列の長さを計算します |
| ColumnValues | 数値列の最小値と最大値を計算します。数値列以外の最小の ColumnLength と最大の ColumnLength を計算します |
| ColumnCorrelation | 特定の列の列相関を計算します |
| CustomSql | カスタム SQL によって返される統計を計算します |
| AllStatistics | 次の統計を計算します: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/glue/latest/dg/dqdl.html) |
### コメント
「\$1」文字を使用して DQDL ドキュメントにコメントを追加できます。「\$1」文字の後から行末までに含まれるすべての文字は DQDL に無視されます。
```
Rules = [
# More items should generally mean a higher price, so correlation should be positive
ColumnCorrelation "price" "num_items" > 0
]
```