# `Ecto.Adapter.Queryable`
[🔗](https://github.com/elixir-ecto/ecto/blob/v3.13.6/lib/ecto/adapter/queryable.ex#L1)

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.

# `adapter_meta`

```elixir
@type adapter_meta() :: Ecto.Adapter.adapter_meta()
```

Proxy type to the adapter meta

# `cached`

```elixir
@type cached() :: term()
```

# `options`

```elixir
@type options() :: Keyword.t()
```

# `prepared`

```elixir
@type prepared() :: term()
```

# `query_cache`

```elixir
@type 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 `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.

# `query_meta`

```elixir
@type query_meta() :: %{sources: tuple(), preloads: term(), select: map()}
```

Ecto.Query metadata fields (stored in cache)

# `selected`

```elixir
@type selected() :: term()
```

# `execute`

```elixir
@callback execute(
  adapter_meta(),
  query_meta(),
  query_cache(),
  params :: list(),
  options()
) ::
  {non_neg_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 `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.

# `prepare`

```elixir
@callback 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 `c:Ecto.Repo.all/2`, `c:Ecto.Repo.update_all/3`,
and `c:Ecto.Repo.delete_all/2`. It returns a tuple, indicating 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`.

# `stream`

```elixir
@callback stream(adapter_meta(), query_meta(), query_cache(), params :: list(), options()) ::
  Enumerable.t()
```

Streams a previously prepared query.

See `c:execute/5` for a description of arguments.

It returns a stream of values.

# `plan_query`

Plans a query using the given adapter.

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

# `prepare_query`

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

This operation uses the query cache if one is available.

---

*Consult [api-reference.md](api-reference.md) for complete listing*