Macaw.Data.Source.Order (macaw_data v0.12.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 (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

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

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

instant(t)

@spec instant(term()) :: integer() | nil

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

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 (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

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()) ::
  {: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"}}]}

sort!(rows, order, schema)

@spec sort!([map()], t(), Macaw.Data.Schema.t()) :: [map()]

As sort/3, the rows alone, raising Macaw.Data.Error naming the faults.

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]

sort_with(items, order, schema, read)

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