One answer of a source: its rows, as a table, and what it actually served (spec/01 §3).
A delivery is a handful of terms beside its table, never per row:
table: the rows, aMacaw.Data.Table.new/2reads any source shape into one at the edge, so a gap staysnil: absence is never zero.schema: the version of the schema the rows were produced under (Macaw.Data.Schema.version/1), never the schema itself, whichMacaw.Data.Schema.Cacheholds by version;nilwhen the source has none.served: what this answer served, which may differ from what was asked:window: a range[from, to], a box over a:pointwindow field%{west: w, south: s, east: e, north: n}, ornil;resolution: the spacing of the rows as served (seconds, or a name such as:minute), ornil;capped: whether the source stopped short of the window it was asked for;reduced_by: who brought the rows within budget,:sourceor:runtime, ornilwhen nobody had to;params: the parameters it was answered for, a map;note: a line for a person ("coarsened from raw"), ornil.
origin: where it came from,%{source: name, request: digest, as_of: time | nil}, ornil.
The shape of visualize's Visualize.Data.Delivery, whose facts are flat and whose
reduced_by is :feed or :visualize, is spec/01 §3's here.
Examples
iex> alias Macaw.Data.{Delivery, Table}
iex> d = Delivery.new(%{t: [1, 2], v: [3, nil]}, served: [window: [0, 10]], schema: "ab12")
iex> Table.rows(d.table)
[%{t: 1, v: 3}, %{t: 2, v: nil}]
iex> {d.served.window, d.served.capped, d.served.reduced_by}
{[0, 10], false, nil}
Summary
Types
Where an answer came from.
What one answer served (spec/01 §3).
A window as served: a range, a box over positions, or none.
Functions
A delivery of rows, any source Macaw.Data.Table.from/2 reads (a table passes as it
is), with served: (a keyword list or map of the served facts), schema: (a version)
and origin:. types: is passed to Table.from/2.
The rows a delivery carries, one map per row (Macaw.Data.Table.rows/1).
Types
@type origin() :: %{source: term(), request: String.t(), as_of: DateTime.t() | nil} | nil
Where an answer came from.
@type served() :: %{ window: window(), resolution: term(), capped: boolean(), reduced_by: :source | :runtime | nil, params: map(), note: String.t() | nil }
What one answer served (spec/01 §3).
@type t() :: %Macaw.Data.Delivery{ origin: origin(), schema: String.t() | nil, served: served(), table: Macaw.Data.Table.t() }
@type window() :: [term()] | %{west: number(), south: number(), east: number(), north: number()} | nil
A window as served: a range, a box over positions, or none.
Functions
@spec new(Macaw.Data.Table.source() | Macaw.Data.Table.t(), keyword()) :: t()
A delivery of rows, any source Macaw.Data.Table.from/2 reads (a table passes as it
is), with served: (a keyword list or map of the served facts), schema: (a version)
and origin:. types: is passed to Table.from/2.
Raises ArgumentError naming the fault: a key that is not a delivery's or a served
fact, a value a field does not take, or rows no table reads.
The rows a delivery carries, one map per row (Macaw.Data.Table.rows/1).