Macaw.Data.Source.Order (macaw_data v0.16.0)
View SourceA request's row order (spec/01 §2.3): what a reader looks at first, so a capped or reduced delivery can hold the first rows in it rather than a sorted sample.
An order is a list of {field, direction}, the field a name of the schema's (an atom or
a string, by either spelling) and the direction :asc or :desc, the first key
deciding first; [] asks for none.
Rows compare by their field's type, never by term order (term order puts a
%DateTime{} by its day before its year): a :time by its instant
(instant/1), a :number by its value, a :text by its string, a
:category by its place in the field's declared order and then by its spelling. A
nil, and a value of no reading for its type, sorts last in either direction:
absence is no value, and a reader's first rows are rows that have one. The sort is
stable, so rows the order cannot tell apart keep their order. filter's orderings
(spec/04 §4.1) compare by the same keys (key/2), so a filter and a sort never disagree.
Summary
Functions
The faults of an order against a schema: {[:order, i], {:unknown_field, name}} for a
field the schema does not describe, and {[:order, i], {:invalid_for, type}} for one
whose type has no order (:point, :color). An order of the wrong shape is
shape/1's, and its keys are not looked up.
A time's instant on one scale, Unix microseconds, so times of every kind compare: a
DateTime's UTC instant, a NaiveDateTime's wall clock and a Date at midnight, as
the edge reads them into a time column (spec/01 §1.1) and as the packed
:utc, :zoned and :naive forms hold them. Anything else, a number included (a
:time holds instants, never numbers, spec/01 §3), is nil, no reading.
A value's sort key under a type, so keys compare in term order exactly as the type
orders, and nil for no reading: a :time's instant (instant/1),
a :number's value, a :text's string, and a :category's place in states (its
declared order, spec/01 §1.2) and then its spelling, a state states does not list
following them. A type with no order of its own (:color, :point, :term) keys a
value by itself, so it sorts by term order; only nil is no reading.
The faults of an order's shape, with no schema: {[:order, i], {:type, :order}} for a
key that is no {field, :asc | :desc} with a name for its field, {[:order, i], {:duplicate, field}} for a field already named (by either spelling), and {[:order], {:type, :order}} for an order that is no list.
The rows sorted by the order under the schema's types, stably, each row read by name
(Macaw.Data.Table.get/2, either spelling): {:ok, rows}. [] leaves them as they
are. An order the schema cannot sort by is {:error, faults}, faults/2's: a field the
schema lacks, {[:order, i], {:unknown_field, name}}, one whose type has no order,
{[:order, i], {:invalid_for, type}}, and an order of the wrong shape, shape/1's.
sort!/3 answers the rows or raises.
As sort/3, the rows alone, raising Macaw.Data.Error naming the faults.
The items sorted stably by keys, each {direction, key, read}: read takes an item to
its value, key (from key/2) the value to its sort key, nil for no reading, which
sorts last in either direction. The first key decides first; items no key tells
apart keep their order. sort/3 is this over a schema's fields, and the sort step
(spec/04 §4.6) over one column's readings, so the two order alike.
The items sorted by the order under the schema's types, stably, as sort/3 sorts rows:
read takes an item and a field of the order, as the order names it, to the item's
value of that field. {:ok, items}, or sort/3's faults. sort/3 is this over rows,
each read by name; finishing a table (spec/01 §2.4) sorts its row indexes so by several
field read from its column, and makes no row.
Types
@type direction() :: :asc | :desc
A direction of one key.
@type t() :: [{Macaw.Data.Schema.name(), direction()}]
A row order: the keys, the first deciding first.
Functions
@spec faults(term(), Macaw.Data.Schema.t()) :: [{list(), term()}]
The faults of an order against a schema: {[:order, i], {:unknown_field, name}} for a
field the schema does not describe, and {[:order, i], {:invalid_for, type}} for one
whose type has no order (:point, :color). An order of the wrong shape is
shape/1's, and its keys are not looked up.
iex> alias Macaw.Data.Schema
iex> schema = Schema.new!(%{p50: %{type: :number}, at: %{type: :point}})
iex> Macaw.Data.Source.Order.faults([{"p5O", :desc}, {:at, :asc}, {"p50", :desc}], schema)
[{[:order, 0], {:unknown_field, "p5O"}}, {[:order, 1], {:invalid_for, :point}}]
A time's instant on one scale, Unix microseconds, so times of every kind compare: a
DateTime's UTC instant, a NaiveDateTime's wall clock and a Date at midnight, as
the edge reads them into a time column (spec/01 §1.1) and as the packed
:utc, :zoned and :naive forms hold them. Anything else, a number included (a
:time holds instants, never numbers, spec/01 §3), is nil, no reading.
iex> alias Macaw.Data.Source.Order
iex> Order.instant(~U[1970-01-01 00:00:01Z])
1_000_000
iex> Order.instant(~N[1970-01-01 00:00:01]) == Order.instant(~U[1970-01-01 00:00:01Z])
true
iex> Order.instant(~D[1970-01-02])
86_400_000_000
iex> Order.instant(5)
nil
A value's sort key under a type, so keys compare in term order exactly as the type
orders, and nil for no reading: a :time's instant (instant/1),
a :number's value, a :text's string, and a :category's place in states (its
declared order, spec/01 §1.2) and then its spelling, a state states does not list
following them. A type with no order of its own (:color, :point, :term) keys a
value by itself, so it sorts by term order; only nil is no reading.
iex> alias Macaw.Data.Source.Order
iex> Order.key(:time).(~U[2026-10-02 00:00:00Z]) > Order.key(:time).(~U[2025-12-31 00:00:00Z])
true
iex> Order.key(:category, ["ok", "warn"]).(:warn)
{1, "warn"}
iex> Order.key(:number).("7")
nil
The faults of an order's shape, with no schema: {[:order, i], {:type, :order}} for a
key that is no {field, :asc | :desc} with a name for its field, {[:order, i], {:duplicate, field}} for a field already named (by either spelling), and {[:order], {:type, :order}} for an order that is no list.
iex> Macaw.Data.Source.Order.shape([{"p50", :desc}, {:host, :asc}])
[]
iex> Macaw.Data.Source.Order.shape([{"p50", :down}, {:p50, :asc}, {"p50", :asc}])
[{[:order, 0], {:type, :order}}, {[:order, 2], {:duplicate, "p50"}}]
@spec sort([map()], t(), Macaw.Data.Schema.t()) :: {:ok, [map()]} | {:error, [{list(), term()}, ...]}
The rows sorted by the order under the schema's types, stably, each row read by name
(Macaw.Data.Table.get/2, either spelling): {:ok, rows}. [] leaves them as they
are. An order the schema cannot sort by is {:error, faults}, faults/2's: a field the
schema lacks, {[:order, i], {:unknown_field, name}}, one whose type has no order,
{[:order, i], {:invalid_for, type}}, and an order of the wrong shape, shape/1's.
sort!/3 answers the rows or raises.
iex> alias Macaw.Data.Schema
iex> schema = Schema.new!(%{t: %{type: :time}, sev: %{type: :category, order: ["ok", "warn", "bad"]}})
iex> rows = [
...> %{t: ~U[2026-10-02 00:00:00Z], sev: "ok"},
...> %{t: ~U[2025-12-31 00:00:00Z], sev: "bad"},
...> %{t: nil, sev: "warn"}
...> ]
iex> {:ok, sorted} = Macaw.Data.Source.Order.sort(rows, [{:t, :desc}], schema)
iex> Enum.map(sorted, & &1.sev)
["ok", "bad", "warn"]
iex> Macaw.Data.Source.Order.sort!(rows, [{:sev, :desc}], schema) |> Enum.map(& &1.sev)
["bad", "warn", "ok"]
iex> Macaw.Data.Source.Order.sort(rows, [{:at, :asc}], schema)
{:error, [{[:order, 0], {:unknown_field, "at"}}]}
@spec sort!([map()], t(), Macaw.Data.Schema.t()) :: [map()]
As sort/3, the rows alone, raising Macaw.Data.Error naming the faults.
@spec sort_by([item], [{direction(), (term() -> term()), (item -> term())}]) :: [item] when item: term()
The items sorted stably by keys, each {direction, key, read}: read takes an item to
its value, key (from key/2) the value to its sort key, nil for no reading, which
sorts last in either direction. The first key decides first; items no key tells
apart keep their order. sort/3 is this over a schema's fields, and the sort step
(spec/04 §4.6) over one column's readings, so the two order alike.
iex> alias Macaw.Data.Source.Order
iex> times = [~U[2026-10-02 00:00:00Z], nil, ~U[2025-12-31 00:00:00Z]]
iex> Order.sort_by(times, [{:asc, Order.key(:time), & &1}])
[~U[2025-12-31 00:00:00Z], ~U[2026-10-02 00:00:00Z], nil]
@spec sort_with([item], t(), Macaw.Data.Schema.t(), (item, Macaw.Data.Schema.name() -> term())) :: {:ok, [item]} | {:error, [{list(), term()}, ...]} when item: term()
The items sorted by the order under the schema's types, stably, as sort/3 sorts rows:
read takes an item and a field of the order, as the order names it, to the item's
value of that field. {:ok, items}, or sort/3's faults. sort/3 is this over rows,
each read by name; finishing a table (spec/01 §2.4) sorts its row indexes so by several
field read from its column, and makes no row.
iex> alias Macaw.Data.{Schema, Source.Order}
iex> schema = Schema.new!(%{v: %{type: :number}})
iex> values = {3, nil, 1}
iex> Order.sort_with([0, 1, 2], [{:v, :asc}], schema, fn i, _field -> elem(values, i) end)
{:ok, [2, 0, 1]}