Dowser.
View Source
The OpenSearch document APIs — the endpoints tagged Document in the
OpenSearch OpenAPI specification
(single-document CRUD, bulk, multi-get, term vectors).
Built on Dowser.Client. Required OpenSearch attributes are positional
arguments; everything optional lives in opts.
Note that the by-query operations live in Dowser.Opensearch.Reindex, not
here: OpenSearch tags _delete_by_query, _update_by_query and _reindex
as Reindex, where Elasticsearch groups them with the document APIs.
Shared conventions
- 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 asdocumentoroperations) otherwise. :index— optional index target where the endpoint accepts one; endpoints that require an index take it as an argument.HEADexistence checks come as a pair where the?variant plays the bang role:exists/3returns{:ok, boolean()}or{:error, exception},exists?/3returns the bare boolean (404→false) and raises on genuine errors.
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).
Values are cast automatically wherever Dowser.Opensearch.Codec is
configured as :decoder/:encoder — no per-call option needed. A response
carries each document's own _index, so reads need telling nothing; the
writing functions name the index each source is going to and where in the
request body it sits, which is the mapping the encoder needs.
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
Performs several index/create/update/delete operations in one request (Bulk API).
Like bulk/2, but returns the body directly or raises the error exception —
including the Dowser.Opensearch.BulkError a partial failure returns, so it
raises unless every item was applied.
Creates the document id, failing if it already exists
(Create document API).
Like create/4, but returns the body directly or raises the error exception.
Deletes the document id
(Delete document API).
Like delete/3, but returns the body directly or raises the error exception.
Checks whether the document id exists
(Document exists API).
Like exists/3, but returns the boolean directly (404 → false) or
raises the error exception.
Retrieves the document id
(Get document API).
Like get/3, but returns the body directly or raises the error exception.
Retrieves the source of the document id, without metadata
(Get document source API).
Like get_source/3, but returns the body directly or raises the error
exception.
Indexes (creates or replaces) a document (Index document API).
Like index/3, but returns the body directly or raises the error exception.
Retrieves several documents in one request (Multi-get API).
Like mget/2, but returns the body directly or raises the error exception.
Returns term vectors for several documents in one request (Multi term vectors API).
Like mtermvectors/2, but returns the body directly or raises the error
exception.
Checks whether the document id exists and has a source
(Source exists API).
Like source_exists/3, but returns the boolean directly (404 → false)
or raises the error exception.
Returns term and field statistics for a stored or artificial document (Term vectors API).
Like termvectors/3, but returns the body directly or raises the error
exception.
Updates the document id with a script or a partial document
(Update document API).
Like update/4, but returns the body directly or raises the error exception.
Types
@type body() :: term()
@type exists_result() :: {:ok, boolean()} | {:error, Exception.t()}
@type id() :: String.t()
@type index() :: Dowser.Opensearch.Target.t()
@type result() :: {:ok, body()} | {:error, Exception.t()}
Functions
Performs several index/create/update/delete operations in one request (Bulk API).
operations is a flat list alternating action and payload maps, encoded as
NDJSON:
Dowser.Opensearch.Document.bulk([
%{index: %{_id: "1"}},
%{title: "hello"},
%{delete: %{_id: "2"}}
])Options
:index— default index target for actions that name none.
Per-item failures
A bulk request is not all-or-nothing. OpenSearch answers 200 OK with
"errors" => true and an items entry per action, so a request whose
documents were half rejected — a per-item 429 under load, a mapping
failure — looks like a successful one at the HTTP level.
So {:ok, body} here means every item was applied. As soon as one failed,
the result is {:error, %Dowser.Opensearch.BulkError{}}, which reports what
failed, what succeeded, and which operations are worth resubmitting:
{:error, %BulkError{failed: failed, succeeded: 488, retryable: operations}} =
Dowser.Opensearch.Document.bulk(operations, index: "posts")Only the rejected items (429/503) are listed in :retryable;
resubmitting those writes nothing twice, where resending the whole payload
would index the successful items a second time.
Like bulk/2, but returns the body directly or raises the error exception —
including the Dowser.Opensearch.BulkError a partial failure returns, so it
raises unless every item was applied.
Creates the document id, failing if it already exists
(Create document API).
document is the document body.
Like create/4, but returns the body directly or raises the error exception.
Deletes the document id
(Delete document API).
Like delete/3, but returns the body directly or raises the error exception.
@spec exists(index(), id(), keyword()) :: exists_result()
Checks whether the document id exists
(Document exists API).
Returns {:ok, true}, {:ok, false} or {:error, exception}.
Like exists/3, but returns the boolean directly (404 → false) or
raises the error exception.
Retrieves the document id
(Get document API).
Like get/3, but returns the body directly or raises the error exception.
Retrieves the source of the document id, without metadata
(Get document source API).
Like get_source/3, but returns the body directly or raises the error
exception.
Indexes (creates or replaces) a document (Index document API).
document is the document body.
Options
:id— document id; absent to let OpenSearch generate one.
Like index/3, but returns the body directly or raises the error exception.
Retrieves several documents in one request (Multi-get API).
body is the request body, e.g. %{ids: ["1", "2"]} or %{docs: [...]}.
Options
:index— index target; absent when each doc names its own.
Like mget/2, but returns the body directly or raises the error exception.
Returns term vectors for several documents in one request (Multi term vectors API).
body is the request body, e.g. %{docs: [...]} or %{ids: [...]}.
Options
:index— index target; absent when each doc names its own.
Like mtermvectors/2, but returns the body directly or raises the error
exception.
@spec source_exists(index(), id(), keyword()) :: exists_result()
Checks whether the document id exists and has a source
(Source exists API).
Returns {:ok, true}, {:ok, false} or {:error, exception}.
Like source_exists/3, but returns the boolean directly (404 → false)
or raises the error exception.
Returns term and field statistics for a stored or artificial document (Term vectors API).
body is the request body (e.g. doc, fields, filter); pass %{} to
send nothing.
Options
:id— stored document id; absent when analyzing adocfrom the body.
Like termvectors/3, but returns the body directly or raises the error
exception.
Updates the document id with a script or a partial document
(Update document API).
body is the update body, e.g. %{doc: %{title: "hi"}} or
%{script: %{...}}.
Like update/4, but returns the body directly or raises the error exception.