From ca9928d62c0b47a13568bdd4b6684c3f3c7caf33 Mon Sep 17 00:00:00 2001
From: Allison Moore <allison.moore@10gen.com>
Date: Fri, 12 Jan 2018 12:30:02 -0500
Subject: [PATCH] DOCS-11142: prefer $expr over $where

---
 source/reference/operator/query/where.txt | 76 ++++++++++++++---------
 1 file changed, 48 insertions(+), 28 deletions(-)

diff --git a/source/reference/operator/query/where.txt b/source/reference/operator/query/where.txt
index 9cf1ef554ce..dfd653cdd2f 100644
--- a/source/reference/operator/query/where.txt
+++ b/source/reference/operator/query/where.txt
@@ -7,9 +7,12 @@ $where
 .. contents:: On this page
    :local:
    :backlinks: none
-   :depth: 1
+   :depth: 2
    :class: singlecol
 
+Definition
+----------
+
 .. query:: $where
 
    Use the :query:`$where` operator to pass either a string
@@ -20,6 +23,14 @@ $where
    collection. Reference the document in the JavaScript expression or
    function using either ``this`` or ``obj`` .
 
+.. important::
+   .. versionchanged:: 3.6
+      The :query:`$expr` operator allows the
+      use of :ref:`aggregation expressions <aggregation-framework>`
+      within the query language. :query:`$expr` is faster than
+      :query:`$where` because it does not execute JavaScript and should
+      be preferred where possible.
+
 Behavior
 --------
 
@@ -66,34 +77,43 @@ following performance advantages:
 - The non\-:query:`$where` query statements may use an
   :term:`index`.
 
-Examples
-~~~~~~~~
-
-Consider the following examples:
-
-.. code-block:: javascript
-
-   db.myCollection.find( { $where: "this.credits == this.debits" } );
-   db.myCollection.find( { $where: "obj.credits == obj.debits" } );
-
-   db.myCollection.find( { $where: function() { return (this.credits == this.debits) } } );
-   db.myCollection.find( { $where: function() { return obj.credits == obj.debits; } } );
-
-Additionally, if the query consists only of the :query:`$where`
-operator, you can pass in just the JavaScript expression or
-JavaScript functions, as in the following examples:
-
-.. code-block:: javascript
-
-   db.myCollection.find( "this.credits == this.debits || this.credits > this.debits" );
-
-   db.myCollection.find( function() { return (this.credits == this.debits || this.credits > this.debits ) } );
+Example
+-------
 
-You can include both the standard MongoDB operators and the
-:query:`$where` operator in your query, as in the following
-examples:
+Consider the following documents in the ``users`` collection:
 
 .. code-block:: javascript
 
-   db.myCollection.find( { active: true, $where: "this.credits - this.debits < 0" } );
-   db.myCollection.find( { active: true, $where: function() { return obj.credits - obj.debits < 0; } } );
+   {  
+      _id: 12378,
+      name: "Steve", 
+      username: "steveisawesome",
+      first_login: "2017-01-01"
+   }
+   {
+      _id: 2,
+      name: "Anya",
+      username: "anya",
+      first_login: "2001-02-02"
+   }
+
+The following example uses :query:`$where` and the ``hex_md5()``
+JavaScript function to compare the value of the ``name`` field to an
+MD5 hash and returns any matching document.
+
+.. code-block:: sh
+
+   db.foo.find( { $where: function() { 
+      return (hex_md5(this.name) == "9b53e667f30cd329dca1ec9e6a83e994") 
+   } } );
+
+The operation returns the following result:
+
+.. code-block:: sh
+
+   {
+      "_id" : 2,
+      "name" : "Anya",
+      "username" : "anya",
+      "first_login" : "2001-02-02"
+   }