What does emit(key, value) in a CouchDB map function build, and when is that index updated?

## A view is a materialized, sorted index CouchDB has no ad-hoc query planner for views. You declare, in advance, a JavaScript `map` function stored inside a design document (`_design/…`), and CouchDB runs it against every document in the database. The function's only output channel is `emit(key, value)`. Each call produces one row `(key, value, id)`; a function that calls `emit` three times for one document produces three rows, and a function that calls it zero times excludes the document entirely — which is how you build filtered indexes. Those rows are stored in a B-tree ordered by key. That single fact determines everything a view can do. ## Querying is range scanning Because the index is a sorted tree, the query surface is deliberately small: `GET /db/_design/{ddoc}/_view/{name}` accepts `key` for an exact match, `keys` for a set, `startkey` and `endkey` for a range, and modifiers `descending`, `limit`, `skip`, and `include_docs`. There is no arbitrary filtering, no OR across unrelated fields, no sorting by anything except the key. If you need a different access path, you emit a different key — often a **compound key**, an array such as `[customerId, orderDate]`, which lets you range-scan all of one customer's orders in date order with `startkey=["c1", "2026-01-01"]` and `endkey=["c1", "2026-02-01"]`. Keys sort by CouchDB's collation, which orders across JSON types in a fixed sequence: `null`, then booleans, then numbers, then strings (compared with Unicode collation, not raw byte order), then arrays, then objects. Two consequences bite people: string ordering follows ICU collation rather than ASCII byte order, and `descending=true` reverses the traversal, so you must also swap `startkey` and `endkey`. ## Incremental maintenance The index is not rebuilt from scratch on each query. CouchDB records how far through the database's change sequence the index has been built. On the next query, it maps only the documents that changed since that point, updates the affected B-tree rows, records the new sequence, and answers. Cost is therefore proportional to churn since the last read, not to database size — with one nasty corollary: a view that is queried once a day pays for a day of changes on that one query, and the first query after a bulk import can take a very long time. The update behaviour is controllable per query. The default builds before answering. `update=false` answers immediately from the index as it stands, which may be missing recent writes — the right choice for dashboards and autocomplete. `update=lazy` answers from the current index and kicks off a background refresh, which keeps a rarely-read view roughly warm. Production deployments commonly add a small "warmer" job that queries each view with `limit=0` after big writes, so no user request ever eats the build. ## Design documents are the unit of indexing All views inside one design document form a single index group, built and stored together. Adding a view to an existing design document therefore forces the whole group to rebuild. Worse, changing so much as whitespace in a map function changes the design document's content, which changes the index identity and triggers a complete rebuild for every view in it. The standard mitigation is to deploy a *new* design document, warm its index in the background, then switch reads over and delete the old one — a blue/green swap. `POST /db/_view_cleanup` removes the index files orphaned by that swap. ## Map functions must be pure Because the index is incremental, a map function must be a deterministic function of the single document passed to it. It cannot read other documents, cannot call out to the network, and must not use the clock or a random number: a document mapped last Tuesday will keep last Tuesday's output until that document itself changes, so `Date.now()` in a map function bakes in a stale value and produces an index that is wrong in ways no error will report. ## emit(key, doc) versus include_docs Emitting the whole document as the value makes reads a single B-tree scan with no extra lookups, but duplicates the document into the index file and inflates it. `include_docs=true` keeps the index small and fetches each document by id at query time, at the cost of a lookup per row and a small race: the document returned is the current one, which may be newer than the row that pointed at it. Emit `null` and use `include_docs` for large documents; emit the two or three fields you actually render for hot, high-volume views. ## Interview framing One sentence: `emit` writes rows into a persistent B-tree sorted by key, so a CouchDB view is a precomputed index whose only query shape is a key range, refreshed incrementally at read time unless you tell it otherwise.