Macaw.Data.Source.Description (macaw_data v0.13.0)
View SourceWhat a source is (spec/01 §2.1): its schema, its parameters, the capabilities it honors, and whether it answers every viewer the same.
schema: aMacaw.Data.Schema;params: the parameters it takes, by name (strings), each aMacaw.Data.Parameter;supports: the capabilities it honors, distinct, among:window | :box | :region | :latest | :order | :budget | :push | :as_of. Every one is optional: Macaw finishes what a source does not honor (spec/01 §2.4);viewer_independent:truedeclares the source answers every viewer the same, which only allows pooling across viewers, fetched with the anonymous viewer (spec/01 §6).falseby default;lateness: a hard bound on how late a change may be, declared only by a source that refuses changes past some age (spec/01 §4.4): aDurationover a:timewindow field, a non-negative number in the field's units over a:numberone;nilby default, accepting a change of any age;idle_after: milliseconds the source may deliver nothing before a derived source's watermark leaves it out (spec/02 §8.6), a positive integer;nilby default, never idle;chunk_span: the span of the window field a chunk of the source's table holds (spec/01 §1.1.3), declared because the source knows its rate: a positiveDurationof fixed length over a:timewindow field, a positive number over a:numberone;nilby default, derived from the resolution bychunk_span/2.
new/1 builds one and reports every fault at once.
Summary
Functions
The capabilities, in the order spec/01 §2.1 lists them.
The span of the window field a chunk of the source's table holds, at resolution, the
resolution its relation is held at (served.resolution; spec/01 §1.1.3). The declared
chunk_span when there is one; else Macaw.Data.Table.chunk_rows/0 times the
resolution: of r seconds (a positive number, or :second, :minute, :hour or
:day) a Duration over a :time window field, of r in the field's units a number
over a :number one. nil for a resolution it can't read, a number too fine or too
coarse for a span to hold (under a nanosecond a row, under 1.0e-280 of the field's
units, over 1.0e280 of either), and for a source with no time or number window field:
its chunks are aligned by row count. Never from the data.
A description of the given fields, schema required: {:ok, description} or every
fault, {path, reason}, ordered by path.
As new/1, raising Macaw.Data.Error naming every fault.
Types
@type capability() ::
:window | :box | :region | :latest | :order | :budget | :push | :as_of
A capability a source may honor.
@type t() :: %Macaw.Data.Source.Description{ chunk_span: Duration.t() | number() | nil, idle_after: pos_integer() | nil, lateness: Duration.t() | number() | nil, params: %{required(String.t()) => Macaw.Data.Parameter.t()}, schema: Macaw.Data.Schema.t(), supports: [capability()], viewer_independent: boolean() }
Functions
@spec capabilities() :: [capability(), ...]
The capabilities, in the order spec/01 §2.1 lists them.
@spec chunk_span(t(), term()) :: Duration.t() | number() | nil
The span of the window field a chunk of the source's table holds, at resolution, the
resolution its relation is held at (served.resolution; spec/01 §1.1.3). The declared
chunk_span when there is one; else Macaw.Data.Table.chunk_rows/0 times the
resolution: of r seconds (a positive number, or :second, :minute, :hour or
:day) a Duration over a :time window field, of r in the field's units a number
over a :number one. nil for a resolution it can't read, a number too fine or too
coarse for a span to hold (under a nanosecond a row, under 1.0e-280 of the field's
units, over 1.0e280 of either), and for a source with no time or number window field:
its chunks are aligned by row count. Never from the data.
iex> alias Macaw.Data.{Schema, Source.Description}
iex> d = Description.new!(schema: Schema.new!(%{t: %{type: :time}}))
iex> Description.chunk_span(d, :minute)
Duration.new!(second: 491_520)
iex> Description.chunk_span(d, nil)
nil
A description of the given fields, schema required: {:ok, description} or every
fault, {path, reason}, ordered by path.
iex> alias Macaw.Data.{Schema, Source.Description}
iex> {:ok, d} = Description.new(schema: Schema.new!(%{v: %{type: :number}}), supports: [:budget])
iex> {d.supports, d.viewer_independent}
{[:budget], false}
iex> Description.new(schema: :nope, supports: [:region, :teleport, :region])
{:error, [{[:schema], {:type, :schema}}, {[:supports, 1], {:enum, Description.capabilities()}}, {[:supports, 2], :duplicate}]}
As new/1, raising Macaw.Data.Error naming every fault.