The Complete Production SOP: How to Deploy and Run Apache CouchDB MapReduce Views & Offline Sync in Autonomous AI Agents

---
name: "couchdb-mapreduce-views"
description: "Build document databases with ACID document revisions, JavaScript MapReduce, and HTTP API."
metadata:
  author: "Apache Software Foundation"
  version: "1.0.0"
  runtime_compatibility:
    - "codex"
    - "claude-code"
    - "cursor"
    - "windsurf"
triggers:
  - "create couchdb map view"
  - "setup couchdb replication"
  - "resolve couchdb document conflicts"
permissions:
  fs_read: true
  fs_write: "workspace"
  shell_exec: false
  net_access: false
---

# Apache CouchDB MapReduce Views & Offline Sync Rules
1. Always create design docs with compound keys: emit([doc.type, doc.date], doc.metric).
2. Use built-in reducers (_sum, _count, _stats) instead of custom JS reduce for speed.
3. Query views with stale=update_after and group_level=N to control aggregation depth.
4. Handle 409 conflicts idempotently: fetch conflicting revs via ?conflicts=true, resolve leaf nodes, and DELETE stale revisions.

{
  "_id": "_design/analytics",
  "views": {
    "by_year_month": {
      "map": "function (doc) { if (doc.type === 'telemetry' && doc.timestamp) { var d = new Date(doc.timestamp); emit([d.getUTCFullYear(), d.getUTCMonth() + 1], doc.duration); } }",
      "reduce": "_sum"
    }
  },
  "language": "javascript"
}

import nano from 'nano';

const couch = nano(process.env.COUCHDB_URL || 'http://admin:[email protected]:5984');

export async function setupBidirectionalSync(localDb, remoteDb) {
  const replicator = couch.use('_replicator');
  
  const outbound = {
    _id: `sync_${localDb}_to_remote`,
    source: localDb,
    target: remoteDb,
    continuous: true,
    create_target: true
  };

  const inbound = {
    _id: `sync_remote_to_${localDb}`,
    source: remoteDb,
    target: localDb,
    continuous: true
  };

  await replicator.insert(outbound).catch(err => { if (err.statusCode !== 409) throw err; });
  await replicator.insert(inbound).catch(err => { if (err.statusCode !== 409) throw err; });
}

import nano from 'nano';

const couch = nano(process.env.COUCHDB_URL || 'http://admin:[email protected]:5984');
const db = couch.use('production_metrics');

export async function resolveDocumentConflicts(docId) {
  const doc = await db.get(docId, { conflicts: true });
  if (!doc._conflicts || doc._conflicts.length === 0) {
    return { status: 'no_conflict', rev: doc._rev };
  }

  // Deterministic winner selection or merge strategy
  for (const conflictRev of doc._conflicts) {
    const staleDoc = await db.get(docId, { rev: conflictRev });
    // Merge custom business fields if necessary
    await db.destroy(docId, conflictRev);
  }

  return { status: 'resolved', winnerRev: doc._rev, purgedRevs: doc._conflicts };
}