# `Sofa.View`
[🔗](https://github.com/skunkwerks/sofa/blob/0.8.1/lib/sofa/view.ex#L1)

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()

# `error`

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

# `t`

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

# `all_docs`

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

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

Lists the design documents of the database, via `_design_docs`.

# `from_map`

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

A result from its JSON body.

# `params`

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

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

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

Queries a view of a design document.

# `query!`

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

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

# `stream`

```elixir
@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
100) 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)

---

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