query.txt

.. _query-projection-operators-top:

==============================
Query and Projection Operators
==============================

.. default-domain:: mongodb

.. contents:: On this page
   :local:
   :backlinks: none
   :depth: 1
   :class: singlecol


.. include:: /includes/extracts/operators-toc-explanation.rst

.. _query-selectors:

Query Selectors
---------------

Comparison
~~~~~~~~~~

.. include:: /includes/fact-comparison-order.rst

.. list-table::
   :widths: 30,70
   :header-rows: 1

   * - Name

     - Description

   * - :query:`$eq`

     - Matches values that are equal to a specified value.

   * - :query:`$gt`

     - Matches values that are greater than a specified value.

   * - :query:`$gte`

     - Matches values that are greater than or equal to a specified value.

   * - :query:`$in`

     - Matches any of the values specified in an array.

   * - :query:`$lt`

     - Matches values that are less than a specified value.

   * - :query:`$lte`

     - Matches values that are less than or equal to a specified value.

   * - :query:`$ne`

     - Matches all values that are not equal to a specified value.

   * - :query:`$nin`

     - Matches none of the values specified in an array.


.. toctree::
   :titlesonly:
   :hidden:

   /reference/operator/query-comparison

Logical
~~~~~~~

.. list-table::
   :widths: 30,70
   :header-rows: 1

   * - Name

     - Description

   * - :query:`$and`

     - Joins query clauses with a logical ``AND`` returns all documents that match the conditions of both clauses.

   * - :query:`$not`

     - Inverts the effect of a query expression and returns documents that do *not* match the query expression.

   * - :query:`$nor`

     - Joins query clauses with a logical ``NOR`` returns all documents that fail to match both clauses.

   * - :query:`$or`

     - Joins query clauses with a logical ``OR`` returns all documents that match the conditions of either clause.


.. toctree::
   :titlesonly:
   :hidden:

   /reference/operator/query-logical

Element
~~~~~~~

.. list-table::
   :widths: 30,70
   :header-rows: 1

   * - Name

     - Description

   * - :query:`$exists`

     - Matches documents that have the specified field.

   * - :query:`$type`

     - Selects documents if a field is of the specified type.


.. toctree::
   :titlesonly:
   :hidden:

   /reference/operator/query-element

Evaluation
~~~~~~~~~~

.. list-table::
   :widths: 30,70
   :header-rows: 1

   * - Name

     - Description

   * - :query:`$expr`

     - Allows use of aggregation expressions within the query language.

   * - :query:`$jsonSchema`

     - Validate documents against the given JSON Schema.

   * - :query:`$mod`

     - Performs a modulo operation on the value of a field and selects documents with a specified result.

   * - :query:`$regex`

     - Selects documents where values match a specified regular expression.

   * - :query:`$text`

     - Performs text search.

   * - :query:`$where`

     - Matches documents that satisfy a JavaScript expression.


.. toctree::
   :titlesonly:
   :hidden:

   /reference/operator/query-evaluation

Geospatial
~~~~~~~~~~

.. list-table::
   :widths: 30,70
   :header-rows: 1

   * - Name

     - Description

   * - :query:`$geoIntersects`

     - Selects geometries that intersect with a :term:`GeoJSON` geometry.
       The :doc:`2dsphere </core/2dsphere>` index supports
       :query:`$geoIntersects`.
   

   * - :query:`$geoWithin`

     - Selects geometries within a bounding :ref:`GeoJSON geometry
       <geospatial-indexes-store-geojson>`. The :doc:`2dsphere
       </core/2dsphere>` and :doc:`2d </core/2d>` indexes support
       :query:`$geoWithin`.
   

   * - :query:`$near`

     - Returns geospatial objects in proximity to a point.
       Requires a geospatial index.  The :doc:`2dsphere
       </core/2dsphere>` and :doc:`2d </core/2d>` indexes support
       :query:`$near`.
   

   * - :query:`$nearSphere`

     - Returns geospatial objects in proximity to a point on a sphere.
       Requires a geospatial index.  The :doc:`2dsphere
       </core/2dsphere>` and :doc:`2d </core/2d>` indexes support
       :query:`$nearSphere`.
   


.. toctree::
   :titlesonly:
   :hidden:

   /reference/operator/query-geospatial

.. _operator-query-array:

Array
~~~~~

.. list-table::
   :widths: 30,70
   :header-rows: 1

   * - Name

     - Description

   * - :query:`$all`

     - Matches arrays that contain all elements specified in the query.

   * - :query:`$elemMatch`

     - Selects documents if element in the array field matches all the specified :query:`$elemMatch` conditions.

   * - :query:`$size`

     - Selects documents if the array field is a specified size.


.. toctree::
   :titlesonly:
   :hidden:

   /reference/operator/query-array

Bitwise
~~~~~~~

.. list-table::
   :widths: 30,70
   :header-rows: 1

   * - Name

     - Description

   * - :query:`$bitsAllClear`

     - Matches numeric or binary values in which a set of bit positions *all* have a value of ``0``.

   * - :query:`$bitsAllSet`

     - Matches numeric or binary values in which a set of bit positions *all* have a value of ``1``.

   * - :query:`$bitsAnyClear`

     - Matches numeric or binary values in which *any* bit from a set of bit positions has a value of ``0``.

   * - :query:`$bitsAnySet`

     - Matches numeric or binary values in which *any* bit from a set of bit positions has a value of ``1``.


.. toctree::
   :titlesonly:
   :hidden:

   /reference/operator/query-bitwise

.. _query-projection-operators:

Projection Operators
--------------------

.. list-table::
   :widths: 30,70
   :header-rows: 1

   * - Name

     - Description

   * - :projection:`$`

     - Projects the first element in an array that matches the query condition.

   * - :projection:`$elemMatch`

     - Projects the first element in an array that matches the specified :projection:`$elemMatch` condition.

   * - :expression:`$meta`

     - Projects the document's score assigned during :query:`$text` operation.

   * - :projection:`$slice`

     - Limits the number of elements projected from an array. Supports skip and limit slices.

.. toctree::
   :titlesonly:
   :hidden:

   /reference/operator/projection

.. _query-miscelaneous-operators:

Miscellaneous Operators
-----------------------

.. list-table::
   :widths: 25,75
   :header-rows: 1

   * - Name

     - Description

   * - :query:`$comment`

     - Adds a comment to a query predicate.

   * - :query:`$rand`

     - Generates a random float between 0 and 1.

.. toctree::
   :titlesonly:
   :hidden:

   /reference/operator/query-miscellaneous