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

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

# `error`

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

# `selector`

```elixir
@type selector() :: %{optional(String.t()) =&gt; term()}
```

# `t`

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

# `delete_index`

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

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

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

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

# `find!`

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

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

# `from_map`

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

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

# `index`

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

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

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

---

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