データの参照元 — 「どこから来るか」
$states.input | このステートへの入力。基本はここから取り出す |
$states.result | 直前の Task / Map / Parallel の結果 |
$変数名 | Assign で持ち回る変数（例 $userId, $total） |
⚠ 裸の orderId は参照できない。必ず $states.input.orderId と書く（本番と同じ挙動）。
基本構文 — JSONata の骨格
.field | パスアクセス。ネストは a.b.c といくらでも深く |
array.field | 配列に . で全要素を自動射影（最重要） |
array[式] | フィルタ。[status="paid"] / index [0] / 末尾 [-1] |
array.{…} | 各要素をオブジェクトに変換（map）。中ではフィールド名を直接参照 |
{ "k": v } | オブジェクト構築 |
array^(f) | ソート。昇順 ^(age) / 降順 ^(>age) / 複数 ^(a,>b) |
array{k:v} | グルーピング（SQL の GROUP BY 相当） |
( $x := …; … ) | ブロック。:= でローカル変数を束縛し、最後の式が結果 |
演算子 — つまずきポイント
& | 文字列連結（+ ではない！） |
= | 等値比較（== ではない）。否定は != |
> < >= <= | 大小比較 |
cond ? a : b | 三項演算子（条件分岐） |
+ - * / % | 算術（数値のみ） |
よく使う関数
| 集計 | $sum $average $max $min $count |
| 配列 | $map $filter $reduce $sort $distinct $reverse $append $join $split |
| オブジェクト | $keys $lookup $merge $spread $each |
| 文字列 | $lowercase $uppercase $trim $substring $substringBefore/After $replace $contains $string |
| 数値・日時 | $number $round $floor $formatNumber $fromMillis $toMillis $now $millis |
| 存在判定 | $exists $type $not |
| 高階関数 | function($x){ … } を第2引数に渡す（例 $map(a, function($n){ $n*$n })） |
SFn 独自関数 — 旧 intrinsic の代替
標準 JSONata に Step Functions が追加した関数。JSONPath 時代の組み込み関数（intrinsics）の置き換え。
$parse | JSON 文字列を値に復元（= States.StringToJson／$eval の代替） |
$partition | 配列を指定サイズで分割（= States.ArrayPartition） |
$range | 連番の配列を生成（= States.ArrayRange） |
$hash | ハッシュ計算 MD5/SHA（= States.Hash） |
$random | 乱数。seed 引数つき（= States.MathRandom） |
$uuid | v4 UUID を生成（= States.UUID） |
⛔ 本番 Step Functions では使えない
標準 JSONata にはあるが、SFn のエンジン（仕様 2.0.6 準拠）は未対応。道場では動いても本番で落ちる。
$eval | JSON 文字列の評価は使えない → 代わりに $parse |
?? ?: | null合体 / Elvis 演算子は 2.1.0 追加のため未対応 → 代わりに $exists(x) ? x : 既定値 |