03 Query Docs

03 List Docs is the friendly "show me some rows" node. 03 Query Docs is the one you reach for when "some rows" isn't good enough - when you need a filter, a sort order, a projection, or the ability to fetch one specific document versus many. It's the most powerful read node in ComfyUI-ZMongo's document suite, and it's where the database actually starts earning its keep.

Think of the use cases: "give me the 20 most recently updated prompt documents for this project", "find the image document that was generated yesterday", "get just the metadata field, not the whole record". List Docs can't do those; Query Docs can, because it exposes the Mongo-style machinery under the hood.

How it works

The node passes your JSON inputs through to session.query_docs():

• query_json - the filter, MongoDB-style. {} is "match everything", {"project_name": "default"} narrows to a project. You can use operators like {"created_at": {"$gte": "2026-08-01"}}.
• many - boolean, default true. true returns a list of matching docs; false treats it as a single-document fetch (and you'd typically also set a document_id).
• projection_json - which fields to include/exclude. {} means full documents. {"metadata": 1} returns only the metadata key. This is your bandwidth control for big records.
• sort_json - a JSON array of [field, direction] pairs, e.g. [["updated_at", -1]] for newest first. Default [] means natural order.
• document_id, limit, skip, cache - the same story as the rest of the pack. limit caps at 500.

Outputs: json (full response), ids (list of matching document IDs), indexed ("0: id" preview text). Like List Docs, failures show up as an error payload in json plus empty lists rather than a crash.

The inputs and outputs that matter

For a beginner, session, collection_name, and query_json are the trio that matters; the rest have sane defaults. many: true + limit is the standard "recent N docs" recipe, and projection_json is the trick that keeps queries fast when documents carry embedded images. The ids output feeds straight into 99 Select Nth Item or 03 Get Doc.

Install

Same as every ZMongo node:

cd ComfyUI/custom_nodes
git clone https://github.com/CentralFloridaAttorney/ComfyUI-ZMongo
cd ComfyUI-ZMongo
pip install -r requirements.txt

or ComfyUI Manager → "ComfyUI-ZMongo" → restart. No model downloads.

Troubleshooting

• Error in json immediately - almost always malformed query_json, projection_json, or sort_json. Remember: query_json and projection_json must be JSON objects ({}), while sort_json must be a JSON array ([]). Mixing those up is the #1 footgun.
• Query returns nothing when you know data exists - field names in the filter must match the keys actually stored. ZMongo docs often nest project-scoped data, so check with 04 Metadata Flattened Paths to see the real key paths before filtering on them.
• many: false with a blank document_id - you asked for one document but didn't say which. Either set the ID or flip many back to true.
• Slow queries - add a projection to drop image/binary fields you don't need, and raise limit instead of looping.

Query Docs is the node that turns ZMongo from "a weird place to save JSON" into an actual searchable parameter library.