=======
$exists
=======
.. default-domain:: mongodb
Definition
----------
.. query:: $exists
*Syntax*: ``{ field: { $exists: <boolean> } }``
When ``<boolean>`` is true, :query:`$exists` matches the documents that
contain the field, including documents where the field value is
``null``. If ``<boolean>`` is false, the query returns only the
documents that do not contain the field.
MongoDB `$exists` does **not** correspond to SQL operator
``exists``. For SQL ``exists``, refer to the :query:`$in`
operator.
.. seealso:: :query:`$nin`, :query:`$in`, and
:ref:`faq-developers-query-for-nulls`.
Examples
--------
Exists and Not Equal To
~~~~~~~~~~~~~~~~~~~~~~~
Consider the following example:
.. 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 ``5`` or
``15``.
Null Values
~~~~~~~~~~~
Given a collection named ``records`` with the following documents:
.. code-block:: javascript
{ a: 5, b: 5, c: null }
{ a: 3, b: null, c: 8 }
{ a: null, b: 3, c: 9 }
{ a: 1, b: 2, c: 3 }
{ a: 2, c: 5 }
{ a: 3, b: 2 }
{ a: 4 }
{ b: 2, c: 4 }
{ b: 2 }
{ c: 6 }
Consider the output of the following queries:
**Query**:
.. code-block:: javascript
db.records.find( { a: { $exists: true } } )
**Result**:
.. code-block:: javascript
{ a: 5, b: 5, c: null }
{ a: 3, b: null, c: 8 }
{ a: null, b: 3, c: 9 }
{ a: 1, b: 2, c: 3 }
{ a: 2, c: 5 }
{ a: 3, b: 2 }
{ a: 4 }
**Query**:
.. code-block:: javascript
db.records.find( { b: { $exists: false } } )
**Result**:
.. code-block:: javascript
{ a: 2, c: 5 }
{ a: 4 }
{ c: 6 }
**Query**:
.. code-block:: javascript
db.records.find( { c: { $exists: false } } )
**Result**:
.. code-block:: javascript
{ a: 3, b: 2 }
{ a: 4 }
{ b: 2 }
