Visualize.Data.Schema (Visualize v0.8.0)

A feed's schema: what each of its fields means (spec/08 §10.1, D-136).

A schema maps a field — named as the feed's rows name it, an atom or a string — to a description: its type, and as much of unit, quantity, label, order, status, polarity, target, continuity, window, metric_kind, bounds and identity as the feed knows, and for a :category field the values it takes, every one (#643, D-194). It says what the numbers are, whoever draws them, and never how they are drawn: a description has no color key, since color is the theme's to choose from the meaning (#533). A declared value may be an entry, %{value: v, name: "Display", color: c}, whose color is a host's hint a design's own range outranks (D-224); values/2, value_names/2 and value_colors/2 read the bare values, the names and the colors. A :time field holds instants; a feed whose clock is a number describes it :number and window: true, the field its windows are over (D-154). A numeric field may say how it was measured, metric_kind: :gauge | :counter | :rate, which refines what its quantity's additivity allows, and where its values lie, bounds: [min, max], a display hint over its quantity's (D-155). A unit is a UCUM code Visualize.Unit reads and a quantity one of Visualize.Quantity.all/0, and when both are given the unit measures the quantity (D-157). A field whose value names the thing a row is about says identity: true, several such fields together naming it (D-167); identity/2 gives a row's identity under the schema.

A schema is identified by its version, a content hash (spec/08 §10.2): the same schema has the same version on every node and under every release, and any change of content is a new version. A Visualize.Data.Delivery names the version its rows were produced under; Visualize.Data.Schema.Cache holds schemas by {feed, version}. Schemas of different versions may still describe the same data in different words, and compatibility/2 says when one's rows read as the other's (D-159).

Examples

iex> {:ok, schema} =
...>   Visualize.Data.Schema.new(%{
...>     t: %{type: :time},
...>     latency: %{type: :number, unit: "s", quantity: :duration, label: "Request time"},
...>     state: %{type: :category, order: ["ok", "warn", "fail"],
...>              status: %{"ok" => :good, "warn" => :warning, "fail" => :bad}}
...>   })
iex> Visualize.Data.Schema.fetch(schema, "latency", :unit)
{:ok, "s"}
iex> String.length(Visualize.Data.Schema.version(schema))
64
iex> Visualize.Data.Schema.new(%{state: %{type: :category, colors: %{"ok" => "#0a0"}}})
{:error, [{[:state, :colors], {:color_key, :colors}}]}

Summary

Types

description()

What one field means (spec/08 §10.1).

error()

A fault of new/1: the path from the schema to the value, and why.

incompatibility()

Why a field of one schema cannot read another's rows (spec/08 §10.1, D-159).

name()

A field name, as the feed's rows spell it.

t()

value()

A category field's value: a string, an atom or a number.

value_entry()

A declared value with what a person reads of it (spec/08 §10.1, D-224): its display name, and a color hint — a literal string or a typed color (spec/08 §1.9).

Functions

attributes()

The fourteen description keys, :type first (spec/08 §10.1).

compatibility(schema, other)

Whether other's rows read as schema's (spec/08 §10.1, D-159): for each field of schema, other has a field of the same name compared as strings, of the same type, and for a :number field a unit that converts into schema's — two absent units agree, one absent facing a present one does not. {:error, faults} lists every fault, field spelled as schema spells it, ordered by its name as a string. Labels and facts are not compared, and other's extra fields are not faults — except identity (D-167): a field one schema declares identity: true and the other does not is {:identity, a, b}, a and b whether each declares it, even a field only other has, since other's rows read as schema's would merge the things other tells apart.

fetch(schema, name)

A field's description, by either spelling of its name (spec/08 §6.2).

fetch(schema, name, key)

One attribute of a field's description; :error when the field or the attribute is absent.

format_error(arg)

One fault of new/1 as a line a person reads.

identity(schema)

The fields the schema declares identity: true, as it spells them, ordered by name as a string; [] when it declares none (spec/08 §10.1, D-167).

identity(schema, row)

A row's identity under the schema (spec/08 §10.1, D-167): the bare value of the one identity field, a map from field to value, keyed as the schema spells them, for several, and nil when the schema declares none or the row has no value for one of them. Each field is read by either spelling of its name.

new(fields)

The schema of a map of field descriptions, or every fault of it by path (spec/08 §10.1).

new!(fields)

The schema of a map of field descriptions, or ArgumentError naming every fault.

value_colors(schema, field)

A map from each declared value with a color to its color, as written — a literal string or a typed color — (spec/08 §10.1, D-224); %{} when none has one, or the field declares no values. It is a :color_map as it stands; a design's own range outranks it.

value_names(schema, field)

A map from each declared value with a name to its name (spec/08 §10.1, D-224); %{} when none has one, or the field declares no values.

values(schema, field)

A field's declared values, bare, in their declared order (spec/08 §10.1, D-224): each value entry's value, and each bare value as it is. nil when the schema has no such field or the field declares no values — an open set, where [] would say a closed one holding nothing. Read by either spelling of the field's name.

version(schema)

The schema's version: the SHA-256 of its canonical encoding as 64 lowercase hex digits (spec/08 §10.2), computed once by new/1.