Macaw.Data.Source.Order (macaw_data v0.9.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
(Macaw.Data.Window.position/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.
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 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 (Macaw.Data.Window.position/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). [] leaves them as they are. The order is
the caller's to have checked (faults/2); a field the schema lacks raises
ArgumentError.
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.
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 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 (Macaw.Data.Window.position/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()) :: [map()]
The rows sorted by the order under the schema's types, stably, each row read by name
(Macaw.Data.Table.get/2, either spelling). [] leaves them as they are. The order is
the caller's to have checked (faults/2); a field the schema lacks raises
ArgumentError.
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> Macaw.Data.Source.Order.sort(rows, [{:t, :desc}], schema) |> Enum.map(& &1.sev)
["ok", "bad", "warn"]
iex> Macaw.Data.Source.Order.sort(rows, [{:sev, :desc}], schema) |> Enum.map(& &1.sev)
["bad", "warn", "ok"]
@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]