DOCS-827 query for nulls

Author: kay-kim

source/faq/developers.txt

@@ -427,6 +427,68 @@ for additional information.
    - The :source:`jsobj.h <src/mongo/db/jsobj.h>` source file for the
      definition of ``MinKey`` and ``MaxKey``.
 
+.. _faq-developers-query-for-nulls:
+
+How do I query for nulls?
+-------------------------
+
+A document may contain a ``null`` value. 
+
+Consider a collection ``test`` that contains the following documents: 
+
+.. code-block:: javascript
+
+   { _id: 1, cancelDate: null }
+   { _id: 2 }
+
+Different query operators treat ``null`` values differently: 
+
+- The ``{ cancelDate : null }`` query matches documents that either
+  contains the ``cancelDate`` field whose value is ``null`` *or* that
+  do not contain the ``cancelDate`` field:
+
+  .. code-block:: javascript
+
+     db.test.find( { cancelDate: null } )
+
+  The query returns both documents:
+
+  .. code-block:: javascript
+
+- The ``{ cancelDate : { $type: 10 } }`` query matches documents that
+  contains the ``cancelDate`` field whose value is ``null`` *only*;
+  i.e. the value of the ``cancelDate`` field is of BSON Type ``Null``
+  (i.e. ``10``) :
+
+  .. code-block:: javascript
+
+     db.test.find( { cancelDate : { $type: 10 } } )
+
+  The query returns only the document that contains the ``null`` value:
+
+  .. code-block:: javascript
+
+     { "_id" : 1, "cancelDate" : null }
+
+- The ``{ cancelDate : { $exists: false } }`` query matches documents
+  that that do not contain the ``cancelDate`` field:
+
+  .. code-block:: javascript
+
+     db.test.find( { cancelDate : { $exists: false } } )
+
+  The query returns only the document that contains the ``null`` value:
+
+  .. code-block:: javascript
+
+     { "_id" : 2 }
+
+.. seealso::
+
+   - :operator:`$type`
+
+   - :operator:`$exists`
+
 .. _faq-developers:
 
 .. _faq-restrictions-on-collection-names:

source/reference/operator/exists.txt

@@ -18,12 +18,26 @@ $exists
    .. code-block:: javascript
 
       db.inventory.find( { qty: { $exists: true, $nin: [ 5, 15 ] } } )
- 
+
    This query will select all documents in the ``inventory`` collection
    where the ``qty`` field exists *and* its value does not equal either
    ``5`` nor ``15``.
- 
+
+   .. note::
+
+      If set to ``false``, the query only returns those documents that
+      do not contain the field and *not* documents that contain the
+      field but has the value ``null``.
+
+
    .. seealso:: 
-  
-      :method:`find() <db.collection.find()>`, :operator:`$and`,
-      :operator:`$nin`, :operator:`$in`.
+
+      - :method:`find() <db.collection.find()>`
+
+      - :operator:`$nin` 
+
+      - :operator:`$and`
+
+      - :operator:`$in`
+
+      - :ref:`faq-developers-query-for-nulls`