The query specification.

A query in Disco is a struct which has the fields representing potential parameters for the query itself.

This module defines a behaviour with a set of default callback implementations to execute a query on an aggregate.

Define a query

Here’s how to implement a simple query without params:

defmodule MyApp.QuerySimple do
  use Disco.Query

  def run(%__MODULE__{} = _query), do: "result"
end

If you might need some params:

defmodule MyApp.QueryWithParams do
  use Disco.Query, foo: nil

  def run(%__MODULE__{} = query), do: query.foo
end

It’s also possible to apply validations on the params. Refer to Vex for more details.

defmodule MyApp.QueryWithValidations do
  use Disco.Query, foo: nil, bar: nil

  # param `foo` is required, `bar` isn't.
  validates(:foo, presence: true)

  def run(%__MODULE__{} = query), do: query.foo
end

Overriding default functions

As you can see, the simplest implementation only requires to implement run/1 callback, while the others are already implemented by default. Sometimes you might need a custom initialization or validation function, that’s why it’s possible to override new/1 and validate/1.

Usage example

NOTE: Disco.Factories.ExampleQuery has been defined in test/support/examples/example_query.ex.

iex> alias Disco.Factories.ExampleQuery, as: Query
iex> Query.new(%{foo: "bar"}) == %Query{foo: "bar"}
true
iex> Query.new(%{foo: "bar"}) |> Query.validate()
{:ok, %Query{foo: "bar"}}
iex> Query.new() |> Query.validate()
{:error, %{foo: ["must be present"]}}
iex> Query.run(%Query{foo: "bar"})
%{foo: "bar"}