QueryResultsProcessor in Java: Merge and Sort Results Across Databases into a View or JSON
You have three batches of documents from three different databases — this year’s orders, last year’s archived orders, a department’s orders on another server. You need them merged into one list, sorted by amount, a total computed, and finally a chunk of JSON for the front end, or a view people can click into.
The hand-rolled way is to getAllDocuments() all three into memory, merge them into one list, and write a comparator to sort. Across three databases, with any real volume, that doesn’t hold up — in memory or in time.
QueryResultsProcessor (since R12, QRP for short) moves this to the server. The docs state its value in one line: “Aggregates, computes, sorts, and formats collections of documents across any set of Domino databases.” This covers its many-in, one-out shape, the two output modes, and a create-method name that even the docs get wrong.
The many-in, one-out shape
QRP works in three moves: create a processor, feed in multiple sources, define the output columns, execute.
First, the create-method name: the class page’s Creation section says createQueryProcessor, but that’s a doc typo — the example code and the method that actually exists is db.createQueryResultsProcessor(), and it’s on Database, not session:
QueryResultsProcessor qrp = db.createQueryResultsProcessor();Then feed in the sources. addCollection is, in the docs, “Adds a pre-created DocumentCollection or ViewEntryCollection of documents” — any collection you built by any means (FTSearch, getAllDocuments, a view’s entries), each given a referencename unique within this processor:
qrp.addCollection(thisYearOrders, "cur");qrp.addCollection(archivedOrders, "arc"); // can come from another dbqrp.addDominoQuery(dq, "Status = 'Open'", "dql"); // or feed a DQL query directlyThat referencename isn’t just a label — it identifies which source each result row came from, and it’s how addFormula targets a formula at one source. Then addColumn defines which columns come back and how they sort and categorize (the docs: “Creates a single column of values to be returned when QueryResultsProcessor is executed.”).
Two outputs: executeToView and executeToJSON
With sources and columns defined, execution goes two ways:
executeToView— the docs: “Saves QueryResultsProcesser results to a “results view” in a database.” It materializes the merged, sorted results into a view people can click into and other code can read. Note it’s temporary: the results view expires in 24 hours by default (you can set a lifetime) — don’t treat it as a permanent view.executeToJSON— returns a JSON string (public String executeToJSON()). Good for feeding a front end or a REST response. Results sit under the top-level keyStreamedResults, and each row carries two special keys:@nid(NoteID) and@DbPath— with those, the front end can act back on a given row’s document (which might live in another db).
A few things that bite
- referencename must be unique: two sources under the same name in one processor, and later references won’t line up.
- the results view expires: executeToView’s output vanishes after 24h by default; set a lifetime if you need it around, or recompute each time.
- cap it: a cross-database merge over big databases can be heavy — use
setMaxEntries/setTimeoutSecso a runaway query doesn’t drag the server down. - QRP, the collections you feed it, and the DominoQuery are back-end handles —
recycle()them when done; the discipline is in the Java recycle blow-up piece.
What about LotusScript and SSJS?
The same QueryResultsProcessor:
- LotusScript:
NotesQueryResultsProcessor, withAddCollection/AddColumn/ExecuteToView/ExecuteToJSON— same behavior; the full usage is in the NotesQueryResultsProcessor piece. - SSJS / XPages: there is no direct QueryResultsProcessor — like DQL, XPages has to run QRP through a Java bean (the DQL-in-XPages approach is in DQL in production).
- The Java-specific part, beyond the API, is that this server-side cross-database merge is a natural fit to wrap as a reusable Java service — many collections in, JSON out to a front end — a useful piece when Domino is the data back end.
Sources
- QueryResultsProcessor class (Java) (cross-database merge/sort, addColumn/executeToView, Release 12) — HCL Domino 14.5 Designer Help (official)
- addCollection (QueryResultsProcessor - Java) (add a DocumentCollection/ViewEntryCollection + a unique referencename) — HCL Domino 14.5 Designer Help (official)
- executeToJSON (QueryResultsProcessor - Java) (JSON output, @nid / @DbPath special keys) — HCL Domino 14.5 Designer Help (official)