Ecto.Adapter.Queryable behaviour (Ecto v3.5.5) 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
Executes a previously prepared query.
Commands invoked to prepare a query.
Streams a previously prepared 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
Ecto.Query metadata fields (stored in cache)
Specs
selected() :: term()
Link to this section Functions
Plans a query using the given adapter.
This does not expect the repository and therefore does not leverage the cache.
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
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
.
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.