Macaw.Data.Derived.Columns (macaw_data v0.13.0)
View SourceA derived function's input read as columns (spec/02 §2.2): accessors over a windowed input table that read its packed buffers and never make a row.
A function whose source reads its inputs as columns (input: :columns) is handed each
input as a Macaw.Data.Table, and reads it through these. A column is named by either
spelling, its atom or its string (Macaw.Layers.Names.same?/2), as a row's field is
read.
Every accessor answers {:ok, value} or {:error, reason}, and raises on no input.
The reasons (format_error/1 words each):
{:unknown_column, name}: the table has no columnnamenames;{:wrong_type, name, expected, actual}: a typed accessor read columnname, of typeactual, which is none of the types inexpected;{:type, :name}: a column was named by something other than an atom or a string;{:type, :table}: the input given is not aMacaw.Data.Table;{:type, :integer},{:type, :non_neg_integer}:take/2's count is not an integer, orslice/3's start or count is not a non-negative integer.
Each has a ! variant (sum!/2, …) that answers the value alone, or raises
Macaw.Data.Error worded by format_error/1.
Positional reads, one value a row, in order,
nilat a gap (falseinvalid/2), so two columns zip row by row:column/2the decoded values, asMacaw.Data.Table.column/2gives them;numbers/2a number column's;instants/2a time column's instants, integer Unix microseconds onMacaw.Data.Source.Order.instant/1's scale (a naive time by its wall clock, a date by its midnight), read straight from the buffer;valid/2the presence mask; andtime_kind/2the kind of time a time column holds, read from its storage form, for host code alone (not on the sandbox allowlist).Reductions over the column's readings, its values present, with the semantics of the package's aggregates (spec/04 §5):
count/2,sum/2(exact,0of none),mean/2(nilof none), andmin/2andmax/2of a number or a time column, the first on a tie, a time compared by its instant and answered as its value. With the native kernels loaded (Macaw.Data.Native),sum,countandmeanread an int64 or float64 buffer in the exact-sum kernel, andminandmaxfind their slot in the extremes kernel, which reads an int64, float64 or int32 buffer; their Elixir path reads the same buffers and answers the same.Part of the input:
slice/3andtake/2answer a table of some of its rows, views of its chunks, decoding nothing;rows/1is the row view, for a function that wants rows after all.iex> alias Macaw.Data.Derived.Columns iex> table = Macaw.Data.Table.new!([{"v", :number, [1.5, nil, 2.5]}, ...> {"t", :time, [~U[2026-01-01 00:00:00Z], ~U[2026-01-01 00:00:01Z], nil]}]) iex> Columns.sum(table, :v) {:ok, 4.0} iex> Columns.valid(table, "v") {:ok, [true, false, true]} iex> Columns.instants!(table, "t") [1767225600000000, 1767225601000000, nil] iex> Columns.max(table, "t") {:ok, ~U[2026-01-01 00:00:01Z]} iex> Columns.take!(table, -1) |> Columns.column!("v") [2.5] iex> Columns.sum(table, "w") {:error, {:unknown_column, "w"}} iex> Columns.mean(table, "t") {:error, {:wrong_type, "t", [:number], :time}}
Summary
Types
A column's name, by either spelling.
Why an accessor answered no value (format_error/1).
An accessor's answer.
Functions
The column's values, in order, nil where one is missing, as
Macaw.Data.Table.column/2 decodes them.
As column/2, the value, or Macaw.Data.Error worded by format_error/1.
The number of the column's readings: its values present.
As count/2, the value, or Macaw.Data.Error worded by format_error/1.
One reason as a line a person reads.
A time column's instants, in order, nil where one is missing: integer Unix
microseconds (Macaw.Data.Source.Order.instant/1), read from the buffer, no time made.
As instants/2, the value, or Macaw.Data.Error worded by format_error/1.
The greatest reading of a number or a time column, the first on a tie, nil of none: a
time by its instant (Macaw.Data.Source.Order.instant/1), answered as its value.
As max/2, the value, or Macaw.Data.Error worded by format_error/1.
The arithmetic mean of a number column's readings, the exact sum over their count;
nil of none.
As mean/2, the value, or Macaw.Data.Error worded by format_error/1.
The least reading of a number or a time column, the first on a tie, nil of none: a
time by its instant (Macaw.Data.Source.Order.instant/1), answered as its value.
As min/2, the value, or Macaw.Data.Error worded by format_error/1.
The column names, in order, as the table spells them.
As names/1, the value, or Macaw.Data.Error worded by format_error/1.
A number column's values, in order, nil where one is missing.
As numbers/2, the value, or Macaw.Data.Error worded by format_error/1.
The rows, one map a row keyed by every column name (Macaw.Data.Table.rows/1).
As rows/1, the value, or Macaw.Data.Error worded by format_error/1.
The number of rows.
As size/1, the value, or Macaw.Data.Error worded by format_error/1.
The count rows from start (from 0), as a table of the same columns: views of the
chunks they lie in, nothing decoded (Macaw.Data.Table.slice/3).
As slice/3, the value, or Macaw.Data.Error worded by format_error/1.
The exact sum of a number column's readings (spec/04 §5): an
integer when every reading is one, else the exact sum rounded once; 0 of none.
As sum/2, the value, or Macaw.Data.Error worded by format_error/1.
The first n rows, or with n negative the last -n, as a table of the same columns,
as Enum.take/2 takes.
As take/2, the value, or Macaw.Data.Error worded by format_error/1.
The kind of time a :time column holds (macaw_data#149): DateTime (UTC or zoned,
whose instants order alike), NaiveDateTime or Date when every chunk holding a value
holds that one kind, else :mixed. It is read from each chunk's storage form alone
(Macaw.Data.Table.Chunk.time_kind/4), so no value is decoded. A column with no value
present, an empty table's included, packs as DateTime and answers it.
As time_kind/2, the kind, or Macaw.Data.Error worded by format_error/1.
The column's declared type (Macaw.Data.Table.types/0).
As type/2, the value, or Macaw.Data.Error worded by format_error/1.
The column's presence mask, in order: true where a value is present.
As valid/2, the value, or Macaw.Data.Error worded by format_error/1.
Types
A column's name, by either spelling.
@type reason() :: {:unknown_column, term()} | {:wrong_type, Macaw.Data.Table.name(), [Macaw.Data.Table.type(), ...], Macaw.Data.Table.type()} | {:type, :name | :table | :integer | :non_neg_integer}
Why an accessor answered no value (format_error/1).
@type result(value) :: {:ok, value} | {:error, reason()}
An accessor's answer.
Functions
@spec column(Macaw.Data.Table.t(), name()) :: result([term()])
The column's values, in order, nil where one is missing, as
Macaw.Data.Table.column/2 decodes them.
@spec column!(Macaw.Data.Table.t(), name()) :: [term()]
As column/2, the value, or Macaw.Data.Error worded by format_error/1.
@spec count(Macaw.Data.Table.t(), name()) :: result(non_neg_integer())
The number of the column's readings: its values present.
@spec count!(Macaw.Data.Table.t(), name()) :: non_neg_integer()
As count/2, the value, or Macaw.Data.Error worded by format_error/1.
One reason as a line a person reads.
iex> Macaw.Data.Derived.Columns.format_error({:wrong_type, "t", [:number], :time})
~s|column "t" is :time, not :number|
@spec instants(Macaw.Data.Table.t(), name()) :: result([integer() | nil])
A time column's instants, in order, nil where one is missing: integer Unix
microseconds (Macaw.Data.Source.Order.instant/1), read from the buffer, no time made.
@spec instants!(Macaw.Data.Table.t(), name()) :: [integer() | nil]
As instants/2, the value, or Macaw.Data.Error worded by format_error/1.
@spec max(Macaw.Data.Table.t(), name()) :: result(number() | DateTime.t() | NaiveDateTime.t() | Date.t() | nil)
The greatest reading of a number or a time column, the first on a tie, nil of none: a
time by its instant (Macaw.Data.Source.Order.instant/1), answered as its value.
@spec max!(Macaw.Data.Table.t(), name()) :: number() | DateTime.t() | NaiveDateTime.t() | Date.t() | nil
As max/2, the value, or Macaw.Data.Error worded by format_error/1.
@spec mean(Macaw.Data.Table.t(), name()) :: result(float() | nil)
The arithmetic mean of a number column's readings, the exact sum over their count;
nil of none.
@spec mean!(Macaw.Data.Table.t(), name()) :: float() | nil
As mean/2, the value, or Macaw.Data.Error worded by format_error/1.
@spec min(Macaw.Data.Table.t(), name()) :: result(number() | DateTime.t() | NaiveDateTime.t() | Date.t() | nil)
The least reading of a number or a time column, the first on a tie, nil of none: a
time by its instant (Macaw.Data.Source.Order.instant/1), answered as its value.
@spec min!(Macaw.Data.Table.t(), name()) :: number() | DateTime.t() | NaiveDateTime.t() | Date.t() | nil
As min/2, the value, or Macaw.Data.Error worded by format_error/1.
@spec names(Macaw.Data.Table.t()) :: result([Macaw.Data.Table.name()])
The column names, in order, as the table spells them.
@spec names!(Macaw.Data.Table.t()) :: [Macaw.Data.Table.name()]
As names/1, the value, or Macaw.Data.Error worded by format_error/1.
@spec numbers(Macaw.Data.Table.t(), name()) :: result([number() | nil])
A number column's values, in order, nil where one is missing.
@spec numbers!(Macaw.Data.Table.t(), name()) :: [number() | nil]
As numbers/2, the value, or Macaw.Data.Error worded by format_error/1.
@spec rows(Macaw.Data.Table.t()) :: result([map()])
The rows, one map a row keyed by every column name (Macaw.Data.Table.rows/1).
@spec rows!(Macaw.Data.Table.t()) :: [map()]
As rows/1, the value, or Macaw.Data.Error worded by format_error/1.
@spec size(Macaw.Data.Table.t()) :: result(non_neg_integer())
The number of rows.
@spec size!(Macaw.Data.Table.t()) :: non_neg_integer()
As size/1, the value, or Macaw.Data.Error worded by format_error/1.
@spec slice(Macaw.Data.Table.t(), non_neg_integer(), non_neg_integer()) :: result(Macaw.Data.Table.t())
The count rows from start (from 0), as a table of the same columns: views of the
chunks they lie in, nothing decoded (Macaw.Data.Table.slice/3).
@spec slice!(Macaw.Data.Table.t(), non_neg_integer(), non_neg_integer()) :: Macaw.Data.Table.t()
As slice/3, the value, or Macaw.Data.Error worded by format_error/1.
@spec sum(Macaw.Data.Table.t(), name()) :: result(number())
The exact sum of a number column's readings (spec/04 §5): an
integer when every reading is one, else the exact sum rounded once; 0 of none.
@spec sum!(Macaw.Data.Table.t(), name()) :: number()
As sum/2, the value, or Macaw.Data.Error worded by format_error/1.
@spec take(Macaw.Data.Table.t(), integer()) :: result(Macaw.Data.Table.t())
The first n rows, or with n negative the last -n, as a table of the same columns,
as Enum.take/2 takes.
@spec take!(Macaw.Data.Table.t(), integer()) :: Macaw.Data.Table.t()
As take/2, the value, or Macaw.Data.Error worded by format_error/1.
@spec time_kind(Macaw.Data.Table.t(), name()) :: result(DateTime | NaiveDateTime | Date | :mixed)
The kind of time a :time column holds (macaw_data#149): DateTime (UTC or zoned,
whose instants order alike), NaiveDateTime or Date when every chunk holding a value
holds that one kind, else :mixed. It is read from each chunk's storage form alone
(Macaw.Data.Table.Chunk.time_kind/4), so no value is decoded. A column with no value
present, an empty table's included, packs as DateTime and answers it.
It is for host code (visualize's board placement): a stored function cannot call it, since its answer is a module (spec/02 §6.2).
iex> alias Macaw.Data.Derived.Columns
iex> table = Macaw.Data.Table.new!([{"t", :time, [~N[2026-01-01 00:00:00], nil]}])
iex> Columns.time_kind(table, "t")
{:ok, NaiveDateTime}
iex> Columns.time_kind(Macaw.Data.Table.new!([{"t", :time, [~D[2026-01-01], ~U[2026-01-01 00:00:00Z]]}]), :t)
{:ok, :mixed}
@spec time_kind!(Macaw.Data.Table.t(), name()) :: DateTime | NaiveDateTime | Date | :mixed
As time_kind/2, the kind, or Macaw.Data.Error worded by format_error/1.
@spec type(Macaw.Data.Table.t(), name()) :: result(Macaw.Data.Table.type())
The column's declared type (Macaw.Data.Table.types/0).
@spec type!(Macaw.Data.Table.t(), name()) :: Macaw.Data.Table.type()
As type/2, the value, or Macaw.Data.Error worded by format_error/1.
@spec valid(Macaw.Data.Table.t(), name()) :: result([boolean()])
The column's presence mask, in order: true where a value is present.
@spec valid!(Macaw.Data.Table.t(), name()) :: [boolean()]
As valid/2, the value, or Macaw.Data.Error worded by format_error/1.