Sofa.View (sofa v0.7.0)

Copy Markdown View Source

Queries views, _all_docs and _design_docs, the CouchDB index reads.

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

See https://docs.couchdb.org/en/stable/api/ddoc/views.html and the _all_docs section of the database API. All three return the same shape, a %Sofa.View{} with its rows, so one module covers them.

Options

The documented query parameters, by name. Keys are JSON values and are encoded as such: key: "meatballs" is sent as key="meatballs", and startkey: ["a", 1] as a JSON array. Everything else is sent as its string form, and nil drops the parameter.

  • selection: key, keys, startkey, endkey, startkey_docid, endkey_docid, inclusive_end, descending, limit, skip
  • reduce: reduce, group, group_level
  • content: include_docs, conflicts, attachments, att_encoding_info
  • freshness: update, stable, stale, update_seq, sorted

keys is sent as a POST body, as the docs describe. With include_docs: true each row's doc is a %Sofa.Doc{}.

Examples

{:ok, view} = Sofa.View.query(db, "recipes", "by_ingredient", key: "meatballs")
view.rows
#=> [%Sofa.View.Row{id: "SpaghettiWithMeatballs", key: "meatballs", value: 1}]

Sofa.View.all_docs(db, include_docs: true, limit: 10)
Sofa.View.stream(db, "recipes", "by_ingredient", limit: 100) |> Enum.count()

Summary

Functions

Lists the documents of the database by id, via _all_docs. Each row's value carries the document's rev.

Lists the design documents of the database, via _design_docs.

A result from its JSON body.

The query string for view options: JSON for the key parameters, string form for the rest, nil dropped.

Runs several queries against one view in a single request, via the /queries endpoint, and returns one result per query, in order. Pass :all_docs or :design_docs as the view for those indexes.

Queries a view of a design document.

Bang! version of query/4. Returns the result or raises Sofa.Error.

Streams the rows of a view, fetching limit rows per request (default

Types

error()

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

t()

@type t() :: %Sofa.View{
  offset: non_neg_integer() | nil,
  rows: [Sofa.View.Row.t()],
  total_rows: non_neg_integer() | nil,
  update_seq: term() | nil
}

Functions

all_docs(sofa, opts \\ [])

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

Lists the documents of the database by id, via _all_docs. Each row's value carries the document's rev.

design_docs(sofa, opts \\ [])

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

Lists the design documents of the database, via _design_docs.

from_map(body)

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

A result from its JSON body.

params(opts)

@spec params(keyword()) :: keyword()

The query string for view options: JSON for the key parameters, string form for the rest, nil dropped.

iex> Sofa.View.params(key: "meatballs", startkey: ["a", 1], limit: 5, include_docs: true, skip: nil)
[key: ~s("meatballs"), startkey: ~s(["a",1]), limit: "5", include_docs: "true"]

queries(sofa, index, view \\ nil, queries)

@spec queries(Sofa.t(), String.t() | :all_docs | :design_docs, String.t() | nil, [
  keyword()
]) ::
  {:ok, [t()]} | {:error, error()}

Runs several queries against one view in a single request, via the /queries endpoint, and returns one result per query, in order. Pass :all_docs or :design_docs as the view for those indexes.

Sofa.View.queries(db, "recipes", "by_ingredient", [[key: "meatballs"], [key: "tomato sauce"]])

query(sofa, ddoc, view, opts \\ [])

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

Queries a view of a design document.

query!(sofa, ddoc, view, opts \\ [])

@spec query!(Sofa.t(), String.t(), String.t(), keyword()) :: t()

Bang! version of query/4. Returns the result or raises Sofa.Error.

stream(sofa, index, view \\ nil, opts \\ [])

@spec stream(
  Sofa.t(),
  String.t() | :all_docs | :design_docs,
  String.t() | nil,
  keyword()
) ::
  Enumerable.t()

Streams the rows of a view, fetching limit rows per request (default

  1. and continuing from the last row of each page, so results of any size can be consumed lazily. Raises Sofa.Error mid-stream on failure. Not for reduced results, which have no row to continue from. Pass reduce: false on a view with a reduce function.
Sofa.View.stream(db, "recipes", "by_ingredient", include_docs: true)
|> Stream.map(& &1.doc)
|> Enum.take(1000)