query-for-null-fields.txt

.. include:: /includes/java-sync-links.rst
.. include:: /includes/java-async-links.rst

.. _faq-developers-query-for-nulls:

================================
Query for Null or Missing Fields
================================

.. default-domain:: mongodb

Different query operators in MongoDB treat ``null`` values differently.

.. |query_operations| replace:: operations that query for ``null`` values

.. tabs-top::

.. include:: /includes/driver-example-query-intro.rst

.. tabs-drivers::

   tabs:
     - id: python
       content: |
         .. important::
            You must use ``None`` with the PyMongo Python driver to
            query for ``null`` or missing fields in MongoDB.

     - id: perl
       content: |
         .. important::
            You must use ``undef`` with the MongoDB Perl driver to
            query for ``null`` or missing fields in MongoDB.

     - id: ruby
       content: |
         .. important::
            You must use ``nil`` with the MongoDB Ruby driver to
            query for ``null`` or missing fields in MongoDB.

     - id: scala
       content: |
         .. important::
            You must use ``BsonNull()`` with the MongoDB Scala driver to query
            for ``null`` or missing fields in MongoDB.

     - id: csharp
       content: |
         .. important::
            You must use ``BsonNull.Value`` with the MongoDB C# driver to
            query for ``null`` or missing fields in MongoDB.

.. include:: /includes/driver-example-query-38.rst

.. _faq-comparison-with-null:

Equality Filter
---------------

.. tabs-drivers::

   tabs:
     - id: shell
       content: |
         The ``{ item : null }`` query matches documents that either
         contain the ``item`` field whose value is ``null`` *or* that
         do not contain the ``item`` field.

     - id: python
       content: |
         The ``{ item : None }`` query matches documents that either
         contain the ``item`` field whose value is ``null`` *or* that
         do not contain the ``item`` field.

     - id: java-sync
       content: |
         The ``eq("item", null)`` query matches documents that either
         contain the ``item`` field whose value is ``null`` *or* that
         do not contain the ``item`` field.

     - id: java-async
       content: |
         The ``eq("item", null)`` query matches documents that either
         contain the ``item`` field whose value is ``null`` *or* that
         do not contain the ``item`` field.

     - id: nodejs
       content: |
         The ``{ item : null }`` query matches documents that either
         contain the ``item`` field whose value is ``null`` *or* that
         do not contain the ``item`` field.

     - id: php
       content: |
         The ``[ item => undef ]`` query matches documents that either
         contain the ``item`` field whose value is ``null`` *or* that
         do not contain the ``item`` field.

     - id: perl
       content: |
         The ``{ item => undef }`` query matches documents that either
         contain the ``item`` field whose value is ``null`` *or* that
         do not contain the ``item`` field.

     - id: ruby
       content: |
         The ``{ item => nil }`` query matches documents that either
         contain the ``item`` field whose value is ``nil`` *or* that
         do not contain the ``item`` field.

     - id: scala
       content: |
         The ``equal("item", BsonNull)`` query matches documents that
         either contain the ``item`` field whose value is ``null`` *or*
         that do not contain the ``item`` field.

     - id: csharp
       content: |
         The ``Eq("item", BsonNull.Value)`` query using the :csharp-api:`FilterDefinitionBuilder.Eq()
         <Overload_MongoDB_Driver_FilterDefinitionBuilder_1_Eq>` method
         matches documents that either contain the ``item`` field whose
         value is ``null`` *or* that do not contain the ``item`` field.

For example, the following query returns both documents:

.. include:: /includes/driver-example-query-39.rst

Type Check
----------

.. tabs-drivers::

   tabs:
     - id: shell
       content: |
         The ``{ item : { $type: 10 } }`` query matches documents that
         contains the ``item`` field whose value is ``null`` *only*;
         i.e. the value of the ``item`` field is of BSON Type ``Null``
         (i.e. ``10``) :

     - id: python
       content: |
         The ``{ item : { $type: 10 } }`` query matches documents that
         contains the ``item`` field whose value is ``null`` *only*;
         i.e. the value of the ``item`` field is of BSON Type ``Null``
         (i.e. ``10``) :

     - id: java-sync
       content: |
         The ``type("item", BsonType.NULL)`` query matches documents
         that contains the ``item`` field whose value is ``null``
         *only*; i.e. the value of the ``item`` field is of BSON Type
         ``Null`` (i.e. ``10``) :

     - id: java-async
       content: |
         The ``type("item", BsonType.NULL)`` query matches documents
         that contains the ``item`` field whose value is ``null``
         *only*; i.e. the value of the ``item`` field is of BSON Type
         ``Null`` (i.e. ``10``) :

     - id: nodejs
       content: |
         The ``{ item : { $type: 10 } }`` query matches documents that
         contains the ``item`` field whose value is ``null`` *only*;
         i.e. the value of the ``item`` field is of BSON Type ``Null``
         (i.e. ``10``) :

     - id: php
       content: |
         The ``[ item => [ $type => 10 ] ]`` query matches documents that
         contains the ``item`` field whose value is ``null`` *only*;
         i.e. the value of the ``item`` field is of BSON Type ``Null``
         (i.e. ``10``) :

     - id: perl
       content: |
         The ``{ item => { $type => 10 } }`` query matches documents that
         contains the ``item`` field whose value is ``null`` *only*;
         i.e. the value of the ``item`` field is of BSON Type ``Null``
         (i.e. ``10``) :

     - id: ruby
       content: |
         The ``{ item => { $type => 10 } }`` query matches documents that
         contains the ``item`` field whose value is ``nil`` *only*;
         i.e. the value of the ``item`` field is of BSON Type ``Null``
         (i.e. ``10``) :

     - id: java-sync
       content: |
         The ``type("item", BsonType.NULL)`` query matches documents
         that contains the ``item`` field whose value is ``null``
         *only*; i.e. the value of the ``item`` field is of BSON Type
         ``Null`` (i.e. ``10``) :

     - id: csharp
       content: |
         The ``Type("item", BsonType.Null)`` query using the :csharp-api:`FilterDefinitionBuilder.Type()
         <Overload_MongoDB_Driver_FilterDefinitionBuilder_1_Type>` method
         matches documents that contain the ``item`` field whose value is
         ``null`` *only*; i.e. the value of the ``item`` field is of BSON
         Type ``Null`` (i.e. ``10``) :

.. include:: /includes/driver-example-query-40.rst

The query returns only the document where the ``item`` field has a
``null`` value.

Existence Check
---------------

.. tabs-drivers::

   tabs:
     - id: shell
       content: |
         The ``{ item : { $exists: false } }`` query matches documents
         that do not contain the ``item`` field:

     - id: python
       content: |
         The ``{ item : { $exists: False } }`` query matches documents
         that do not contain the ``item`` field:

     - id: java-sync
       content: |
         The ``exists("item", false)`` query matches documents that
         do not contain the ``item`` field:

     - id: java-async
       content: |
         The   ``exists("item", false)`` query matches documents that do
         not contain the ``item`` field:

     - id: nodejs
       content: |
         The ``{ item : { $exists: false } }`` query matches documents
         that do not contain the ``item`` field:

     - id: php
       content: |
         The ``[ item => [ $exists => false ] ]`` query matches documents
         that do not contain the ``item`` field:

     - id: perl
       content: |
         The ``{ item => { $exists => false } }`` query matches documents
         that do not contain the ``item`` field:

     - id: ruby
       content: |
         The ``{ item => { $exists => false } }`` query matches documents
         that do not contain the ``item`` field:

     - id: scala
       content: |
         The ``exists("item", exists = false)`` query matches documents
         that do not contain the ``item`` field:

     - id: csharp
       content: |
         The ``Exists("item", false)`` query using the :csharp-api:`FilterDefinitionBuilder.Exists()
         <Overload_MongoDB_Driver_FilterDefinitionBuilder_1_Exists>`
         method matches documents that do not contain the ``item`` field:

.. include:: /includes/driver-example-query-41.rst

The query returns only the document that does *not* contain the
``item`` field:

.. seealso:: The reference documentation for the :query:`$type` and
   :query:`$exists` operators.