#+TITLE: clutch MongoDB Backend Guide

* MongoDB Backend

The =mongodb= backend is Clutch's ordinary MongoDB backend.  This guide focuses on Clutch-owned native document query, object, and read-only result workflows.  Support levels and the one-backend boundary, including the =:surface sql-interface= distinction, are defined in [[file:backend-support.org][docs/backend-support.org]].  The default document surface delegates native protocol operations to the external =mongodb.el= package and uses supported MongoDB Shell / MQL helper syntax in query buffers, not SQL and not arbitrary JavaScript.

** Requirements

The default document surface requires the =mongodb.el= package on =load-path=. It does not require Java, =mongosh=, or a JDBC jar.

MongoDB SQL Interface endpoints require the JDBC sidecar and MongoDB JDBC driver jar:

#+begin_src emacs-lisp
(clutch-jdbc-ensure-agent)
(clutch-jdbc-install-driver 'mongodb)
#+end_src

=clutch-jdbc-install-driver 'mongodb= downloads the official MongoDB SQL Interface JDBC driver and stores it as =~/.emacs.d/clutch-jdbc/drivers/mongodb-jdbc.jar=.

** Connection Examples

#+begin_src emacs-lisp
(setq clutch-connection-alist
      '(("local-mongodb" . (:backend mongodb
                           :host "127.0.0.1"
                           :port 27017
                           :database "app"))

        ("local-mongodb-auth" . (:backend mongodb
                                :host "127.0.0.1"
                                :port 27017
                                :database "app"
                                :auth-database "admin"
                                :user "root"
                                :pass-entry "local-mongodb-auth"))

        ("atlas-sql" . (:backend mongodb
                         :surface sql-interface
                         :url "jdbc:mongodb://cluster0.a.query.mongodb.net/admin"
                         :database "analytics"
                         :user "reporter"
                         :pass-entry "atlas-sql"))))
#+end_src

Clutch passes native connection parameters to =mongodb.el= after resolving saved credentials.  Native connection URLs and protocol options are owned by =mongodb.el=; consult its [[https://github.com/LuciusChen/mongodb.el][documentation]] for the supported native connection surface rather than this guide.

Use =:password= only when the password is already available in memory.  For saved connections, prefer =:pass-entry= and let Clutch resolve it through =auth-source-pass= / =auth-source= before opening the native connection.  Unauthenticated local MongoDB connections do not need =:user=, =:password=, or =:pass-entry=.

Clutch-managed SSH tunnels and TRAMP forwarding require structured =:host= / =:port= parameters because Clutch rewrites that endpoint before connecting.  Clutch does not rewrite opaque =:url= values; use structured parameters when a saved MongoDB connection needs Clutch-managed forwarding.

** Query Buffers

Native MongoDB query buffers use =clutch-mongodb-mode= from =clutch-document.el=, the document query-console layer.  The mode is Clutch UI code: it fontifies and completes a supported MongoDB Shell / MQL helper surface, then the backend translates those helpers into native =mongodb.el= command calls. It keeps the shared execute, object, schema/database, and completion shortcuts, but does not bind SQL-only transaction controls.  =C-c C-p= explains the current =find=, =findOne=, or =aggregate= helper and shows formatted JSON with a compact execution summary.  =C-c ?= opens the MongoDB document-console dispatch menu.

Completion intentionally covers common helper, stage, operator, collection, and sampled field names for basic support.  It also offers cursor helper chains after =find(...).= and =aggregate(...).= so query-bar controls common in GUI MongoDB clients remain discoverable in the Emacs query buffer.  Projection stays as the second =find= argument; =find(...).= completion offers =sort()=, =skip()=, =limit()=, =maxTimeMS()=, =allowDiskUse()=, and =explain()=. =aggregate(...).= completion offers =allowDiskUse()=, =maxTimeMS()=, and =explain()=.  Field completion and collection metadata sample up to =clutch-mongodb-schema-sample-size= documents, merge field paths from those documents, and report sampled BSON type summaries. Collection-method completion also offers lightweight templates such as =find({}).limit(20)=, projected =find=, common =aggregate= skeletons, and a =$lookup= skeleton.  These are plain completion candidates, not a separate query builder.  They are not MongoDB server-enforced schemas or an exhaustive field catalog; long-tail operators can still be typed manually when the backend helper parser and =mongodb.el= command layer support the query shape.

Native =find()= results are bounded by =clutch-mongodb-find-result-limit= (default 1000).  A smaller explicit =.limit(N)= is honored; zero, negative, or larger limits are rejected before sending the command.  Narrow the filter or use =skip()= with a bounded =limit()= when exploring a large collection.

Supported helper families include:

- collection reads: =find=, =findOne=, =aggregate=, =countDocuments=, =distinct=, and =explain=
- generated document mutations: =insertOne=, =insertMany=, =updateOne=, =replaceOne=, and =deleteOne=
- uncommon commands: =db.runCommand(...)= against the current database

Database selection uses the shared =clutch-switch-schema= workflow.  Dedicated MongoDB Shell admin, index-management, shell-shaped database-switching helpers, and multi-document mutation helpers are intentionally outside the basic console surface.

Write helpers validate their documented argument shape before calling =mongodb.el=.  =insertOne= accepts one document, =insertMany= accepts one document array, and =deleteOne= requires one explicit filter document.

=updateOne= requires a nonempty document whose top-level keys are update operators, such as ={$set: {name: 'Ann'}}=. Plain documents and mixed operator/field documents are rejected; use =replaceOne= for a replacement document. =replaceOne= rejects top-level update operators. Update pipelines remain unsupported by the helper parser.

=ObjectId()= and =ISODate()= encode the common non-JSON query literals as native BSON wrapper values before being sent to =mongodb.el=.

This parser is intentionally not a general JavaScript runtime.  Unsupported helpers and Mongo shell-only syntax such as regex literals should fail clearly instead of being passed to a shell process.

** Clutch Mapping

Clutch maps MongoDB concepts onto the generic database contract:

- schemas are MongoDB databases
- tables are collections
- columns are sampled document field paths with sampled BSON type summaries
- indexes are collection indexes returned by the public MongoDB client API
- nested documents and arrays render as JSON-valued cells

Object actions use the same =C-c C-o= / Embark workflow as SQL backends.  For a MongoDB collection, Describe shows a formatted JSON schema profile with sampled field paths, presence counts, type counts, examples, top scalar values, and collection indexes.  Show definition displays collection metadata as JSON. Browse inserts a =db.getCollection(...).find({}).limit(20);= helper.  Show index insight combines index definitions with =$indexStats= usage data.  Show stats displays formatted JSON with collection-level =count=, =avgObjSize=, =storageSize=, =totalIndexSize=, =totalSize=, and =indexSizes= values from a =$collStats= aggregation.  Explain sample query uses the same backend explain path as =C-c C-p= and explains =find({}).limit(1)= with =executionStats=.  Show validation displays collection =validator= / =validationAction= / =validationLevel= collection metadata. Profile, index insight, stats, explain, and validation are MongoDB document features; Clutch exposes them through the shared object action UI for workflow consistency, not as SQL-compatible features or query-result footer fields.

MongoDB result grids are read-only.  Nested documents, arrays, and mixed scalar/document columns are marked as JSON-valued where the sample shows JSON content, so the normal Clutch value viewers can pretty-print them.  Staged SQL =UPDATE= / =DELETE= workflows, SQL-style manual transaction toggles, and row identity editing remain disabled for the native document surface.  Result-level copy/refine, CSV/TSV/Org table export, client-side filtering, and aggregate remain available because they operate on the displayed grid.  When a result came from a collection helper and Clutch kept the source document metadata, copy and export actions can generate MongoDB helper snippets such as =insertOne=, =insertMany=, =replaceOne=, =updateOne({ _id }, { $set: ... })=, and =deleteOne=.

MongoDB SQL Interface is different: it is a JDBC SQL surface selected with =:surface sql-interface=, uses SQL query buffers, and requires an endpoint that actually provides MongoDB SQL Interface.

** Live Tests

MongoDB live coverage is tagged =:mongodb-live=.  The live runner starts or reuses a local MongoDB container and exercises the native document surface; it verifies switching the active database, querying the target database, and restoring the original database:

#+begin_src sh
./test/run-ci.sh native-live
#+end_src

Manual local container example:

#+begin_src sh
docker run -d --name clutch-mongodb-live -p 27017:27017 mongo:7
#+end_src

MongoDB SQL Interface JDBC live tests are separate and remain tagged =:sql-interface-mongodb-live= because they require an Atlas or Enterprise Advanced SQL Interface endpoint.