Dowser.
View Source
The OpenSearch search APIs — the endpoints tagged Search in the
OpenSearch OpenAPI specification.
Built on Dowser.Client. Required OpenSearch attributes are positional
arguments; everything optional lives in opts. Request bodies come first so
they pipe naturally.
Shared conventions
:index— where the endpoint accepts an optional index target:nil/absent for all indices, a single index string, or a list of index strings (joined with,). Endpoints that require an index take it as the first argument instead.- Endpoints that accept a request body take it as their first argument,
required — pass
%{}to send nothing. The argument is namedquerywhen the body is an OpenSearch query DSL document, andbody(or a more specific name such astemplateorsearches) otherwise. - When OpenSearch serves an operation over both
GETandPOST, the request usesPOSTwhenever a body is present andGETotherwise.
All remaining options are forwarded to Dowser.Client.request/4, e.g.
:context, :params (query-string parameters), :format, :keys and
:http_opts (including :headers) — plus :codec, this package's own,
which picks the per-field codec for this one request (see
Dowser.Opensearch.Codec).
Response values are cast automatically wherever Dowser.Opensearch.Codec is
configured as :decoder — no per-call option needed. A query is never cast:
build it in the shape OpenSearch expects.
On a 2xx response every function returns {:ok, body} with the decoded
response body. A non-2xx response returns
{:error, %Dowser.Opensearch.Error{}}; a transport, encoding or decoding
failure returns {:error, exception} from Dowser.Client. A required
argument that is missing or empty is reported the same way, before any
request is made: {:error, %ArgumentError{}}. Each function has a bang
variant that returns the body directly or raises the error exception.
Summary
Functions
Releases one or several scroll contexts (Clear scroll API).
Like clear_scroll/2, but returns the body directly or raises the error
exception.
Counts the documents matching a query (Count API).
Like count/2, but returns the body directly or raises the error exception.
Creates a point in time over index, to search a fixed view of the data
(Create PIT API).
Like create_pit/3, but returns the body directly or raises the error
exception.
Deletes every point in time (Delete all PITs API).
Like delete_all_pits/1, but returns the body directly or raises the error
exception.
Deletes one or several points in time (Delete PIT API).
Like delete_pit/2, but returns the body directly or raises the error
exception.
Explains whether and how the document id in index matches a query
(Explain API).
Like explain/4, but returns the body directly or raises the error exception.
Returns the capabilities of fields across indices (Field capabilities API).
Like field_caps/2, but returns the body directly or raises the error
exception.
Lists every point in time currently open (List all PITs API).
Like get_all_pits/1, but returns the body directly or raises the error
exception.
Runs several searches in one request (Multi-search API).
Like msearch/2, but returns the body directly or raises the error exception.
Runs several template searches in one request (Multi-search template API).
Like msearch_template/2, but returns the body directly or raises the error
exception.
Renders a search template into the actual search body it would run (Render search template API).
Like render_search_template/2, but returns the body directly or raises the
error exception.
Fetches the next page of a scrolling search (Scroll API).
Like scroll/2, but returns the body directly or raises the error exception.
Runs a search against one, several, or all indices (Search API).
Like search/2, but returns the body directly or raises the error exception.
Returns the indices and shards a search would run against (Search shards API).
Like search_shards/1, but returns the body directly or raises the error
exception.
Runs a search with a stored or inline search template (Search template API).
Like search_template/2, but returns the body directly or raises the error
exception.
Validates a query without running it (Validate query API).
Like validate_query/2, but returns the body directly or raises the error
exception.
Types
@type body() :: term()
@type id() :: String.t()
@type index() :: Dowser.Opensearch.Target.t()
@type query() :: map()
@type result() :: {:ok, body()} | {:error, Exception.t()}
Functions
Releases one or several scroll contexts (Clear scroll API).
scroll_id is a scroll id, a list of scroll ids, or "_all".
Like clear_scroll/2, but returns the body directly or raises the error
exception.
Counts the documents matching a query (Count API).
query is the count body (query DSL map); pass %{} to count everything.
Options
:index— index target; absent for all indices.
Like count/2, but returns the body directly or raises the error exception.
Creates a point in time over index, to search a fixed view of the data
(Create PIT API).
keep_alive is how long the point in time is kept alive, e.g. "1m"; it is
sent as the required keep_alive query-string parameter. The endpoint takes
no request body.
Note that this is not Elasticsearch's /_pit: OpenSearch serves the whole
point-in-time API under /_search/point_in_time, and the id it returns is
named pit_id rather than id.
{:ok, %{"pit_id" => pit_id}} =
Dowser.Opensearch.Search.create_pit("posts", "5m")
Dowser.Opensearch.Search.search!(%{pit: %{id: pit_id}})Like create_pit/3, but returns the body directly or raises the error
exception.
Deletes every point in time (Delete all PITs API).
Like delete_all_pits/1, but returns the body directly or raises the error
exception.
Deletes one or several points in time (Delete PIT API).
pit_id is one id or a list of them; a single id is wrapped, since
OpenSearch requires the body's pit_id to be an array.
Like delete_pit/2, but returns the body directly or raises the error
exception.
Explains whether and how the document id in index matches a query
(Explain API).
query is the explain body (query DSL map).
Like explain/4, but returns the body directly or raises the error exception.
Returns the capabilities of fields across indices (Field capabilities API).
body is the request body, e.g.
%{fields: ["title"], index_filter: %{...}}.
Options
:index— index target; absent for all indices.
Like field_caps/2, but returns the body directly or raises the error
exception.
Lists every point in time currently open (List all PITs API).
Like get_all_pits/1, but returns the body directly or raises the error
exception.
Runs several searches in one request (Multi-search API).
searches is a flat list alternating header and body maps, encoded as
NDJSON:
Dowser.Opensearch.Search.msearch([
%{},
%{query: %{match_all: %{}}},
%{index: "comments"},
%{query: %{match: %{body: "hello"}}}
])Options
:index— default index target for searches whose header has none.
Like msearch/2, but returns the body directly or raises the error exception.
Runs several template searches in one request (Multi-search template API).
searches is a flat list alternating header and template-body maps, encoded
as NDJSON (see msearch/2).
Options
:index— default index target for searches whose header has none.
Like msearch_template/2, but returns the body directly or raises the error
exception.
Renders a search template into the actual search body it would run (Render search template API).
template is the request body, typically %{params: %{...}} alongside an
id or a source.
Options
:id— the stored template to render, appended to the path. Omit it for an inlinesourcegiven in the body.
Like render_search_template/2, but returns the body directly or raises the
error exception.
Fetches the next page of a scrolling search (Scroll API).
Sends scroll_id in the request body, the form OpenSearch recommends over
the deprecated path parameter.
Options
:scroll— how long to keep the scroll context alive, e.g."1m"; merged into the body.
Like scroll/2, but returns the body directly or raises the error exception.
Runs a search against one, several, or all indices (Search API).
query is the search body (the OpenSearch query DSL as a map); pass %{}
to match everything. It comes first so it can be piped:
%{query: %{match: %{title: "hello"}}}
|> Dowser.Opensearch.Search.search(index: "posts")Every key in the response is cast per :keys. Wherever
Dowser.Opensearch.Codec is configured as :decoder, each hit's _source
is additionally cast against its own index mapping (dates become DateTime,
IPs become :inet tuples, and so on) — automatically, at any nesting depth,
so msearch/2, search_template/2, scroll/2 and the rest get the same
treatment with no extra options.
Options
:index—nil/absent for all indices, a single index string, or a list of index strings (joined with,).
Like search/2, but returns the body directly or raises the error exception.
Returns the indices and shards a search would run against (Search shards API).
Options
:index— index target; absent for all indices.
Like search_shards/1, but returns the body directly or raises the error
exception.
Runs a search with a stored or inline search template (Search template API).
template is the request body, e.g. %{id: "my-template", params: %{...}}
or %{source: %{...}, params: %{...}}.
Options
:index— index target; absent for all indices.
Like search_template/2, but returns the body directly or raises the error
exception.
Validates a query without running it (Validate query API).
query is the query body to check; pass %{} to validate nothing in
particular. Use params: [explain: true] to get the reason a query is
rejected rather than just valid: false.
Options
:index— index target; absent for all indices.
Like validate_query/2, but returns the body directly or raises the error
exception.