ExDatalog.Result (ExDatalog v0.2.0)

Copy Markdown View Source

Structured result from Datalog evaluation.

Contains the derived fact sets for each relation, along with evaluation statistics (iteration count, duration, relation sizes).

When provenance tracking is enabled (via explain: true), the provenance field records which rule derived each fact. Base facts (EDB) are attributed as :base. This field is nil when provenance tracking is disabled, ensuring zero overhead for the common case.

Access functions

  • get/2 — all tuples for a relation.
  • match/3 — tuples matching a pattern (:_ for wildcard).
  • size/2 — number of tuples in a relation.
  • relations/1 — list of all relation names in the result.

Summary

Types

provenance()
stats()
t()

Functions

get(result, relation)

Returns all tuples for a relation as a MapSet.

match(result, relation, pattern)

Returns tuples matching a pattern.

relations(result)

Returns all relation names present in the result.

size(result, relation)

Returns the number of tuples in a relation.

Types

provenance()

@type provenance() :: %{
  fact_origins: %{
    required(String.t()) => %{required(tuple()) => non_neg_integer() | :base}
  },
  rules: %{required(non_neg_integer()) => ExDatalog.IR.Rule.t()}
}

stats()

@type stats() :: %{
  iterations: non_neg_integer(),
  duration_us: non_neg_integer(),
  relation_sizes: %{required(String.t()) => non_neg_integer()},
  capabilities: ExDatalog.Capabilities.t()
}

t()

@type t() :: %ExDatalog.Result{
  provenance: provenance() | nil,
  relations: %{required(String.t()) => MapSet.t(tuple())},
  stats: stats()
}

Functions

get(result, relation)

@spec get(t(), String.t()) :: MapSet.t(tuple())

Returns all tuples for a relation as a MapSet.

Examples

iex> result = %ExDatalog.Result{relations: %{"parent" => MapSet.new([{:alice, :bob}])}, stats: %{iterations: 1, duration_us: 0, relation_sizes: %{"parent" => 1}}}
iex> ExDatalog.Result.get(result, "parent") |> MapSet.to_list()
[{:alice, :bob}]

match(result, relation, pattern)

@spec match(t(), String.t(), [term()]) :: MapSet.t(tuple())

Returns tuples matching a pattern.

The pattern is a list where :_ matches any value and other values match exactly. Useful for querying specific facts.

Examples

iex> result = %ExDatalog.Result{relations: %{"parent" => MapSet.new([{:alice, :bob}, {:carol, :dave}, {:alice, :carol}])}, stats: %{iterations: 1, duration_us: 0, relation_sizes: %{"parent" => 3}}}
iex> ExDatalog.Result.match(result, "parent", [:alice, :_]) |> MapSet.to_list() |> Enum.sort()
[{:alice, :bob}, {:alice, :carol}]

relations(result)

@spec relations(t()) :: [String.t()]

Returns all relation names present in the result.

Examples

iex> result = %ExDatalog.Result{relations: %{"parent" => MapSet.new(), "ancestor" => MapSet.new()}, stats: %{iterations: 1, duration_us: 0, relation_sizes: %{}}}
iex> Enum.sort(ExDatalog.Result.relations(result))
["ancestor", "parent"]

size(result, relation)

@spec size(t(), String.t()) :: non_neg_integer()

Returns the number of tuples in a relation.

Examples

iex> result = %ExDatalog.Result{relations: %{"parent" => MapSet.new([{:alice, :bob}, {:carol, :dave}])}, stats: %{iterations: 1, duration_us: 0, relation_sizes: %{"parent" => 2}}}
iex> ExDatalog.Result.size(result, "parent")
2