Sofa.Mango (sofa v0.7.0)

Copy Markdown View Source

Mango, the CouchDB declarative query API: _find, _explain and the _index endpoints.

If the only tool you have is CouchDB, then everything looks like {:ok, :relax}

See https://docs.couchdb.org/en/stable/api/database/find.html. A query is a selector, a JSON object such as %{"year" => %{"$gt" => 2010}}, plus the documented options sent alongside it in the request body: limit (default 25), skip, sort, fields, use_index, allow_fallback, conflicts, r, bookmark, update, stable, stale and execution_stats.

Matching documents come back as %Sofa.Doc{} structs, except when fields leaves out _id, in which case they stay plain maps.

Examples

{:ok, result} = Sofa.Mango.find(db, %{"year" => %{"$gt" => 2010}}, sort: [%{"year" => "asc"}], limit: 2)
Enum.map(result.docs, & &1.body["title"])
#=> ["The Tragedy of Man", "Drive"]

Sofa.Mango.index(db, ["year"], name: "by_year")
Sofa.Mango.stream(db, %{"year" => %{"$gt" => 2010}}) |> Enum.count()

Summary

Functions

Deletes a JSON index by its design document (with or without the _design/ prefix) and name.

Explains how a query would run, without running it: which index would be used, and why, as the documented _explain response.

Finds the documents matching a selector, see the module documentation for the options.

Bang! version of find/3. Returns the result or raises Sofa.Error.

A result from its JSON body. Documents with an _id become %Sofa.Doc{} structs.

Creates a JSON index on the given fields, each a field name or a %{"field" => "asc" | "desc"} map, and returns its design document id and name. CouchDB answers :exists for an identical index.

Lists the indexes of the database, as CouchDB describes them: maps with "ddoc", "name", "type" and "def". The built-in primary index on _id is always among them.

Streams every document matching a selector, fetching limit at a time (default 100) and following the bookmark CouchDB returns for the next page. Raises Sofa.Error mid-stream on failure.

Types

error()

@type error() :: Sofa.Response.error() | term()

selector()

@type selector() :: %{optional(String.t()) => term()}

t()

@type t() :: %Sofa.Mango{
  bookmark: String.t() | nil,
  docs: [Sofa.Doc.t() | map()],
  execution_stats: map() | nil,
  warning: String.t() | nil
}

Functions

delete_index(sofa, ddoc, name)

@spec delete_index(Sofa.t(), String.t(), String.t()) :: :ok | {:error, error()}

Deletes a JSON index by its design document (with or without the _design/ prefix) and name.

explain(sofa, selector, opts \\ [])

@spec explain(Sofa.t(), selector(), keyword()) :: {:ok, map()} | {:error, error()}

Explains how a query would run, without running it: which index would be used, and why, as the documented _explain response.

find(sofa, selector, opts \\ [])

@spec find(Sofa.t(), selector(), keyword()) :: {:ok, t()} | {:error, error()}

Finds the documents matching a selector, see the module documentation for the options.

find!(sofa, selector, opts \\ [])

@spec find!(Sofa.t(), selector(), keyword()) :: t()

Bang! version of find/3. Returns the result or raises Sofa.Error.

from_map(body)

@spec from_map(map()) :: t()

A result from its JSON body. Documents with an _id become %Sofa.Doc{} structs.

index(sofa, fields, opts \\ [])

@spec index(Sofa.t(), [String.t() | map()], keyword()) ::
  {:ok, %{result: :created | :exists, ddoc: String.t(), name: String.t()}}
  | {:error, error()}

Creates a JSON index on the given fields, each a field name or a %{"field" => "asc" | "desc"} map, and returns its design document id and name. CouchDB answers :exists for an identical index.

Options: name: and ddoc: to choose the names, otherwise CouchDB generates them. partial_filter_selector: to index a subset. type:, which defaults to "json". partitioned:.

Sofa.Mango.index(db, ["year", "title"], name: "by_year_title", ddoc: "movies")
#=> {:ok, %{result: :created, ddoc: "_design/movies", name: "by_year_title"}}

indexes(sofa)

@spec indexes(Sofa.t()) :: {:ok, [map()]} | {:error, error()}

Lists the indexes of the database, as CouchDB describes them: maps with "ddoc", "name", "type" and "def". The built-in primary index on _id is always among them.

stream(sofa, selector, opts \\ [])

@spec stream(Sofa.t(), selector(), keyword()) :: Enumerable.t()

Streams every document matching a selector, fetching limit at a time (default 100) and following the bookmark CouchDB returns for the next page. Raises Sofa.Error mid-stream on failure.

Sofa.Mango.stream(db, %{"type" => "order"}, fields: ["_id", "total"]) |> Enum.take(1000)