Macaw.Data.Source.Order (macaw_data v0.9.0)

View Source

A 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

Types

A direction of one key.

t()

A row order: the keys, the first deciding first.

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

direction()

@type direction() :: :asc | :desc

A direction of one key.

t()

@type t() :: [{Macaw.Data.Schema.name(), direction()}]

A row order: the keys, the first deciding first.

Functions

faults(order, schema)

@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}}]

key(type, states \\ [])

@spec key(atom(), [term()]) :: (term() -> term())

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

shape(order)

@spec shape(term()) :: [{list(), term()}]

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"}}]

sort(rows, order, schema)

@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"]

sort_by(items, keys)

@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]