Design documents: the _design/ documents that hold views, filters and
validation functions, built as pipelines and saved like any document.
If the only tool you have is CouchDB, then everything looks like
{:ok, :relax}
See https://docs.couchdb.org/en/stable/api/ddoc/common.html and the
design documents guide. A design document is an ordinary %Sofa.Doc{}
whose id starts with _design/, so Sofa.Doc.save/2, Sofa.Doc.get/3
and Sofa.Attachment all apply. This module builds them and reads
their index information.
Examples
JavaScript functions are written with the ~JS sigil, see sigil_JS/2:
import Sofa.Design, only: [sigil_JS: 2]
by_title = ~JS"""
function(doc) {
if (doc.title) emit(doc.title, null);
}
"""
by_ingredient = ~JS"""
function(doc) {
doc.ingredients.forEach(function(i) { emit(i, 1); });
}
"""
validate = ~JS"""
function(newDoc, oldDoc, userCtx) {
if (!newDoc.title) throw({forbidden: 'needs a title'});
}
"""
Sofa.Design.new("recipes")
|> Sofa.Design.view("by_title", by_title)
|> Sofa.Design.view("by_ingredient", by_ingredient, "_sum")
|> Sofa.Design.filter("important", ~JS"function(doc, req) { return doc.important === true; }")
|> Sofa.Design.validate(validate)
|> Sofa.Doc.save(db)
{:ok, %{"name" => "recipes", "view_index" => %{"language" => "javascript"}}} = Sofa.Design.info(db, "recipes")
Sofa.View.query(db, "recipes", "by_title")
Summary
Functions
Every design document of the database, as %Sofa.Doc{} structs.
Adds a filter function, for Sofa.Changes and replication with filter: "{name}/{filter}".
Fetches a design document by name, with or without the _design/ prefix.
Bang! version of get/3.
The index information of a design document, via _info: its name and
a "view_index" map with the signature, sizes, update sequence and
whether an update or compaction is running, as documented.
A new design document named _design/{name}, in JavaScript unless
language: says otherwise. Further options go into the body as given:
views:, filters:, updates:, validate_doc_update:, options:,
autoupdate:.
A JavaScript function as a string, for views, filters, updates and validation. Nothing is interpolated or escaped, so the function reads exactly as CouchDB will store it.
Adds an update function, as called via /{db}/_design/{ddoc}/_update/{name}.
Sets the validate_doc_update function, which CouchDB runs on every write to the database.
Adds a view with a map function and, optionally, a reduce function such as "_sum".
Types
@type error() :: Sofa.Response.error() | term()
Functions
@spec all(Sofa.t()) :: {:ok, [Sofa.Doc.t()]} | {:error, error()}
Every design document of the database, as %Sofa.Doc{} structs.
@spec filter(Sofa.Doc.t(), String.t(), String.t()) :: Sofa.Doc.t()
Adds a filter function, for Sofa.Changes and replication with filter: "{name}/{filter}".
@spec get(Sofa.t(), String.t(), keyword()) :: {:error, error()} | Sofa.Doc.t()
Fetches a design document by name, with or without the _design/ prefix.
@spec get!(Sofa.t(), String.t(), keyword()) :: Sofa.Doc.t()
Bang! version of get/3.
The index information of a design document, via _info: its name and
a "view_index" map with the signature, sizes, update sequence and
whether an update or compaction is running, as documented.
@spec new(String.t(), keyword()) :: Sofa.Doc.t()
A new design document named _design/{name}, in JavaScript unless
language: says otherwise. Further options go into the body as given:
views:, filters:, updates:, validate_doc_update:, options:,
autoupdate:.
A JavaScript function as a string, for views, filters, updates and validation. Nothing is interpolated or escaped, so the function reads exactly as CouchDB will store it.
import Sofa.Design, only: [sigil_JS: 2]
~JS"""
function(doc) {
if (doc.title) emit(doc.title, null);
}
"""The single-line form ~JS"function(doc) { emit(doc._id, 1); }" suits
short functions. The sigil takes no modifiers.
@spec update(Sofa.Doc.t(), String.t(), String.t()) :: Sofa.Doc.t()
Adds an update function, as called via /{db}/_design/{ddoc}/_update/{name}.
@spec validate(Sofa.Doc.t(), String.t()) :: Sofa.Doc.t()
Sets the validate_doc_update function, which CouchDB runs on every write to the database.
@spec view(Sofa.Doc.t(), String.t(), String.t(), String.t() | nil) :: Sofa.Doc.t()
Adds a view with a map function and, optionally, a reduce function such as "_sum".