Macaw.Data.Source.Description (macaw_data v0.18.0)

View Source

What a source is (spec/01 §2.1): its schema, its parameters, the capabilities it honors, and whether it answers every viewer the same.

  • schema: a Macaw.Data.Schema;
  • params: the parameters it takes, by name (strings), each a Macaw.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: true declares the source answers every viewer the same, which only allows pooling across viewers, fetched with the anonymous viewer (spec/01 §6). false by 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): a Duration over a :time window field, a non-negative number in the field's units over a :number one; nil by 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; nil by 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 positive Duration of fixed length over a :time window field, a positive number over a :number one; nil by default, derived from the resolution by chunk_span/2.

new/1 builds one and reports every fault at once.

Summary

Types

A capability a source may honor.

t()

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

capability()

@type capability() ::
  :window | :box | :region | :latest | :order | :budget | :push | :as_of

A capability a source may honor.

t()

@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

capabilities()

@spec capabilities() :: [capability(), ...]

The capabilities, in the order spec/01 §2.1 lists them.

chunk_span(description, resolution)

@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

new(fields)

@spec new(keyword() | map()) :: {:ok, t()} | {:error, [{list(), term()}, ...]}

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

new!(fields)

@spec new!(keyword() | map()) :: t()

As new/1, raising Macaw.Data.Error naming every fault.