Macaw.Data.Delivery (macaw_data v0.5.3)

Copy Markdown View Source

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, a Macaw.Data.Table. new/2 reads any source shape into one at the edge, so a gap stays nil: absence is never zero.
  • schema: the version of the schema the rows were produced under (Macaw.Data.Schema.version/1), never the schema itself, which Macaw.Data.Schema.Cache holds by version; nil when 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 :point window field %{west: w, south: s, east: e, north: n}, or nil;
    • resolution: the spacing of the rows as served (seconds, or a name such as :minute), or nil;
    • capped: whether the source stopped short of the window it was asked for;
    • reduced_by: who brought the rows within budget, :source or :runtime, or nil when nobody had to;
    • params: the parameters it was answered for, a map;
    • note: a line for a person ("coarsened from raw"), or nil.
  • origin: where it came from, %{source: name, request: digest, as_of: time | nil}, or nil.

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

t()

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

origin()

@type origin() ::
  %{source: term(), request: String.t(), as_of: DateTime.t() | nil} | nil

Where an answer came from.

served()

@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).

t()

@type t() :: %Macaw.Data.Delivery{
  origin: origin(),
  schema: String.t() | nil,
  served: served(),
  table: Macaw.Data.Table.t()
}

window()

@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

new(rows, opts \\ [])

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.

rows(delivery)

@spec rows(t()) :: [map()]

The rows a delivery carries, one map per row (Macaw.Data.Table.rows/1).