Decree.Store.Query (decree v0.1.0)

Copy Markdown View Source

What Decree.Store.read_query/2 and Decree.Store.stream_query/2 search for.

A query is a non-empty list of items, and it matches an event when any item does. An item is a keyword list or a map with :types and :tags, each a list of strings, either of which may be absent. It matches an event whose type is one of its types, if it names any, and which carries all of its tags:

[
  # Every event of either type.
  [types: ["OrderPlaced", "OrderCancelled"]],

  # Every event carrying both tags, whatever its type.
  [tags: ["order:1", "tenant:a"]],

  # Every event of this type carrying this tag.
  [types: ["InvoiceRaised"], tags: ["order:1"]]
]

Tags and types are strings. An item's repeats count once. An item naming neither types nor tags cannot be served by an index, so it is refused. A store that declares deletable also refuses a query naming what it declares, with {:error, :query_names_deletable}: see "Deletable streams" in Decree.Store.

The first tag

An item's first tag is the one the index searches, and the item's other tags are checked against each hit. Put the narrowest tag first: a broad first tag costs read time, and never changes the answer.

Summary

Functions

Compiles a list of items.

Types

item()

@type item() ::
  [types: [String.t()], tags: [String.t()]]
  | %{optional(:types) => [String.t()], optional(:tags) => [String.t()]}

t()

@type t() :: %Decree.Store.Query{
  probe_items: [non_neg_integer()],
  probe_tags: [String.t() | nil],
  probe_types: [String.t() | nil],
  rest_items: [non_neg_integer()],
  rest_tags: [String.t()]
}

Functions

compile(items)

@spec compile(items :: [item()]) ::
  {:ok, t()} | {:error, :invalid_query} | {:error, :tag_too_long}

Compiles a list of items.

Answers {:error, :invalid_query} for anything but a non-empty list of items, and {:error, :tag_too_long} for a tag over Decree.Store.EventData.max_tag_bytes/0. A refusal sends nothing to the database, so a caller's transaction stays alive.