Document $inverseMatch, and close out the missing-stages list - #66
Merged
guanzhousongmicrosoft merged 1 commit intoAug 3, 2026
Merged
Conversation
Of the five aggregation stages still missing from the reference, $inverseMatch is the only one a reader can actually use, and it is the one they are least able to look up elsewhere: it has no MongoDB equivalent, so there is no upstream page to fall back on. The stage inverts the direction of a match. Where $match holds one query and tests it against many documents, $inverseMatch reads a query out of each document and tests it against a supplied input, which is what a collection of stored queries needs - saved searches, alert rules, subscription filters. Written from ParseInverseMatchSpec and the operator implementation rather than from any equivalent elsewhere: the required path, the mutually exclusive input and from, pipeline being required with from and restricted to $match, $project and $limit, and defaultResult governing documents that carry no query at all. Two behaviours are worth the space they take - a missing path is not an error but a silent drop unless defaultResult says otherwise, and input is parsed as an aggregation expression, so a string is a path reference rather than a literal. The other four remain undocumented on purpose; see the pull request for why none of them can currently be run.
guanzhousongmicrosoft
approved these changes
Aug 3, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Addresses the remainder of documentdb/documentdb.github.io#130. Nine of the fourteen stages it listed were documented in #59 and #64; this covers the five that were left, though not in the way the issue expects — only one of them can currently be run.
The one that ships:
$inverseMatchImplemented, ungated, and specific to DocumentDB — there is no MongoDB equivalent, so a reader who meets it in a pipeline has nowhere else to look. That makes it the highest-value page of the original fourteen.
The stage inverts the direction of a match:
$matchholds one query and tests it against many documents, while$inverseMatchreads a query out of each document and tests it against a supplied input. It is the stage for collections of stored queries — saved searches, alert rules, subscription filters.Documented from
ParseInverseMatchSpecand the operator implementation: requiredpath, mutually exclusiveinput/from,pipelinerequired alongsidefromand restricted to$match,$projectand$limit, anddefaultResultgoverning documents that carry no query. Two behaviours got explicit space because both are quietly surprising — a missingpathis not an error but a silent drop unlessdefaultResultsays otherwise, andinputis parsed as an aggregation expression, so a bare string is a path reference rather than a literal document.The four that do not: no pages, deliberately
$listLocalSessions.mutateFunc = NULL$listSessions.mutateFunc = NULL$searchMeta.mutateFunc = NULL$listSearchIndexesA stage registered with a null handler is rejected by the pipeline builder itself (
bson_aggregation_pipeline.c:9019):$listSearchIndexesfails twice over.documentdb.enableExtendedIndexesdefaults tofalse(feature_flag_configs.c:214), so it errors$listSearchIndexes stage is not enabledout of the box; and even with the flag on,rewrite_list_extended_indexes_query_hookisNULLin this build (api_hooks.c:47), so the handler'sRewriteListExtendedIndexesQueryreturnsNULLand it errors$listSearchIndexes is not supported. It is an extension point for a downstream distribution, not a stage this engine can run.Writing reference pages for these four would repeat the mistake #64 had to correct on
$search: documenting MongoDB's behaviour for something DocumentDB does not implement, in a form that looks authoritative and fails on first use.A note on the count
Issue #130 derived "40 public stages" from
StageDefinitions[], and its own analysis warned that the table "gives a name and a.mutateFuncpointer, and says nothing about what the stage accepts". That caveat applies to the count as well: at least four entries in the table cannot be executed. The gap was smaller than it looked.Verification
Every claim here comes from the engine source at
v0.114-0, not from MongoDB's documentation. The three outbound links on the new page were checked against the live site and return 200.