From 79d75e4055bdfb0e4d095caeb92343b20c4abcdb Mon Sep 17 00:00:00 2001 From: kay Date: Thu, 29 Nov 2012 16:05:45 -0500 Subject: [PATCH 1/2] DOCS-827 query for nulls --- source/faq/developers.txt | 62 ++++++++++++++++++++++++++++ source/reference/operator/exists.txt | 24 ++++++++--- 2 files changed, 81 insertions(+), 5 deletions(-) diff --git a/source/faq/developers.txt b/source/faq/developers.txt index 7e4b806050e..9999b2caa87 100644 --- a/source/faq/developers.txt +++ b/source/faq/developers.txt @@ -427,6 +427,68 @@ 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 + +- 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: diff --git a/source/reference/operator/exists.txt b/source/reference/operator/exists.txt index 574bd707514..8519f041724 100644 --- a/source/reference/operator/exists.txt +++ b/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() `, :operator:`$and`, - :operator:`$nin`, :operator:`$in`. + + - :method:`find() ` + + - :operator:`$nin` + + - :operator:`$and` + + - :operator:`$in` + + - :ref:`faq-developers-query-for-nulls` From a18453667dd8f504441915adcec1b978d255edfe Mon Sep 17 00:00:00 2001 From: kay Date: Thu, 29 Nov 2012 16:50:48 -0500 Subject: [PATCH 2/2] DOCS-827 migrate query and nulls wiki --- source/faq/developers.txt | 8 ++++++-- source/reference/operator/exists.txt | 15 ++++++--------- 2 files changed, 12 insertions(+), 11 deletions(-) diff --git a/source/faq/developers.txt b/source/faq/developers.txt index 9999b2caa87..7843b66201b 100644 --- a/source/faq/developers.txt +++ b/source/faq/developers.txt @@ -455,6 +455,9 @@ Different query operators treat ``null`` values differently: .. 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`` @@ -471,13 +474,14 @@ Different query operators treat ``null`` values differently: { "_id" : 1, "cancelDate" : null } - The ``{ cancelDate : { $exists: false } }`` query matches documents - that that do not contain the ``cancelDate`` field: + 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: + The query returns only the document that does *not* contain the + ``cancelDate`` field: .. code-block:: javascript diff --git a/source/reference/operator/exists.txt b/source/reference/operator/exists.txt index 8519f041724..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. @@ -23,13 +27,6 @@ $exists 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() `