マップ関数 ​

Mapはキーと値のペアのセット、つまりJSONオブジェクト用のWEL型です。マップ関数は、そのキーと値の読み取り、あるマップと別のマップの結合、フィールドの削除、およびリスト関数が操作できるようにマップとリストの間の変換を行います。

キーは常にStringです。挿入順序は保持されるため、意図した順序で作成されたマップはその順序でシリアル化されます。

_ は、これらの例で式が受け取る入力です。詳細については、入力変数を参照してください。

マップ関数を呼び出す ​

関数を直接呼び出すか、>>を使用して値をパイプします:

keys(_.customer)
_.customer >> keys

フィールドはピリオド（.）で読み取ります。キーが計算される場合やベア識別子でない場合は、角かっこ（[]）を使用します。

_.customer.email
_.customer['email']

存在しないキーを読み取るとE104が発生します。最初にテストするにはhas_key?を使用し、デフォルトを指定するにはtry-fallback演算子|?を使用します。

_.customer.nickname |? 'none'

キーと値の読み取り ​

次の関数は、マップを変更せずにマップのキーと値を読み取ります。

keys ​

キーを挿入順序でリストとして返します。

keys(map)

keys({sku: 'WID-1', qty: 3})

["sku", "qty"]

values ​

値を挿入順序でリストとして返します。 Skipである値は省略されます。

values(map)

values({sku: 'WID-1', qty: 3})

["WID-1", 3]

has_key? ​

キーが存在する場合はtrueを返します。

キーのテストは、値のテストと同じではありません。 null値を持つキーが存在する場合、ここではtrueを返します。使用可能な値をテストするには、代わりにpresent?を使用します。

has_key?(map, key)

has_key?({sku: 'WID-1'}, 'sku')

true

has_key?({sku: 'WID-1'}, 'qty')

false

フィールドの選択 ​

次の関数は、マップをより小さく安全なフィールドのセットに絞り込みます。

pluck ​

指定されたキーのみを含むマップを返します。存在しないキーは、エラーを発生させるのではなくスキップされます。

これを使用して、大きな受信レコードを宛先が実際に受け入れるフィールドに絞り込みます。

pluck(map, keys)

pluck({id: 1, secret: 'x', name: 'a'}, ['id', 'name'])

{id: 1, name: "a"}

pluck({id: 1}, ['id', 'missing'])

{id: 1}

except ​

指定されたキーを削除したマップを返します。

pluckとexceptは反対の機能であり、安全性の観点ではどちらを選ぶかが重要です。 pluckは許可リストであるため、アップストリームに新しいフィールドが現れてもデフォルトで破棄されます。 exceptは拒否リストであるため、新しいフィールドはデフォルトで転送されます。新しく追加されたフィールドの漏えいが懸念される場合は、pluckを優先します。

except(map, keys)

except({id: 1, secret: 'x', name: 'a'}, ['secret'])

{id: 1, name: "a"}

ユースケース：転送前に機密フィールドを削除する ​

受信ユーザーレコードには、宛先システムに届くべきではない資格情報が含まれています。レコードを転送する前に機密フィールドを削除するには、exceptを使用します。

入力

{
  "user": {
    "id": "U-1",
    "email": "nur@example.com",
    "password": "hunter2",
    "ssn": "111-22-3333"
  }
}

Formula

_.user >> except(['password', 'ssn'])

出力

{"id": "U-1", "email": "nur@example.com"}

このexceptの使用は拒否リスト形式であり、ソースが送信できるすべてのフィールドを把握している間だけ安全です。ソースがフィールドを追加する可能性がある場合、pluck(['id', 'email'])は同じ意図を表すより安全な式です。

マップの結合 ​

次の関数は、2つのマップを1つに結合します。

merge ​

2つのマップを結合します。両方で同じキーが定義されている場合は、2番目が優先されます。

merge(first, second)

merge({sku: 'WID-1', qty: 1}, {qty: 5})

{sku: "WID-1", qty: 5}

ユースケース：デフォルトセットにオーバーライドを適用する ​

デフォルトのセットに呼び出し元が指定したオーバーライドを重ねて適用する必要があります。指定されたものはすべて優先され、省略されたものはフォールバックされます。 mergeでは、デフォルトを1番目に、呼び出し元の値を2番目に指定します。

入力

{
  "overrides": {"currency": "EUR", "notify": true}
}

Formula

merge(
  {currency: 'USD', locale: 'en-US', notify: false},
  _.overrides
)

出力

{"currency": "EUR", "locale": "en-US", "notify": true}

mergeは1つのレベルを結合します。 2番目の引数にあるネストされたマップは、対応するマップにマージされるのではなく、そのまま置き換えます。

マップとリストの間の変換 ​

これら4つの関数によって、マップはリスト関数に到達できます。 entriesとpairsは一方向に変換します。 from_entriesとfrom_pairsは元に戻します。

entries ​

マップを{key, value}マップのリストに変換します。

entries(map)

entries({sku: 'WID-1', qty: 3})

[{key: "sku", value: "WID-1"}, {key: "qty", value: 3}]

from_entries ​

{key, value}マップのリストをマップに戻します。 entriesの逆です。

from_entries(list)

from_entries([{key: 'sku', value: 'WID-1'}])

{sku: "WID-1"}

pairs ​

マップを2要素の[key, value]リストのリストに変換します。値がSkipであるペアは省略されます。

pairs(map)

pairs({sku: 'WID-1', qty: 3})

[["sku", "WID-1"], ["qty", 3]]

from_pairs ​

2要素の[key, value]リストのリストをマップに戻します。 pairsの逆です。

from_pairs(list)

from_pairs([['sku', 'WID-1']])

{sku: "WID-1"}

{a: 1, b: 2} >> filter_by((k, v) ~> v > 1)

ネストされたマップのフラット化 ​

次の関数は、ネストされたマップを単一レベルに折りたたみ、パスを1つのキーに結合します。

flatten_map ​

ネストされたマップを単一レベルに折りたたみ、パスを1つのキーに結合します。

走査は挿入順序で深さ優先です。マップのみが下位にたどられます。リストはリーフ値として扱われ、全体が保持されます。空のネストされたマップもリーフです。

2つのネストされたキーが、同じフラット化されたキーに折りたたまれることがあります。最後の書き込みが優先され、その場合はE229警告が発行されるため、競合はサイレントではなくジョブ内で確認できます。

flatten_map(map, options)

認識されないオプションキーは無視されず、E222を発生させます。

flatten_map({customer: {name: 'Nur', address: {city: 'London'}}})

{"customer.name": "Nur", "customer.address.city": "London"}

flatten_map({a: {b: 1}}, {sep: '_'})

{a_b: 1}

ユースケース：CSV行用にレコードをフラット化する ​

CSVの宛先ではフィールドごとに1つの列が必要ですが、ソースは2レベルの深さでネストされています。マップ関数を使用して、レコードを単一レベルにフラット化します。

入力

{
  "record": {
    "id": "C-1",
    "customer": {
      "name": "Nur",
      "address": {"city": "London", "postcode": "E1"}
    }
  }
}

Formula

_.record >> flatten_map

出力

{
  "id": "C-1",
  "customer.name": "Nur",
  "customer.address.city": "London",
  "customer.address.postcode": "E1"
}

フラット化されたキーは、宛先が期待する列ヘッダーそのものです。ターゲットがヘッダー名のドットを受け入れない場合は、{sep: '_'}を渡します。

関連情報 ​

• リスト関数：entries、pairs、keys、valuesで行うこと。
• ディープマップ関数：ネストをフラット化するのではなく、ネストをたどる。
• データ型：Map、Skip、null。
• エラーコード：E104、E222、E229などのジョブ失敗のトラブルシューティング。