diff --git a/source/faq/developers.txt b/source/faq/developers.txt index 7e4b806050e..7843b66201b 100644 --- a/source/faq/developers.txt +++ b/source/faq/developers.txt @@ -427,6 +427,72 @@ for additional information. - The :source:`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: diff --git a/source/reference/operator/exists.txt b/source/reference/operator/exists.txt index 574bd707514..c8cb775bec3 100644 --- a/source/reference/operator/exists.txt +++ b/source/reference/operator/exists.txt @@ -6,9 +6,13 @@ $exists .. operator:: $exists - *Syntax*: ``{ field: { $exists: boolean } }`` + *Syntax*: ``{ field: { $exists: } }`` - :operator:`$exists` selects the documents that contain the field. + :operator:`$exists` selects the documents that contain the field if + ```` is ``true``. If ```` 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() `, :operator:`$and`, - :operator:`$nin`, :operator:`$in`. + + - :method:`find() ` + + - :operator:`$nin` + + - :operator:`$and` + + - :operator:`$in` + + - :ref:`faq-developers-query-for-nulls`