MongoDB

The MongoDB resource exposes MongoDB databases, collections, and documents as a virtual filesystem mounted at some prefix such as /mongodb/. For connection setup, see MongoDB Setup.

Config

import os

from mirage import MountMode, Workspace
from mirage.resource.mongodb import MongoDBConfig, MongoDBResource

config = MongoDBConfig(
    uri=os.environ["MONGODB_URI"],
    default_doc_limit=1000,
    default_search_limit=100,
    max_doc_limit=5000,
    elide_fields={"sample_mflix.movies": ["plot_embedding"]},
)
resource = MongoDBResource(config=config)
ws = Workspace({"/mongodb": resource}, mode=MountMode.READ)

Config field	Required	Default	Description
`uri`	yes		MongoDB connection URI
`databases`	no		List of database names to mount (omit for all)
`default_doc_limit`	no	1000	Default doc cap for one-shot reads (not used by streaming `cat`)
`default_search_limit`	no	100	Default result cap for collection/db-level `grep`
`max_doc_limit`	no	5000	Hard cap for `head -n K` / `tail -n K`
`elide_fields`	no	`{}`	`{"<db>.<coll>": ["field", "nested.path"]}`; listed fields are dropped from `documents.jsonl`

Filesystem Layout

The mount mirrors MongoDB’s cluster → database → collection / view model. The database directory always appears in the path, even when databases filters to a single entry.

/mongodb/
  <database>/
    database.json                  # collections + views + counts
    collections/
      <collection>/
        schema.json                # sampled types + indexes + validator
        documents.jsonl            # streamed BSON Extended JSON
    views/
      <view>/
        schema.json                # view-aware (no indexes / validator)
        documents.jsonl            # streamed, same format as collections

Example:

/mongodb/
  sample_mflix/
    database.json
    collections/
      movies/
        schema.json
        documents.jsonl
      comments/
        schema.json
        documents.jsonl
    views/
      top_rated_movies/
        schema.json
        documents.jsonl

documents.jsonl

One JSON object per line, encoded with BSON Relaxed Extended JSON. BSON-specific types round-trip through their canonical $ wrappers:

{"_id":{"$oid":"573a1390f29313caabcd4135"},"title":"Casablanca","released":{"$date":"1943-01-23T00:00:00Z"},"runtime":102}

cat / head / tail / grep / jq all stream from this file; nothing materializes the full collection in memory. Because the file is rendered on demand, stat / ls -l report no size and du returns 0 for it (computing the real size would require rendering the whole collection). Use wc -c documents.jsonl for the actual rendered byte count; stat still exposes document_count for the number of documents.

schema.json

Generated from a 100-document $sample. Includes:

field path → observed BSON type frequencies (nested paths unioned across the sample)
indexes from listIndexes plus access counts from $indexStats
the $jsonSchema validator if one is registered

Views skip the index and validator sections.

database.json

Lists every collection and view under the database with their document counts. Useful for cat /mongodb/<db>/database.json to get an overview without recursing into each entity.

Elided fields

Fields listed under elide_fields are dropped entirely from documents.jsonl output. The type stays documented in schema.json, so heavy fields (embeddings, large binary, raw text blobs) can be hidden from agent reads without losing the schema signal:

config = MongoDBConfig(
    uri=os.environ["MONGODB_URI"],
    elide_fields={
        "sample_mflix.movies": ["plot_embedding"],
        "rag.docs": ["metadata.embedding"],
    },
)

Nested paths use dot notation. Elision applies to both cat (one-shot streaming reads) and tail -f (live change-stream follows).

Streaming and Limits

cat, grep, head, and tail -f consume documents lazily through a batched PyMongo async cursor (or change stream); the consumer cancels to stop fetching. There is no truncation notice because nothing is forced into memory ahead of the consumer.

Command	Behavior
`cat`	Streams the whole collection sorted by `_id`; pipe to `head` to cap
`head -n K` / `tail -n K`	K is capped at `max_doc_limit`; server-side sort + limit
`tail -f`	Opens a change stream; yields each new insert as a JSONL line
`grep` (file level)	Streams from `documents.jsonl`; supports `-m` for short-circuit
`grep` (collection/db level)	Server-side query, capped at `default_search_limit`
`jq`	Inherits the streaming `cat` source
`wc`	Uses `countDocuments()` server-side; zero download
`stat`	Metadata only (doc count, indexes; views skip the index lookup)

Smart Commands

grep at different scopes

grep uses MongoDB’s query engine at directory scopes instead of streaming all documents through the regex pipeline:

# FILE level - streams documents.jsonl, runs the regex locally
grep "Godfather" "/mongodb/sample_mflix/collections/movies/documents.jsonl"

# COLLECTION level - server-side query against the collection
grep "Godfather" "/mongodb/sample_mflix/collections/movies/"

# DATABASE level - searches across every collection in sample_mflix
grep "Godfather" "/mongodb/sample_mflix/"

# ROOT level - fans out across every mounted database
grep "Godfather" "/mongodb/"

At collection or higher scope the resource picks the best server-side strategy from the indexes available:

Text index exists → uses $text (ranked by relevance)
Atlas Search index exists → uses $search (fuzzy, Lucene-based)
Neither → falls back to $regex on sampled string fields

Scope detection is handled by mirage/core/mongodb/scope.py.

head / tail / tail -f

head and tail use server-side sort + limit; the requested count is capped at max_doc_limit. tail -f opens a Mongo change stream filtered to insert events and yields each new document as a JSONL line in the same format as cat:

# First 10 docs (sorted by _id ascending)
head -n 10 "/mongodb/sample_mflix/collections/movies/documents.jsonl"

# Last 10 docs (sorted by _id descending)
tail -n 10 "/mongodb/sample_mflix/collections/movies/documents.jsonl"

# Live-follow new inserts; consumer cancels to stop
tail -f "/mongodb/sample_mflix/collections/movies/documents.jsonl"

tail -f requires the cluster to be a replica set; Atlas already satisfies this. Views fall through to the non-streaming path because change streams aren’t defined on views.

Cache

The MongoDB resource uses IndexCacheStore (same as RAM/S3/disk/GitHub) for listings: database names, collection names, and document counts. Document content is not cached. The resource leaves caches_reads at its default of False, so cat, grep, head, and tail always query the live collection instead of serving a stored snapshot. This keeps reads consistent with a mutable database and ensures tail -f follows the live change stream rather than replaying cached bytes.

Example

import asyncio
import os

from dotenv import load_dotenv

from mirage import MountMode, Workspace
from mirage.resource.mongodb import MongoDBConfig, MongoDBResource

load_dotenv(".env.development")

config = MongoDBConfig(uri=os.environ["MONGODB_URI"])
resource = MongoDBResource(config=config)


async def main():
    ws = Workspace({"/mongodb": resource}, mode=MountMode.READ)

    # List all databases
    r = await ws.execute("ls /mongodb/")
    print(await r.stdout_str())

    # List the entities under a database (database.json, collections/, views/)
    r = await ws.execute("ls /mongodb/sample_mflix/")
    print(await r.stdout_str())

    # List collections
    r = await ws.execute("ls /mongodb/sample_mflix/collections/")
    print(await r.stdout_str())

    # Read first 5 movies
    r = await ws.execute(
        'head -n 5 "/mongodb/sample_mflix/collections/movies/documents.jsonl"')
    print(await r.stdout_str())

    # Read last 5 movies
    r = await ws.execute(
        'tail -n 5 "/mongodb/sample_mflix/collections/movies/documents.jsonl"')
    print(await r.stdout_str())

    # Inspect the sampled schema and indexes
    r = await ws.execute(
        'cat "/mongodb/sample_mflix/collections/movies/schema.json"')
    print(await r.stdout_str())

    # Extract titles with jq
    r = await ws.execute(
        'jq -r ".[] | .title" "/mongodb/sample_mflix/collections/movies/documents.jsonl"'
    )
    print(await r.stdout_str())

    # Search across a database (uses MongoDB query engine)
    r = await ws.execute('grep "Godfather" "/mongodb/sample_mflix/"')
    print(await r.stdout_str())

    # Count documents (server-side, no download)
    r = await ws.execute(
        'wc -l "/mongodb/sample_mflix/collections/movies/documents.jsonl"')
    print(await r.stdout_str())

    # View the database overview without recursing
    r = await ws.execute('cat "/mongodb/sample_mflix/database.json"')
    print(await r.stdout_str())


if __name__ == "__main__":
    asyncio.run(main())

Runnable examples

Three working examples live under examples/python/mongodb/:

mongodb.py — agent-shell workflow: ls, tree, cat, head, tail, wc, stat, grep/rg at every scope, jq, find, cd + relative paths.
mongodb_vfs.py — in-process VFS: os.listdir and open() walk every readdir level (root, database, collections/, views/, entity) and read database.json, schema.json, documents.jsonl (collection + view).
mongodb_fuse.py — same coverage as the VFS example, but the tree is mounted as a real filesystem so other processes can cat/ls/head the mountpoint directly.

All three default to the mirage_test database seeded by python/scripts/seed_mongodb_test.py.

Finding IDs

_id is serialized as {"$oid": "..."} under Extended JSON:

# List the first 10 ObjectId values
jq -r '.[] | ._id["$oid"]' \
  "/mongodb/sample_mflix/collections/movies/documents.jsonl" | head -n 10

# Find a specific document by ID
grep "573a1390f29313caabcd42e8" \
  "/mongodb/sample_mflix/collections/movies/documents.jsonl"

# Extract a few fields together
jq -r '.[] | "\(._id["$oid"]) \(.title) \(.year)"' \
  "/mongodb/sample_mflix/collections/movies/documents.jsonl"

Working with Large Collections

Streaming is the default; reach for these patterns when you want to keep the round trip small:

# Document count (server-side, no download)
wc -l "/mongodb/sample_mflix/collections/comments/documents.jsonl"

# Most recent documents (sorted by _id desc)
tail -n 10 "/mongodb/sample_mflix/collections/comments/documents.jsonl"

# Server-side query at collection scope avoids streaming the whole jsonl
grep "love" "/mongodb/sample_mflix/collections/comments/"

# Drop heavy fields via elide_fields, then take the slice you want
head -n 20 "/mongodb/sample_mflix/collections/movies/documents.jsonl"

Hide embeddings or large blobs from agent reads with elide_fields; schema.json still documents the original type so the agent can decide when to ask for the raw bytes through a different path.

Shell Commands

Standard commands available on the mounted MongoDB tree:

Command	Notes
`ls`	List databases, collections, views, and per-entity files
`cat`	Stream `documents.jsonl` (or read `schema.json` / `database.json`)
`head` / `tail`	Smart: server-side sort + limit (capped at `max_doc_limit`)
`tail -f`	Live-follow new inserts via Mongo change stream
`grep` / `rg`	Smart: MongoDB query engine at collection/db scope, regex at file scope
`jq`	Query JSON; use `.[]` prefix when iterating JSONL files
`wc`	Smart: uses `countDocuments()` server-side
`stat`	Metadata (doc count, indexes; views skip the index lookup)
`find`	List databases/collections/views with `-name`, `-maxdepth`
`tree`	Directory tree view

Getting Started

Agents

Resources

CLIs

Watch

Runtimes

Config

Filesystem Layout

documents.jsonl

schema.json

database.json

Elided fields

Streaming and Limits

Smart Commands

grep at different scopes

head / tail / tail -f

Cache

Example

Runnable examples

Finding IDs

Working with Large Collections

Shell Commands

​Config

​Filesystem Layout

​documents.jsonl

​schema.json

​database.json

​Elided fields

​Streaming and Limits

​Smart Commands

​grep at different scopes

​head / tail / tail -f

​Cache

​Example

​Runnable examples

​Finding IDs

​Working with Large Collections

​Shell Commands

Config

Filesystem Layout

documents.jsonl

schema.json

database.json

Elided fields

Streaming and Limits

Smart Commands

grep at different scopes

head / tail / tail -f

Cache

Example

Runnable examples

Finding IDs

Working with Large Collections

Shell Commands