リスト関数 ​

リスト関数は順序付きコレクションを操作します。ほとんどの連携作業はリスト作業です。 webhookはレコードの配列を配信し、APIは結果のページを返し、宛先システムは異なる形状、異なる順序、または単一の集計数値を想定します。

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

リスト関数の呼び出し ​

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

count(_.line_items)
_.line_items >> count

リスト関数は連鎖に適しており、パイプ形式により複数ステップの変換を読みやすくできます:

_.orders >> filter_by(o ~> o.status == 'open') >> map_by(o ~> o.id)

Lambda ​

多くのリスト関数は、~>で記述された小さなインライン関数であるlambdaを受け取ります:

_.orders >> filter_by(order ~> order.total > 100)

~>の前のパラメーターには任意の名前を選択できます。これは一度に1つの要素を参照します。 2つ以上のパラメーターは括弧（()）で囲みます:

_.items >> map_with_index_by((item, index) ~> f"{index + 1}. {item.name}")

リストの検査 ​

次の関数はリストを変更せずに読み取ります:

count ​

要素数を返します。

count(list)

count(['SO-1', 'SO-2', 'SO-3'])

3

count([])

0

first ​

最初の要素を返します。リストが空の場合はnullを返します。

first(list)

first(['pending', 'shipped'])

保留中

first([])

null

last ​

最後の要素を返します。リストが空の場合はnullを返します。

last(list)

last(['pending', 'shipped'])

shipped

at ​

ゼロベースのインデックスにある要素を返します。負のインデックスは末尾から逆に数えます。

リスト範囲外のインデックスはE201を発生させます。末尾または先頭だけが必要な場合は、firstまたはlastを使用します。位置ではなく要素を検索するには、find_byを使用します。

at(list, index)

at(['pending', 'shipped', 'closed'], 0)

保留中

at(['pending', 'shipped', 'closed'], -1)

closed

one! ​

1要素のリストの単一要素を返し、それ以外の長さの場合はE204を発生させます。

アサーションとして使用します。 one!は、lookupが正確に1件のレコードに一致する必要がある場合に、「ゼロまたは多数」を、誤ったレコードで静かに処理を続行する変換ではなく、明確に失敗するジョブに変えます。

one!(list)

one!(['SO-1001'])

SO-1001

リストのテスト ​

次の関数は新しいリストを返すのではなく、リストに関する質問に答えます:

all? ​

すべての要素がpredicateを満たす場合にtrueを返します。空のリストはtrueを返します。

all?(list, predicate)

['open', 'open'] >> all?(s ~> s == 'open')

true

any? ​

少なくとも1つの要素がpredicateを満たす場合にtrueを返します。

any?(list, predicate)

[199, 42, 8] >> any?(n ~> n > 100)

true

find_by ​

predicateを満たす最初の要素を返します。該当するものがない場合はnullを返します。

find_by(list, predicate)

[{id: 1, sku: 'WID-1'}, {id: 2, sku: 'GAD-7'}] >> find_by(r ~> r.sku == 'GAD-7')

{id: 2, sku: "GAD-7"}

find_first_index ​

predicateを満たす最初の要素のゼロベースのインデックスを返します。該当するものがない場合は-1を返します。

find_first_index(list, predicate)

['a', 'b', 'c'] >> find_first_index(s ~> s == 'c')

2

['a', 'b'] >> find_first_index(s ~> s == 'z')

-1

要素の選択 ​

次の関数は元のリストから構築された短いリストを返します:

filter_by ​

predicateがtrueを返す要素を保持します。

Mapも受け取ります。その場合、lambdaはkeyとvalueの2つのパラメーターを受け取ります。結果もMapです。

filter_by(list, predicate)

[1, 2, 3, 4] >> filter_by(n ~> n > 2)

[3, 4]

take ​

最初のcount個の要素を返します。countが負の場合は最後のcount個の要素を返します。リストが保持する数より多く要求すると、エラーを発生させるのではなくリスト全体を返します。

take(list, count)

take(['a', 'b', 'c', 'd'], 2)

["a", "b"]

take(['a', 'b', 'c', 'd'], -2)

["c", "d"]

drop ​

最初のcount個の要素を削除します。countが負の場合は最後のcount個の要素を削除します。

drop(list, count)

drop(['a', 'b', 'c', 'd'], 2)

["c", "d"]

compact ​

nullとSkipの値を削除します。

一部の要素に対してのみ値を生成するmap_byの直後や、受信payloadから任意フィールドを取り除く場合に便利です。

compact(list)

compact(['a', null, 'b'])

["a", "b"]

unique ​

重複を削除し、各値の最初の出現を元の位置に保持します。

unique(list)

unique(['WID-1', 'GAD-7', 'WID-1'])

["WID-1", "GAD-7"]

unique_by ​

key関数で重複を削除し、各keyの最初の要素を保持します。

レコードで使用します。2つのエントリは、オブジェクト全体は異なっていても識別子を共有しているため「同じ」と見なされます。

unique_by(list, key)

[{sku: 'WID-1'}, {sku: 'WID-1'}] >> unique_by(r ~> r.sku)

[{sku: "WID-1"}]

ユースケース: webhookバッチから有効なレコードを保持 ​

webhookは、一部のレコードでメールアドレスが欠落し、1つの識別子が繰り返されるバッチを配信します。リスト関数を使用して、識別子ごとに1つのレコードを保持し、配信先のメールがないものを削除します:

入力

{
  "contacts": [
    {"id": "C-1", "email": "nur@example.com"},
    {"id": "C-2", "email": null},
    {"id": "C-1", "email": "nur@example.com"},
    {"id": "C-3", "email": "dana@example.com"}
  ]
}

Formula

_.contacts
  >> unique_by(c ~> c.id)
  >> filter_by(c ~> present?(c.email))
  >> map_by(c ~> c.email)

出力

["nur@example.com", "dana@example.com"]

unique_byはfilter_byの前に実行されるため、重複はメールアドレスの有無ではなくIDに基づいて削除されます。

要素の変換 ​

次の関数は同じ長さのリストを返すか、構造を変形します:

map_by ​

すべての要素にlambdaを適用し、結果を返します。

lambdaがSkipを返す要素は省略されるため、map_byは同じパスでフィルターと変換を実行できます。

map_by(list, transform)

[1, 2, 3] >> map_by(n ~> n * 2)

[2, 4, 6]

map_with_index_by ​

要素とそのゼロベースのインデックスを受け取る2パラメーターのlambdaを適用します。

map_with_index_by(list, transform)

['a', 'b'] >> map_with_index_by((s, i) ~> f"{i + 1}. {s}")

["1. a", "2. b"]

flatten ​

ネストを1レベルだけフラット化します。 2階層深くネストされたリストでは内側のリストが保持されるため、さらに進むにはflattenを再度呼び出します。

flatten(list)

flatten([[1, 2], [3]])

[1, 2, 3]

[[1, 2], [3, [4]]] >> flatten

[1, 2, 3, [4]]

zip ​

2つのリストの要素を2要素リストにペア化します。短い方のリストが長さを決定します。

zip(first, second)

zip(['sku', 'qty'], ['WID-1', 3])

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

zip(['a', 'b', 'c'], [1])

[["a", 1]]

reverse ​

要素の順序を反転します。

reverse(list)

reverse(['a', 'b', 'c'])

["c", "b", "a"]

リストの並べ替え ​

次の関数は、リストを昇順かつ安定的にソートします:

sort ​

昇順にソートします。ソートは安定しているため、比較で等しい要素は元の相対順序を保持します。

sort(list)

sort([3, 1, 2])

[1, 2, 3]

[3, 1, 2] >> sort >> reverse

[3, 2, 1]

sort_by ​

key関数で昇順かつ安定的にソートします。

降順のバリアントはありません。降順にするには、結果をreverseにパイプします。

sort_by(list, key)

[{n: 'b'}, {n: 'a'}] >> sort_by(r ~> r.n)

[{n: "a"}, {n: "b"}]

ユースケース: 上位3つの最大注文を取得 ​

レポートでは、バッチから抽出された上位3つの最大注文が必要です。昇順にソートし、反転してから先頭から取得します:

入力

{
  "orders": [
    {"id": "SO-1", "amount": 120},
    {"id": "SO-2", "amount": 940},
    {"id": "SO-3", "amount": 310},
    {"id": "SO-4", "amount": 75}
  ]
}

Formula

_.orders
  >> sort_by(o ~> o.amount)
  >> reverse
  >> take(3)
  >> map_by(o ~> o.id)

出力

["SO-2", "SO-3", "SO-1"]

グループ化と分割 ​

次の関数は、keyまたはpredicateに基づいてリストをグループまたは2つのバケットに分割します:

group_by ​

key関数の結果をkeyとするMapに要素をグループ化します。各値は、そのkeyを共有する要素のリストです。

group_by(list, key)

[{sku: 'WID-1', q: 1}, {sku: 'GAD-7', q: 2}, {sku: 'WID-1', q: 5}] >> group_by(r ~> r.sku)

{"WID-1": [{sku: "WID-1", q: 1}, {sku: "WID-1", q: 5}], "GAD-7": [{sku: "GAD-7", q: 2}]}

partition_by ​

リストを正確に2つのリストに分割します: predicateに一致する要素、その後に一致しない要素。

結果は常に2要素のリストなので、at(0)とat(1)で読み取ります。

partition_by(list, predicate)

[1, 2, 3, 4] >> partition_by(n ~> n > 2)

[[3, 4], [1, 2]]

[1, 2, 3, 4] >> partition_by(n ~> n > 2) >> at(0)

[3, 4]

ユースケース: バッチ結果を成功と失敗に分割 ​

bulk APIは、行ごとのステータスを持つレコードを行ごとに1件返します。 partition_byを使用してそれらを分割します。これにより、成功は続行し、失敗は再試行パスにルーティングできます:

入力

{
  "results": [
    {"id": "A", "status": "ok"},
    {"id": "B", "status": "error"},
    {"id": "C", "status": "ok"}
  ]
}

Formula

let parts = _.results >> partition_by(r ~> r.status == 'ok')
do {
  succeeded: parts >> at(0) >> map_by(r ~> r.id),
  failed: parts >> at(1) >> map_by(r ~> r.id)
}

出力

{"succeeded": ["A", "C"], "failed": ["B"]}

let … doは分割を1回だけバインドするため、リストは2回ではなく1回だけパーティション化されます。

集計 ​

次の関数はリストを1つの値に縮約します:

sum ​

数値要素を加算します。空のリストの合計は0です。

sum(list)

sum([12.50, 99.00])

111.5

sum([Decimal('12.50'), Decimal('99.00')])

111.50

sum([])

0

avg ​

数値要素の平均を返します。空のリストはE207を発生させます。何もないものの有意な平均は存在しないためです。

avg(list)

avg([10, 20, 30])

20

min ​

最小の要素を返します。数値だけでなく文字列にも対応します。

min(list)

min([5, 2, 9])

2

max ​

最大の要素を返します。数値だけでなく文字列にも対応します。

max(list)

max([5, 2, 9])

9

max(['apple', 'pear'])

pear

reduce_by ​

accumulatorを使用してリストを単一の値に畳み込みます。

結果が単純な合計ではない場合、たとえばMapの構築、連結、要素間での状態の保持などに使用します。単純な合計または平均の場合は、代わりにsumとavgを使用します。名前が意味を表しているためです。

reduce_by(list, initial, accumulate)

[1, 2, 3] >> reduce_by(0, (acc, n) ~> acc + n)

6

ユースケース: SKU別に注文を合計 ​

line itemは出荷ごとに1行で届くため、同じSKUが複数回表示されます。リスト関数を使用してそれらをグループ化し、それぞれの数量を合計します:

入力

{
  "line_items": [
    {"sku": "WID-1", "qty": 3},
    {"sku": "GAD-7", "qty": 1},
    {"sku": "WID-1", "qty": 2}
  ]
}

Formula

_.line_items
  >> group_by(li ~> li.sku)
  >> entries
  >> map_by(e ~> {key: e.key, value: e.value >> map_by(r ~> r.qty) >> sum})
  >> from_entries

出力

{"WID-1": 5, "GAD-7": 1}

group_byはリストのMapを生成します。 entriesはそれを{key, value}ペアのリストに変換し、各グループを合計できるようにします。その後、from_entriesがそれを元に戻します。両方については、Map関数を参照してください。

リストの生成 ​

次の関数は既存のリストを変換するのではなく、新しいリストを生成します:

range ​

startからendまでの整数のリストを、両端を含めて構築します。 startがendより大きい場合、リストは降順になります。

range(start, end)

range(1, 5)

[1, 2, 3, 4, 5]

range(5, 1)

[5, 4, 3, 2, 1]

random_choice ​

ランダムに選択された1つの要素を返します。

結果は評価のたびに異なるため、後続ステップで再現が必要な用途には使用しないでください。繰り返す必要のない値を生成する他の方法については、Random関数を参照してください。

random_choice(list)

関連情報 ​

• Map関数: group_byが返すMapを操作します。
• Deep map関数: 深くネストされた構造をたどります。
• 演算子: 演算子のpipelineファミリーに関する詳細情報。
• エラーコード: E201、E204、E207などのジョブ失敗をトラブルシューティングします。