defmodule Ecto.Adapter.Queryable do
@moduledoc """
Specifies the query API required from adapters.
If your adapter is only able to respond to one or a couple of the query functions,
add custom implementations of those functions directly to the Repo
by using `c:Ecto.Adapter.__before_compile__/1` instead.
"""
@typedoc "Proxy type to the adapter meta"
@type adapter_meta :: Ecto.Adapter.adapter_meta()
@typedoc "Ecto.Query metadata fields (stored in cache)"
@type query_meta :: %{sources: tuple, preloads: term, select: map}
@typedoc """
Cache query metadata that is passed to `c:execute/5`.
The cache can be in 3 states, documented below.
If `{:nocache, prepared}` is given, it means the query was
not and cannot be cached. The `prepared` value is the value
returned by `c:prepare/2`.
If `{:cache, cache_function, prepared}` is given, it means
the query can be cached and it must be cached by calling
the `cache_function` function with the cache entry of your
choice. Once `cache_function` is called, the next time the
same query is given to `c:execute/5`, it will receive the
`:cached` tuple.
If `{:cached, update_function, reset_function, cached}` is
given, it means the query has been cached. You may call
`update_function/1` if you want to update the cached result.
Or you may call `reset_function/1`, with a new prepared query,
to force the query to be cached again. If `reset_function/1`
is called, the next time the same query is given to
`c:execute/5`, it will receive the `:cache` tuple.
"""
@type query_cache :: {:nocache, prepared}
| {:cache, cache_function :: (cached -> :ok), prepared}
| {:cached, update_function :: (cached -> :ok), reset_function :: (prepared -> :ok), cached}
@type prepared :: term
@type cached :: term
@type options :: Keyword.t()
@type selected :: term
@doc """
Commands invoked to prepare a query.
It is used on `c:Ecto.Repo.all/2`, `c:Ecto.Repo.update_all/3`,
and `c:Ecto.Repo.delete_all/2`. If returns a tuple, saying if
this query can be cached or not, and the `prepared` query.
The `prepared` query is any term that will be passed to the
adapter's `c:execute/5`.
"""
@callback prepare(atom :: :all | :update_all | :delete_all, query :: Ecto.Query.t()) ::
{:cache, prepared} | {:nocache, prepared}
@doc """
Executes a previously prepared query.
The `query_meta` field is a map containing some of the fields
found in the `Ecto.Query` struct, after they have been normalized.
For example, the values `selected` by the query, which then have
to be returned, can be found in `query_meta`.
The `query_cache` and its state is documented in `t:query_cache/0`.
The `params` is the list of query parameters. For example, for
a query such as `from Post, where: [id: ^123]`, `params` will be
`[123]`.
Finally, `options` is a keyword list of options given to the
`Repo` operation that triggered the adapter call. Any option is
allowed, as this is a mechanism to allow users of Ecto to customize
how the adapter behaves per operation.
It must return a tuple containing the number of entries and
the result set as a list of lists. The entries in the actual
list will depend on what has been selected by the query. The
result set may also be `nil`, if no value is being selected.
"""
@callback execute(adapter_meta, query_meta, query_cache, params :: list(), options) ::
{integer, [[selected]] | nil}
@doc """
Streams a previously prepared query.
See `c:execute/5` for a description of arguments.
It returns a stream of values.
"""
@callback stream(adapter_meta, query_meta, query_cache, params :: list(), options) ::
Enumerable.t
@doc """
Plans and prepares a query for the given repo, leveraging its query cache.
This operation uses the query cache if one is available.
"""
def prepare_query(operation, repo_name_or_pid, queryable) do
{adapter, %{cache: cache}} = Ecto.Repo.Registry.lookup(repo_name_or_pid)
{_meta, prepared, params} =
queryable
|> Ecto.Queryable.to_query()
|> Ecto.Query.Planner.ensure_select(operation == :all)
|> Ecto.Query.Planner.query(operation, cache, adapter, 0)
{prepared, params}
end
@doc """
Plans a query using the given adapter.
This does not expect the repository and therefore does not leverage the cache.
"""
def plan_query(operation, adapter, queryable) do
query = Ecto.Queryable.to_query(queryable)
{query, params, _key} = Ecto.Query.Planner.plan(query, operation, adapter)
{query, _} = Ecto.Query.Planner.normalize(query, operation, adapter, 0)
{query, params}
end
end