specify-query.txt

.. _csharp-specify-query:

===============
Specify a Query
===============

.. meta::
   :description: Learn how to specify queries using the MongoDB .NET/C# Driver, including creating query filters and using comparison, logical, array, element, and evaluation operators.

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

Overview
--------

In this guide, you can learn how to specify a query using the {+driver-long+}.

You can narrow the set of matched documents returned by your query by creating a
**query filter**. A query filter is an expression that specifies the documents you 
want to match in a read, update, or delete operation.

.. note:: Using LINQ

   This guide shows how to specify queries using query filters. You can also
   specify queries using LINQ. To learn more about using LINQ, see
   :ref:`csharp-linq`.

The examples in this guide use the following documents in a collection called
``guitars``:

.. code-block:: json
 
   { "_id": 1, "make": "Fender", "models": ["Stratocaster", "Telecaster"], "establishedYear": 1946, "rating": 9 }
   { "_id": 2, "make": "Gibson", "models": ["Les Paul", "SG", "Explorer"], "establishedYear": 1902, "rating": 8 }
   { "_id": 3, "make": "PRS", "models": ["Silver Sky", "SE", "Custom"], "establishedYear": 1985, "rating": 9 }
   { "_id": 4, "make": "Kiesel", "models": ["Ares", "Vader", "Solo"], "establishedYear": 2015 }
   { "_id": 5, "make": "Ibanez", "models": ["RG", "AZ"], "establishedYear": 1957, "rating": 7 }
   { "_id": 6, "make": "Strandberg", "models": ["Boden", "Salen"], "establishedYear": 1982 }

The following ``Guitar`` class models the documents in this collection.

.. literalinclude:: /includes/fundamentals/code-examples/specify-query/Guitar.cs
   :language: csharp
   :copyable:
   :dedent:

.. note::

   The documents in the ``guitars`` collection use the camel-case naming
   convention. The examples in this guide use a ``ConventionPack``
   to deserialize the fields in the collection into Pascal case and map them to
   the properties in the ``Guitar`` class.

   To learn more about custom serialization, see :ref:`csharp-custom-serialization`.

To learn more about class mapping, see :ref:`csharp-class-mapping`.

The following code instantiates the ``_guitarsCollection`` object using the 
``Guitar`` class as a type parameter. This type parameter causes the driver to 
automatically serialize and deserialize the documents it sends to and receives
from MongoDB to instances of the ``Guitar`` class:

.. code-block:: csharp

   private static IMongoCollection<Guitar> _guitarsCollection;

Literal Values
--------------

Literal value queries return documents with an exact match to your query filter.

The following example specifies a query filter as a parameter to the ``Find()`` 
method. The query matches all documents where the
``make`` field equals "Fender".

.. io-code-block::
   :copyable:

   .. input:: /includes/fundamentals/code-examples/specify-query/FindEqPOCO.cs
      :language:  csharp

   .. output:: 
      :language: json
      :visible:

      { "_id" : 1, "make" : "Fender", "models" : ["Stratocaster", "Telecaster"], "establishedYear" : 1946, "rating" : 9 }

The following example uses builders to create a query filter that matches the
same documents as the preceding example:

.. io-code-block::
   :copyable:

   .. input:: /includes/fundamentals/code-examples/specify-query/FindEqBuilder.cs
      :language:  csharp

   .. output:: 
      :language: json
      :visible:

      { "_id" : 1, "make" : "Fender", "models" : ["Stratocaster", "Telecaster"], "establishedYear" : 1946, "rating" : 9 }

.. tip:: Find All Documents

   Use an empty query filter to match all documents in the collection. Create
   an empty query filter with builders as follows:

   .. code-block:: csharp

      var result = _guitarsCollection.Find(Builders<Guitar>.Filter.Empty).ToList();

To learn more about using builders, see :ref:`csharp-builders`.

Comparison Operators
--------------------

Comparison operators analyze the value in a document against the specified value
in your query filter. Common comparison operators include:

.. list-table::
   :widths: 30 30 40
   :header-rows: 1

   * - Operator
     - Builder
     - Description

   * - ``>``
     - ``Gt()``
     - Greater than

   * - ``<=``
     - ``Lte()``
     - Less than or equal to

   * - ``!=``
     - ``Ne()``
     - Not equal to

For a full list of comparison operators, see the :manual:`Comparison
Query Operators </reference/operator/query-comparison/>` page.

The following example specifies a query filter as a parameter to the ``Find()``
method. The query matches all documents where the ``establishedYear`` field is
greater than ``1985``.

.. io-code-block::
   :copyable:

   .. input:: /includes/fundamentals/code-examples/specify-query/FindGtPOCO.cs
      :language:  csharp

   .. output::
      :language: json
      :visible:

      { "_id" : 4, "make" : "Kiesel", "models" : ["Ares", "Vader", "Solo"], "establishedYear" : 2015, "rating" : null }

The following example uses builders to create a query filter that matches the
same documents as the preceding example:

.. io-code-block::
   :copyable:

   .. input:: /includes/fundamentals/code-examples/specify-query/FindGtBuilder.cs
      :language:  csharp

   .. output:: 
      :language: json
      :visible:

      { "_id" : 4, "make" : "Kiesel", "models" : ["Ares", "Vader", "Solo"], "establishedYear" : 2015, "rating" : null }


To learn more about using builders, see :ref:`csharp-builders`.

Logical Operators
-----------------

Logical operators match documents using logic applied to the results of two or more
sets of expressions. The following is a list of some logical operators:

.. list-table::
   :widths: 30 30 40
   :header-rows: 1

   * - Operator
     - Builder
     - Description

   * - ``&&``
     - ``And()``
     - All expressions must evaluate to true.

   * - ``||``
     - ``Or()``
     - At least one expression must evaluate to true.

For a full list of logical operators, see the :manual:`Logical
Query Operators </reference/operator/query-logical/>` page. 

The following example specifies a query filter as a parameter to the ``Find()`` 
method. The query matches all documents where the
``establishedYear`` field is greater than or equal to ``1985``, and the ``make``
field is not equal to "Kiesel".

.. io-code-block::
   :copyable:

   .. input:: /includes/fundamentals/code-examples/specify-query/FindAndPOCO.cs
      :language:  csharp

   .. output::
      :language: json
      :visible:

      { "_id" : 3, "make" : "PRS", "models" : ["Silver Sky", "SE", "Custom"], "establishedYear" : 1985, "rating" : 9 }


The following example uses builders to create a query filter that matches the
same documents as the preceding example:

.. io-code-block::
   :copyable:

   .. input:: /includes/fundamentals/code-examples/specify-query/FindAndBuilder.cs
      :language:  csharp

   .. output:: 
      :language: json
      :visible:

      { "_id" : 3, "make" : "PRS", "models" : ["Silver Sky", "SE", "Custom"], "establishedYear" : 1985, "rating" : 9 }

To learn more about using builders, see :ref:`csharp-builders`.

Array Operators
---------------

Array operators match documents based on the value or quantity of elements in an array
field. The following is a list of builder methods that use array operators:

.. list-table::
   :widths: 40 60
   :header-rows: 1

   * - Operator
     - Description

   * - ``All()``
     - Matches documents if the array field contains all elements specified in
       the query.

   * - ``Any()``
     - Matches documents if any element in the array field matches the specified
       query filter.

   * - ``Size()``
     - Matches documents if the array field is a specified size.

.. note:: 

   The ``Any()`` builder uses the ``$elemMatch`` query operator.

   To learn more about the ``$elemMatch`` query selector, see
   :manual:`$elemMatch </reference/operator/query/elemMatch/#mongodb-query-op.-elemMatch>`.

For more information on the array operators, see the :manual:`Array
Query Operators </reference/operator/query-array/>` page.

The following example uses builders to create a query filter that matches all
documents that have 3 elements in the ``models`` field:

.. io-code-block::
   :copyable:

   .. input:: /includes/fundamentals/code-examples/specify-query/FindSizeBuilder.cs
      :language:  csharp

   .. output::
      :language: json
      :visible:

      { "_id" : 2, "make" : "Gibson", "models" : ["Les Paul", "SG", "Explorer"], "establishedYear" : 1902, "rating" : 8 }
      { "_id" : 3, "make" : "PRS", "models" : ["Silver Sky", "SE", "Custom"], "establishedYear" : 1985, "rating" : 9 }
      { "_id" : 4, "make" : "Kiesel", "models" : ["Ares", "Vader", "Solo"], "establishedYear" : 2015, "rating" : null }

To learn more about using builders, see :ref:`csharp-builders`.

Element Operators
-----------------

Element operators query data based on the presence or type of a field.

For a full list of element operators, see the :manual:`Element
Query Operators </reference/operator/query-element/>` page.

The following example uses builders to create a query filter that matches all
documents that have a ``rating`` field:

.. io-code-block::
   :copyable:

   .. input:: /includes/fundamentals/code-examples/specify-query/FindExistsBuilder.cs
      :language:  csharp

   .. output::
      :language: json
      :visible:

      { "_id" : 1, "make" : "Fender", "models" : ["Stratocaster", "Telecaster"], "establishedYear" : 1946, "rating" : 9 }
      { "_id" : 2, "make" : "Gibson", "models" : ["Les Paul", "SG", "Explorer"], "establishedYear" : 1902, "rating" : 8 }
      { "_id" : 3, "make" : "PRS", "models" : ["Silver Sky", "SE", "Custom"], "establishedYear" : 1985, "rating" : 9 }
      { "_id" : 5, "make" : "Ibanez", "models" : ["RG", "AZ"], "establishedYear" : 1957, "rating" : 7 }

To learn more about using builders, see :ref:`csharp-builders`.

Evaluation Operators
--------------------

Evaluation operators analyze data on individual fields, or on the entire collection's
documents. Some builder methods that use evaluation operators include ``Regex()``
and ``Text()``.

For a full list of evaluation operators, see the :manual:`Evaluation
Query Operators </reference/operator/query-evaluation/>` page.

The following example uses builders to create a query filter that matches all
documents that have a value in the ``make`` field that starts with the letter 
"G":

.. io-code-block::
   :copyable:

   .. input:: ../../../includes/fundamentals/code-examples/specify-query/FindRegexBuilder.cs
      :language:  csharp

   .. output::
      :language: json
      :visible:

      { "_id" : 2, "make" : "Gibson", "models" : ["Les Paul", "SG", "Explorer"], "establishedYear" : 1902, "rating" : 8 }

To learn more about using builders, see :ref:`csharp-builders`.

Additional Information
----------------------

For more information about the operators mentioned in this guide, see the 
following Server Manual Entries:

- :manual:`Comparison Query Operators </reference/operator/query-comparison/>`
- :manual:`Logical Query Operators </reference/operator/query-logical/>`
- :manual:`Array Query Operators </reference/operator/query-array/>`
- :manual:`Element Query Operators </reference/operator/query-element/>`
- :manual:`Evaluation Query Operators </reference/operator/query-evaluation/>`

To learn more about using Builders, see :ref:`csharp-builders`.

To learn how to specify queries using LINQ, see :ref:`csharp-linq`.