Null 1

source/faq/developers.txt

@@ -427,6 +427,72 @@ 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
+
+     { "_id" : 1, "cancelDate" : null }
+     { "_id" : 2 }
+
+- 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 do not contain the ``cancelDate`` field:
+
+  .. code-block:: javascript
+
+     db.test.find( { cancelDate : { $exists: false } } )
+
+  The query returns only the document that does *not* contain the
+  ``cancelDate`` field:
+
+  .. code-block:: javascript
+
+     { "_id" : 2 }
+
+.. seealso::
+
+   - :operator:`$type`
+
+   - :operator:`$exists`
+
 .. _faq-developers:
 
 .. _faq-restrictions-on-collection-names:

source/reference/operator/exists.txt

@@ -6,9 +6,13 @@ $exists
 
 .. operator:: $exists
 
-   *Syntax*: ``{ field: { $exists: boolean } }`` 
+   *Syntax*: ``{ field: { $exists: <boolean> } }``
 
-   :operator:`$exists` selects the documents that contain the field.
+   :operator:`$exists` selects the documents that contain the field if
+   ``<boolean>`` is ``true``. If ``<boolean>`` is ``false``, the query
+   only returns the documents that do not contain the field. Documents
+   that contain the field but has the value ``null`` are *not* returned.
+
    MongoDB `$exists` does **not** correspond to SQL operator
    ``exists``. For SQL ``exists``, refer to the :operator:`$in`
    operator.
@@ -18,12 +22,19 @@ $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``.
- 
+
    .. 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`