Alembic v2.1.0 Alembic.Fetch

Fetching Data in the JSON API spec

Summary

Types

params()

t()

The options when performing a fetch

Functions

from_params(params)

Extract a t from the params

to_query(fetch, preload_by_include, query)

Converts the includes in fetch to Ecto.Query.preloads

Types

params :: %{}

t :: %Alembic.Fetch{includes: nil | Alembic.Fetch.Includes.t}

The options when performing a fetch

:include - The relationships paths to include in the response document

Functions

from_params(params)

Specs

from_params(params) :: t

Extract a t from the params.

include param is parsed in includes of t

params without "include" will have no includes

iex> Alembic.Fetch.from_params(%{})
%Alembic.Fetch{
  includes: []
}

params with "include" will have the value of "includes" broken into Alembic.Fetch.Includes.t

iex> Alembic.Fetch.from_params(
  ...>   %{
  ...>     "include" => "author,comments.author.posts"
  ...>   }
  ...> )
  %Alembic.Fetch{
    includes: [
      "author",
      %{
        "comments" => %{
          "author" => "posts"
        }
      }
    ]
  }

to_query(fetch, preload_by_include, query)

Specs

to_query(t, Alembic.Fetch.Includes.preload_by_include, Ecto.Query.t) ::
  {:ok, Ecto.Query.t} |
  {:error, Alembic.Document.t}

Converts the includes in fetch to Ecto.Query.preloads.

With no includes, no preloads are added

iex> require Ecto.Query
iex> query = Ecto.Query.from p in Alembic.TestPost
%Ecto.Query{
  from: {"posts", Alembic.TestPost}
}
iex> params = %{}
iex> fetch = Alembic.Fetch.from_params(params)
iex> {:ok, fetch_query} = Alembic.Fetch.to_query(fetch, %{}, query)
{
  :ok,
  %Ecto.Query{
    from: {"posts", Alembic.TestPost}
  }
}
iex> fetch_query == query
true

If there are includes, they are converted to preloads and added to the query

iex> require Ecto.Query
iex> query = Ecto.Query.from p in Alembic.TestPost
%Ecto.Query{
  from: {"posts", Alembic.TestPost}
}
iex> params = %{
...>   "include" => "comments"
...> }
iex> fetch = Alembic.Fetch.from_params(params)
iex> Alembic.Fetch.to_query(
...>   fetch,
...>   %{
...>     "comments" => :comments
...>   },
...>   query
...> )
{
  :ok,
  %Ecto.Query{
    from: {"posts", Alembic.TestPost},
    preloads: [
      [:comments]
    ]
  }
}

If the includes can’t be converted to preloads, then the conversion errors are returned

iex> require Ecto.Query
iex> query = Ecto.Query.from p in Alembic.TestPost
%Ecto.Query{
  from: {"posts", Alembic.TestPost}
}
iex> params = %{
...>   "include" => "secret"
...> }
iex> fetch = Alembic.Fetch.from_params(params)
iex> Alembic.Fetch.to_query(
...>   fetch,
...>   %{},
...>   query
...> )
{
  :error,
  %Alembic.Document{
    errors: [
      %Alembic.Error{
        detail: "`secret` is an unknown relationship path",
        meta: %{
          "relationship_path" => "secret"
        },
        source: %Alembic.Source{
          parameter: "include"
        },
        title: "Unknown relationship path"
      }
    ]
  }
}