Ecto.Adapter.Queryable behaviour (Ecto v3.5.0-rc.1) View Source

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 Ecto.Adapter.__before_compile__/1 instead.

Link to this section Summary

Types

Proxy type to the adapter meta

Cache query metadata that is passed to execute/5.

Ecto.Query metadata fields (stored in cache)

Functions

Plans a query using the given adapter.

Plans and prepares a query for the given repo, leveraging its query cache.

Callbacks

Commands invoked to prepare a query.

Link to this section Types

Specs

adapter_meta() :: Ecto.Adapter.adapter_meta()

Proxy type to the adapter meta

Specs

cached() :: term()

Specs

options() :: Keyword.t()

Specs

prepared() :: term()

Specs

query_cache() ::
  {:nocache, prepared()}
  | {:cache, cache_function :: (cached() -> :ok), prepared()}
  | {:cached, update_function :: (cached() -> :ok),
     reset_function :: (prepared() -> :ok), cached()}

Cache query metadata that is passed to 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 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 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 execute/5, it will receive the :cache tuple.

Specs

query_meta() :: %{sources: tuple(), preloads: term(), select: map()}

Ecto.Query metadata fields (stored in cache)

Specs

selected() :: term()

Link to this section Functions

Link to this function

plan_query(operation, adapter, queryable)

View Source

Plans a query using the given adapter.

This does not expect the repository and therefore does not leverage the cache.

Link to this function

prepare_query(operation, repo_name_or_pid, queryable)

View Source

Plans and prepares a query for the given repo, leveraging its query cache.

This operation uses the query cache if one is available.

Link to this section Callbacks

Link to this callback

execute(adapter_meta, query_meta, query_cache, params, options)

View Source

Specs

execute(
  adapter_meta(),
  query_meta(),
  query_cache(),
  params :: list(),
  options()
) :: {integer(), [[selected()]] | nil}

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 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.

Specs

prepare(atom :: :all | :update_all | :delete_all, query :: Ecto.Query.t()) ::
  {:cache, prepared()} | {:nocache, prepared()}

Commands invoked to prepare a query.

It is used on Ecto.Repo.all/2, Ecto.Repo.update_all/3, and 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 execute/5.

Link to this callback

stream(adapter_meta, query_meta, query_cache, params, options)

View Source

Specs

stream(adapter_meta(), query_meta(), query_cache(), params :: list(), options()) ::
  Enumerable.t()

Streams a previously prepared query.

See execute/5 for a description of arguments.

It returns a stream of values.