Alembic

v4.0.0

Alembic v4.0.0 Alembic.Fetch View Source

Fetching Data in the JSON API spec

Link to this section 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

Link to this section Types

Link to this type params() View Source 
params() :: %{}
Link to this type t() View Source 
t() :: %Alembic.Fetch{
  includes: Alembic.Fetch.Includes.t(),
  sorts: Alembic.Fetch.Sorts.t()
}

The options when performing a fetch

  • :includes - The relationships paths to include in the response document
  • :sorts - The attributes and their direction to sort in the response document.

Link to this section Functions

Link to this function from_params(params) View Source 
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"
        }
      }
    ]
  }

params with "sort" will ahve the value of "sort" broken into Alembic.Fetch.Sorts.t

  iex> Alembic.Fetch.from_params(
  ...>   %{
  ...>     "sort" => "author.name,-comments.author.posts.inserted-at"
  ...>   }
  ...> )
  %Alembic.Fetch{
    sorts: [
      %Alembic.Fetch.Sort{
        attribute: "name",
        direction: :ascending,
        relationship: "author"
      },
      %Alembic.Fetch.Sort{
        attribute: "inserted-at",
        direction: :descending,
        relationship: %{
          "comments" => %{
            "author" => "posts"
          }
        }
      }
    ]
  }
Link to this function to_query(fetch, preload_by_include, query) View Source 
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 t in Alembic.TestPost>
iex> params = %{}
iex> fetch = Alembic.Fetch.from_params(params)
iex> {:ok, fetch_query} = Alembic.Fetch.to_query(fetch, %{}, query)
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 t in Alembic.TestPost>
iex> params = %{
...>   "include" => "comments"
...> }
iex> fetch = Alembic.Fetch.from_params(params)
iex> {:ok, query} = Alembic.Fetch.to_query(
...>   fetch,
...>   %{
...>     "comments" => :comments
...>   },
...>   query
...> )
...> query
#Ecto.Query<from t in Alembic.TestPost, preload: [[: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 t in 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"
      }
    ]
  }
}