Skip to content

Document $inverseMatch, and close out the missing-stages list - #66

Merged
guanzhousongmicrosoft merged 1 commit into
documentdb:mainfrom
GuanzhouSong:docs-inversematch-stage
Aug 3, 2026
Merged

Document $inverseMatch, and close out the missing-stages list#66
guanzhousongmicrosoft merged 1 commit into
documentdb:mainfrom
GuanzhouSong:docs-inversematch-stage

Conversation

@GuanzhouSong

Copy link
Copy Markdown
Contributor

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: $inverseMatch

Implemented, 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: $match holds one query and tests it against many documents, while $inverseMatch reads 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 ParseInverseMatchSpec and the operator implementation: required path, mutually exclusive input / from, pipeline required alongside from and restricted to $match, $project and $limit, and defaultResult governing documents that carry no query. Two behaviours got explicit space because both are quietly surprising — 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 bare string is a path reference rather than a literal document.

The four that do not: no pages, deliberately

Stage Why not
$listLocalSessions .mutateFunc = NULL
$listSessions .mutateFunc = NULL
$searchMeta .mutateFunc = NULL
$listSearchIndexes Feature-flagged off, and its rewrite hook is unset in this build

A stage registered with a null handler is rejected by the pipeline builder itself (bson_aggregation_pipeline.c:9019):

if (definition->mutateFunc == NULL)
    ereport(ERROR, (errcode(ERRCODE_DOCUMENTDB_COMMANDNOTSUPPORTED),
        errmsg("Stage %s is not supported yet in native pipeline", definition->stage)));

$listSearchIndexes fails twice over. documentdb.enableExtendedIndexes defaults to false (feature_flag_configs.c:214), so it errors $listSearchIndexes stage is not enabled out of the box; and even with the flag on, rewrite_list_extended_indexes_query_hook is NULL in this build (api_hooks.c:47), so the handler's RewriteListExtendedIndexesQuery returns NULL and 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 .mutateFunc pointer, 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.

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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants