From e766493aec1d74fc2f38751baf3cd260d374151f Mon Sep 17 00:00:00 2001 From: Jason Price Date: Tue, 9 Mar 2021 10:41:55 -0800 Subject: [PATCH] DOCS-14252 create match expressions for aggregation --- source/includes/expr-operators-and-indexes.rst | 13 +++++++++++++ .../includes/fact-let-variable-access-note.rst | 13 +++++-------- .../reference/operator/aggregation/lookup.txt | 12 ++++++------ source/reference/operator/query/expr.txt | 18 +++++++----------- source/release-notes/5.0.txt | 7 +++++++ 5 files changed, 38 insertions(+), 25 deletions(-) create mode 100644 source/includes/expr-operators-and-indexes.rst diff --git a/source/includes/expr-operators-and-indexes.rst b/source/includes/expr-operators-and-indexes.rst new file mode 100644 index 00000000000..2138792bd88 --- /dev/null +++ b/source/includes/expr-operators-and-indexes.rst @@ -0,0 +1,13 @@ +Starting in MongoDB 5.0, the :expression:`$eq`, :expression:`$lt`, +:expression:`$lte`, :expression:`$gt`, and :expression:`$gte` comparison +operators placed in an :query:`$expr` operator can use an index on the +``from`` collection referenced in a :pipeline:`$lookup` stage. +Limitations: + +- :ref:`Multikey indexes ` are not used. + +- Indexes are not used for comparisons where the operand is an array or + the operand type is undefined. + +- Indexes are not used for comparisons with more than one :ref:`field + path ` operand. \ No newline at end of file diff --git a/source/includes/fact-let-variable-access-note.rst b/source/includes/fact-let-variable-access-note.rst index 3692213ed1d..83eabc44fb1 100644 --- a/source/includes/fact-let-variable-access-note.rst +++ b/source/includes/fact-let-variable-access-note.rst @@ -1,21 +1,18 @@ .. note:: To reference variables in :ref:`pipeline ` - stages, use the ``"$$"`` syntax. + stages, use the ``"$$"`` syntax. The :ref:`let ` variables can be accessed by the stages in the :ref:`pipeline `, including additional :pipeline:`$lookup` stages nested in the ``pipeline``. - A :pipeline:`$match` stage requires the use of an - :query:`$expr` operator to access the variables. - :query:`$expr` allows the use of aggregation expressions - inside of the :pipeline:`$match` syntax. + :query:`$expr` operator to access the variables. The :query:`$expr` + operator allows the use of aggregation expressions inside of the + :pipeline:`$match` syntax. - The :query:`$expr` operator only uses indexes on the joined - ``from`` collection for equality matches. Non-equality match - queries, such as range queries, cannot use indexes on the joined - ``from`` collection. + .. include:: /includes/expr-operators-and-indexes.rst - Other (non-:pipeline:`$match`) stages in the :ref:`pipeline ` do not diff --git a/source/reference/operator/aggregation/lookup.txt b/source/reference/operator/aggregation/lookup.txt index 98ae0526a8b..c9a9348307f 100644 --- a/source/reference/operator/aggregation/lookup.txt +++ b/source/reference/operator/aggregation/lookup.txt @@ -15,7 +15,7 @@ Definition .. pipeline:: $lookup - .. versionadded:: 3.2 + .. versionchanged:: 5.0 Performs a left outer join to an unsharded collection in the *same* database to filter in documents from the "joined" collection for @@ -772,16 +772,16 @@ The operation corresponds to this pseudo-SQL statement: AND instock >= orders.ordered ); -The :query:`$expr` operator only uses indexes on the ``from`` -collection for equality matches. For example, if the index -``{ stock_item: 1, instock: 1 }`` exists on the ``warehouses`` -collection: +.. include:: /includes/expr-operators-and-indexes.rst + +For example, if the index ``{ stock_item: 1, instock: 1 }`` exists on +the ``warehouses`` collection: - The equality match on the ``warehouses.stock_item`` field uses the index. - The range part of the query on the ``warehouses.instock`` field - does not use the indexed field in the compound index. + also uses the indexed field in the compound index. .. seealso:: diff --git a/source/reference/operator/query/expr.txt b/source/reference/operator/query/expr.txt index 8598f26fd1e..569a8382a4a 100644 --- a/source/reference/operator/query/expr.txt +++ b/source/reference/operator/query/expr.txt @@ -13,7 +13,7 @@ $expr Definition ---------- -.. versionadded:: 3.6 +.. versionchanged:: 5.0 .. query:: $expr @@ -33,18 +33,14 @@ Definition Behavior -------- -- :query:`$expr` can build query expressions that compare fields - from the same document in a :pipeline:`$match` stage. +:query:`$expr` can build query expressions that compare fields from the +same document in a :pipeline:`$match` stage. - - If the :pipeline:`$match` stage is part of a :pipeline:`$lookup` - stage, :query:`$expr` can compare fields using ``let`` variables. - See :ref:`lookup-multiple-joins` for an example. +If the :pipeline:`$match` stage is part of a :pipeline:`$lookup` stage, +:query:`$expr` can compare fields using ``let`` variables. See +:ref:`lookup-multiple-joins` for an example. - - :query:`$expr` only uses indexes on the ``from`` collection for - equality matches in a :pipeline:`$match` stage. - -- :query:`$expr` does not support - :ref:`multikey indexes `. +.. include:: /includes/expr-operators-and-indexes.rst Examples -------- diff --git a/source/release-notes/5.0.txt b/source/release-notes/5.0.txt index 4a19a007b0a..45ba2a9dba8 100644 --- a/source/release-notes/5.0.txt +++ b/source/release-notes/5.0.txt @@ -47,6 +47,13 @@ Starting in MongoDB 5.0, you can specify multiple input expressions for the :expression:`$ifNull` expression before returning a replacement expression. +Comparison Operators and Indexes with ``$expr`` Operator +```````````````````````````````````````````````````````` + +Starting in MongoDB 5.0, the :expression:`$eq`, :expression:`$lt`, +:expression:`$lte`, :expression:`$gt`, and :expression:`$gte` operators +placed in an :query:`$expr` operator can use an index. + Aggregate ``let`` Option ````````````````````````