Pipelines builtins

17 builtins of Soma 3.2.4 in the category Pipelines, with their exact signatures, as soma describe --builtins --json prints them.

• filter_by
• sort_by
• top
• bottom
• sum_by
• avg_by
• min_by
• max_by
• pluck
• group_by
• distinct
• distinct_by
• count_by
• select
• agg
• inner_join
• left_join

filter_by

filter_by(rows: List<Map>, field, value) -> List<Map> | filter_by(rows: List<Map>, field, op: ">"|">="|"<"|"<="|"=="|"!=", value) -> List<Map>

Keep rows whose field compares true against value (op defaults to == with 3 args).

deterministic · replay: pure

Used in verified programs:

• data/ab_test, line 19: on of(variant: String) { return samples() |> filter_by("variant", "=", variant) }
• data/basket_analysis, line 58: assert (order_values() |> filter_by("order", "=", "o2"))[0].price_sum == 6
• data/cohort_retention, line 52: assert (retention() |> filter_by("cohort", "=", "jan"))[0].retention_pct == 66
• data/csv_transform, line 19: |> filter_by("qty", ">", 0)

sort_by

sort_by(rows: List<Map>, field, order?: "desc") -> List<Map> | sort_by(list, x => key, order?: "desc") -> List

Stable sort by a field (numbers by value, strings lexicographically) or by a key function; a list key sorts on several keys: sort_by(rows, r => [0 - r.total, r.name]).

deterministic · replay: pure

Used in verified programs:

• data/ab_test, line 35: ) |> sort_by("rate", "desc")
• data/basket_analysis, line 23: |> sort_by("price_count", "desc")
• data/cohort_retention, line 36: |> sort_by("retention_pct", "desc")
• data/dedup_events, line 29: |> sort_by("event_id_count", "desc")

top

top(rows: List, n: Int) -> List

First n elements, capped at the list length. n must be a nonnegative Int; negative raises kind range, wrong types raise kind type.

deterministic · replay: pure

Used in verified programs:

• data/leaderboard, line 20: on podium() { return ranked() |> top(3) |> pluck("name") }
• data/topn_movies, line 18: on best() { return movies() |> sort_by("rating", "desc") |> top(3) |> select("title", "rating") }
• finance/portfolio_pnl, line 48: return enriched() |> sort_by("pnl", "desc") |> top(1)

bottom

bottom(rows: List, n: Int) -> List

Last n elements, capped at the list length. n must be a nonnegative Int; negative raises kind range, wrong types raise kind type.

deterministic · replay: pure

Used in verified programs:

• data/topn_movies, line 20: on worst() { return movies() |> sort_by("rating", "desc") |> bottom(2) |> select("title", "rating") }

sum_by

sum_by(rows: List<Map>, field) -> Int | Float

Sum of a field across rows: exact Int when every value is an Int, else a Float; a numeric String ("5") counts as its number.

deterministic · replay: pure

Used in verified programs:

• data/csv_transform, line 29: on grand_total() { return line_items() |> sum_by("gross") }
• data/expense_tracker, line 38: on total() { return items() |> sum_by("amount") }
• data/sales_report, line 34: on total_revenue() { return orders() |> sum_by("amount") }

avg_by

avg_by(rows: List<Map>, field) -> Int|Float

Mean of a field; Int when whole, () on an empty list.

deterministic · replay: pure

Used in verified programs:

• data/survey_scores, line 29: on overall_avg() { return responses() |> avg_by("score") }
• data/topn_movies, line 24: on avg_rating() { return movies() |> avg_by("rating") }

min_by

min_by(rows: List<Map>, field) -> Map

Row with the smallest integer value of field, or ().

deterministic · replay: pure

Used in verified programs:

• data/leaderboard, line 52: assert min_by(players(), "score").name == "vex"

max_by

max_by(rows: List<Map>, field) -> Map

Row with the largest integer value of field, or ().

deterministic · replay: pure

Used in verified programs:

• data/expense_tracker, line 40: on biggest() { return max_by(items(), "amount") }
• data/leaderboard, line 22: on champion() { return max_by(players(), "score") }
• data/record_pipeline, line 25: on top_earner() { return max_by(staff(), "salary") }
• records/playlist, line 32: return tracks() |> max_by("secs")

pluck

pluck(rows: List<Map>, field) -> List

Extract one field from every row (missing fields become ()).

deterministic · replay: pure

Used in verified programs:

• data/leaderboard, line 20: on podium() { return ranked() |> top(3) |> pluck("name") }
• data/left_join_inventory, line 34: on out_of_stock() { return availability() |> filter_by("available", "=", false) |> pluck("name") }
• data/survey_scores, line 27: on divisive() { return by_question() |> filter_by("spread", ">=", 3) |> pluck("q") }
• data/topn_movies, line 31: |> pluck("title")

group_by

group_by(rows: List<Map>, field) -> Map<String, List>

Group rows into a map keyed by the field's stringified value: 1 and "1" (true and "true") share a group, a row without the field goes to "unknown" and a () value to "null" — normalise the field first when those differ in your data.

deterministic · replay: pure

Used in verified programs:

• data/group_reduce, line 31: let grouped = group_by(votes(), "poll")

distinct

distinct(rows: List, field?) -> List

Unique elements — or, with field, the unique VALUES of that field (distinct_by keeps the rows).

deterministic · replay: pure

Used in verified programs:

• data/dedup_events, line 19: on unique_events() { return events() |> distinct() }
• data/funnel, line 22: return hits() |> filter_by("stage", "=", stage) |> distinct("user") |> len
• data/log_analysis, line 31: on unique_paths() { return entries() |> distinct("path") }

distinct_by

distinct_by(rows: List<Map>, field: String) -> List<Map>

The first row per distinct value of field (lodash uniqBy / dedup by id). Alias: unique_by.

deterministic · replay: pure

count_by

count_by(rows: List<Map>, field, value) -> Int

Number of rows whose field stringifies equal to value.

deterministic · replay: pure

Used in verified programs:

• data/basket_analysis, line 38: on milk_count() { return count_by(lines(), "product", "milk") }
• data/log_analysis, line 22: on error_count() { return count_by(entries(), "status", 500) }

select

select(rows: List<Map>, fields...) -> List<Map>

Project each row down to the named fields.

deterministic · replay: pure

Used in verified programs:

• data/csv_transform, line 27: on invoice() { return line_items() |> select("sku", "qty", "net", "tax", "gross") }
• data/inner_join_orders, line 29: return enriched() |> select("order_id", "name", "tier", "total")
• data/topn_movies, line 18: on best() { return movies() |> sort_by("rating", "desc") |> top(3) |> select("title", "rating") }

agg

agg(rows: List<Map>, group_field, "col:func"...) -> List<Map>

Group + aggregate: func is sum|avg|min|max|count; every group also gets a count. Groups are keyed like group_by (the field's text).

deterministic · replay: pure

Used in verified programs:

• data/basket_analysis, line 22: |> agg("product", "price:count")
• data/cohort_retention, line 31: let agged = joined() |> agg("cohort", "active:sum", "active:count")
• data/dedup_events, line 28: |> agg("kind", "event_id:count")
• data/expense_tracker, line 28: |> agg("category", "amount:sum", "amount:count")

inner_join

inner_join(left: List<Map>, right: List<Map>, key) -> List<Map>

Merge rows whose key matches in both lists (left fields win).

deterministic · replay: pure

Used in verified programs:

• data/cohort_retention, line 27: on joined() { return signups() |> inner_join(march_active(), "user") }
• data/inner_join_orders, line 26: on enriched() { return orders() |> inner_join(customers(), "customer_id") }

left_join

left_join(left: List<Map>, right: List<Map>, key) -> List<Map>

Keep every left row, merging matching right-row fields when found.

deterministic · replay: pure

Used in verified programs:

• data/left_join_inventory, line 24: on joined() { return products() |> left_join(stock(), "sku") }