diff --git a/config/redirects b/config/redirects index b593fff5..0f70d847 100644 --- a/config/redirects +++ b/config/redirects @@ -93,4 +93,5 @@ raw: ${prefix}/master -> ${base}/upcoming/ [*-master]: ${prefix}/${version}/fundamentals/authentication/ldap/ -> ${base}/${version}/security/authentication/ldap/ [*-master]: ${prefix}/${version}/fundamentals/authentication/oidc/ -> ${base}/${version}/security/authentication/oidc/ [*-master]: ${prefix}/${version}/fundamentals/authentication/scram/ -> ${base}/${version}/security/authentication/scram/ -[*-master]: ${prefix}/${version}/fundamentals/authentication/x509/ -> ${base}/${version}/security/authentication/x509/ \ No newline at end of file +[*-master]: ${prefix}/${version}/fundamentals/authentication/x509/ -> ${base}/${version}/security/authentication/x509/ +[*-master]: ${prefix}/${version}/crud/query/specify-query/ -> ${base}/${version}/crud/query/query-filter/ \ No newline at end of file diff --git a/source/crud/query.txt b/source/crud/query.txt index 93468c74..e5f07bf7 100644 --- a/source/crud/query.txt +++ b/source/crud/query.txt @@ -12,7 +12,7 @@ Read Operations :titlesonly: :maxdepth: 1 - Specify a Query + Specify a Query Find Documents Specify Documents to Return Specify Fields to Return diff --git a/source/crud/query/query-filter.txt b/source/crud/query/query-filter.txt new file mode 100644 index 00000000..d409d099 --- /dev/null +++ b/source/crud/query/query-filter.txt @@ -0,0 +1,633 @@ +.. _csharp-specify-query: +.. _csharp-create-query-filter: + +===================== +Create a Query Filter +===================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 1 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: search, read, update, delete + +Overview +-------- + +In this guide, you can learn how to use the {+driver-long+} to create a **query filter**. +A query filter is an expression that specifies the documents to read, update, or delete +in a CRUD operation. You can use builder methods, available from the +``Builders.Filter`` static property, to create query filters and add +operations to them. + +.. include:: /includes/method-overloads.rst + +Sample Data +~~~~~~~~~~~ + +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: + +To run the code examples on this page, you must obtain a reference to the ``guitars`` +collection, as shown in the following example: + +.. code-block:: csharp + + var client = new MongoClient("localhost://27017"); + var guitarCollection = client.GetDatabase("example").GetCollection("guitars"); + +.. 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 creating and serializing custom classes, see the following pages: + + - :ref:`csharp-poco` + - :ref:`csharp-class-mapping` + - :ref:`csharp-serialization` + - :ref:`csharp-polymorphism` + +Find All Documents +------------------ + +An empty query filter matches all documents in a collection. The following example shows +how to create an empty query filter: + +.. code-block:: csharp + + var filter = Builders.Filter.Empty; + +Comparison Operators +-------------------- + +Comparison operators compare the query value to the value in a specified field. Some of +these methods have alternative syntax that you can use in place of the method, as shown +in the following example: + +.. code-block:: csharp + + var filter = Builders.Filter.Eq(g => g.Make, "Fender"); + var results = guitarCollection.Find(filter).ToList(); + + // Alternative syntax + var results = guitarCollection.Find(g => g.Make == "Fender").ToList();; + +The following table lists the {+driver-short+} methods for comparison operations +and the equivalent {+mdb-server+} operators: + +.. list-table:: + :widths: 20 20 40 20 + :header-rows: 1 + + * - {+driver-short+} Method + - Alternative Syntax + - Description + - {+mdb-server+} Operator + + * - ``Eq()`` + - ``==`` + - Matches documents where the value of the specified field is equal to the query value. + - :manual:`$eq ` + + * - ``Gt()`` + - ``>`` + - Matches documents where the value of the specified field is greater than the query value. + - :manual:`$gt ` + + * - ``Gte()`` + - ``>=`` + - Matches documents where any element in the specified array field is greater than or + equal to the query value. + - :manual:`$gte ` + + * - ``In()`` + - N/A + - Matches documents where any element in the specified array field matches any value in + the query array. + - :manual:`$in ` + + * - ``Lt()`` + - ``<`` + - Matches documents where any element in the specified array field is less than the + query value. + - :manual:`$lt ` + + * - ``Lte()`` + - ``<=`` + - Matches documents where any element in the specified array field is less than or equal + to the query value. + - :manual:`$lte ` + + * - ``Ne()`` + - ``!=`` + - Matches documents where any element in the specified array field is not equal to + the query value. + - :manual:`$ne ` + + * - ``Nin()`` + - N/A + - Matches documents where one of the following is true: + + - None of the elements in the specified array field matches any of the values in the + query array. + - The specified field doesn't exist. + - :manual:`$nin ` + + * - ``StringIn()`` + - N/A + - Matches documents where the string value of the specified field matches any string + value in the query array. + - :manual:`$in ` + + * - ``StringNin()`` + - N/A + - Matches documents where the string value of the specified field doesn't match any + of the string values in the query array. + - :manual:`$in ` + +The following example calls the ``Find()`` method and passes a lambda filter, which +the driver translates to a query filter. 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: false + + { "_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: false + + { "_id" : 4, "make" : "Kiesel", "models" : ["Ares", "Vader", "Solo"], "establishedYear" : 2015, "rating" : null } + +The following example calls the ``Find()`` method and passes a lambda expression, which +the driver translates to a query filter. 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: false + + { "_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: false + + { "_id" : 1, "make" : "Fender", "models" : ["Stratocaster", "Telecaster"], "establishedYear" : 1946, "rating" : 9 } + +Logical Operators +----------------- + +Logical operators combine two or more expressions and return results based on the results +of those expressions. These methods have alternative syntax that you can use in place of +the method, as shown in the following example: + +.. code-block:: csharp + + var builder = Builders.Filter; + var filter = builder.And( + builder.Gte(g => g.EstablishedYear, 1985), + builder.Ne(r => r.Make, "Kiesel")); + + var results = guitarCollection.Find(filter).ToList(); + + // Alternative syntax + var results = guitarCollection.Find( + g => g.EstablishedYear >= 1985 + && g.Make != "Kiesel") + .ToList(); + +The following table lists the {+driver-short+} methods for logical operations +and the equivalent {+mdb-server+} operators: + +.. list-table:: + :widths: 20 20 40 20 + :header-rows: 1 + + * - {+driver-short+} Method + - Alternative Syntax + - Description + - {+mdb-server+} Operator + + * - ``And()`` + - ``&&`` + - Matches documents where all expressions evaluate to true. + - :manual:`$and ` + + * - ``Or()`` + - ``||`` + - Matches documents where one or more expressions evaluates to true. + - :manual:`$or ` + +The following example calls the ``Find()`` method and passes a lambda expression, +which the driver translates to a query filter. 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: false + + { "_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: false + + { "_id" : 3, "make" : "PRS", "models" : ["Silver Sky", "SE", "Custom"], "establishedYear" : 1985, "rating" : 9 } + +Array Operators +--------------- + +Array operators match documents based on the value or quantity of elements in an array +field. The following table lists the {+driver-short+} methods for array operations +and the equivalent {+mdb-server+} operators: + +.. list-table:: + :widths: 20 60 20 + :header-rows: 1 + + * - {+driver-short+} Method + - Description + - {+mdb-server+} Operator + + * - ``All()`` + - Matches documents where the values in the specified array field match all query + values. + - :manual:`$all ` + + * - ``AnyEq()`` + - Matches documents where any element in the specified array field matches the + query value. + - :manual:`$elemMatch ` + + * - ``AnyGt()`` + - Matches documents where any element in the specified array field is greater than the + query value. + - :manual:`$elemMatch ` + + * - ``AnyGte()`` + - Matches documents where any element in the specified array field is greater than or + equal to the query value. + - :manual:`$elemMatch ` + + * - ``AnyIn()`` + - Matches documents where any element in the specified array field matches any value in + the query array. + - :manual:`$elemMatch ` + + * - ``AnyLt()`` + - Matches documents where any element in the specified array field is less than the + query value. + - :manual:`$elemMatch ` + + * - ``AnyLte()`` + - Matches documents where any element in the specified array field is less than or + equal to the query value. + - :manual:`$elemMatch ` + + * - ``AnyNe()`` + - Matches documents where any element in the specified array field is not equal to + the query value. + - :manual:`$elemMatch ` + + * - ``AnyNin()`` + - Matches documents where one of the following is true: + + - Any element in the specified array field isn't in the query array. + - The specified field doesn't exist. + - :manual:`$elemMatch ` + + * - ``AnyStringIn()`` + - Matches documents where any string element in the specified array field matches any + string value in the query array. + - :manual:`$elemMatch ` + + * - ``AnyStringNin()`` + - Matches documents where one of the following is true: + + - Any string element in the specified array field isn't in the query array. + - The specified field doesn't exist. + - :manual:`$elemMatch ` + + * - ``ElemMatch()`` + - Matches documents where any element in the specified array field matches the + query criteria. + - :manual:`$elemMatch ` + + * - ``Size()`` + - Matches documents where the specified array field is the specified size. + - :manual:`$size ` + + * - ``SizeGt()`` + - Matches documents where the specified array field is larger than the specified size. + - :manual:`$size ` + + * - ``SizeGte()`` + - Matches documents where the specified array field is larger than or equal to the + specified size. + - :manual:`$size ` + + * - ``SizeLt()`` + - Matches documents where the specified array field is smaller than the specified size. + - :manual:`$size ` + + * - ``SizeLte()`` + - Matches documents where the specified array field is smaller than or equal to the + specified size. + - :manual:`$size ` + +The following example uses builders to create a query filter that matches all +documents that have exactly three elements in the ``models`` field: + +.. io-code-block:: + :copyable: + + .. input:: /includes/fundamentals/code-examples/specify-query/FindSizeBuilder.cs + :language: csharp + + .. output:: + :language: json + :visible: false + + { "_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 } + +Element Operators +----------------- + +Element operators match document query data based on the presence or type of a field. +The following table lists the {+driver-short+} methods for element operations +and the equivalent {+mdb-server+} operators: + +.. list-table:: + :widths: 20 60 20 + :header-rows: 1 + + * - {+driver-short+} Method + - Description + - {+mdb-server+} Operator + + * - ``Exists()`` + - Matches documents that contain or don't contain a specified field, including + documents where the field value is ``null``. + - :manual:`$exists ` + + * - ``Type()`` + - Matches documents where the value of the specified field is an instance of the + specified BSON types. + - :manual:`$type ` + +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: false + + { "_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 } + +Evaluation Operators +-------------------- + +Evaluation operators analyze data in individual fields or all documents in the collection. +The following table lists the {+driver-short+} methods for +evaluation operations and the equivalent {+mdb-server+} operators: + +.. list-table:: + :widths: 20 60 20 + :header-rows: 1 + + * - {+driver-short+} Method + - Description + - {+mdb-server+} Operator + + * - ``JsonSchema()`` + - Matches documents that satisfy the specified JSON schema. + - :manual:`$jsonSchema ` + + * - ``Mod()`` + - Matches documents where the value of the specified field divided by a divisor has the + specified remainder (modulo). + - :manual:`$mod ` + + * - ``RegEx()`` + - Matches documents where the value of the specified field matches a specified regular + expression. + - :manual:`$regex ` + + * - ``Where()`` + - Use to pass either a string containing a JavaScript expression or a full JavaScript + function to the query system. + - :manual:`$where ` + +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: false + + { "_id" : 2, "make" : "Gibson", "models" : ["Les Paul", "SG", "Explorer"], "establishedYear" : 1902, "rating" : 8 } + +Geospatial Operators +-------------------- + +Geospatial operators return data based on geospatial expression conditions. +The following table lists the {+driver-short+} methods for +geospatial operations and the equivalent {+mdb-server+} operators: + +.. list-table:: + :widths: 20 60 20 + :header-rows: 1 + + * - {+driver-short+} Method + - Description + - {+mdb-server+} Operator + + * - ``GeoIntersects()`` + - Matches documents whose geospatial data intersects with a specified + `GeoJsonObject <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.GeoJsonObjectModel.GeoJsonObject-1.html>`__. + - :manual:`$geoIntersects ` + + * - ``GeoWithin()`` + - Matches documents whose geospatial data is entirely within the specified shape. + - :manual:`$geoWithin ` + + * - ``GeoWithinBox()`` + - Matches documents whose geospatial data is entirely within the specified box. + - :manual:`$geoWithin `, :manual:`$box ` + + * - ``GeoWithinCenter()`` + - Matches documents whose geospatial data is entirely within the specified circle. + - :manual:`$geoWithin `, :manual:`$center ` + + * - ``GeoWithinCenterSphere()`` + - Matches documents whose geospatial data is entirely within the specified sphere. + - :manual:`$geoWithin `, :manual:`$centerSphere ` + + * - ``GeoWithinPolygon()`` + - Matches documents whose geospatial data is entirely within the specified polygon. + - :manual:`$geoWithin `, :manual:`$polygon ` + + * - ``Near()`` + - Specifies a point for which a geospatial query returns the documents from nearest to + farthest. + - :manual:`$near ` + + * - ``NearSphere()`` + - Specifies a point for which a geospatial query returns the documents from nearest to + farthest in spherical geometry. + - :manual:`$nearSphere ` + +Bitwise Operators +----------------- + +Bitwise operators matches documents based on bit-position conditions. +The following table lists the {+driver-short+} methods for +bitwise operations and the equivalent {+mdb-server+} operators: + +.. list-table:: + :widths: 20 60 20 + :header-rows: 1 + + * - {+driver-short+} Method + - Description + - {+mdb-server+} Operator + + * - ``BitsAllClear()`` + - Matches documents where all of the specified bit positions are clear (``0``) in + the specified field. + - :manual:`$bitsAllClear ` + + * - ``BitsAllSet()`` + - Matches documents where all of the specified bit positions are set (``1``) in + the specified field. + - :manual:`$bitsAllSet ` + + * - ``BitsAnyClear()`` + - Matches documents where any of the specified bit positions are clear (``0``) in + the specified field. + - :manual:`$bitsAnyClear ` + + * - ``BitsAnySet()`` + - Matches documents where any of the specified bit positions are set (``1``) in + the specified field. + - :manual:`$bitsAnySet ` + +Other Operators +--------------- + +The {+driver-short+} also provides the following methods that create filter definitions: + +.. list-table:: + :widths: 40 60 + :header-rows: 1 + + * - {+driver-short+} Method + - Description + + * - ``OfType()`` + - Matches documents of a type derived from the specified type. You can use overloads + of this method to specify additional query criteria. + + * - ``Text()`` + - Matches documents with a field that contains the specified string. + +Additional Information +---------------------- + +For more information about any of the driver methods on this page, see the +API documentation for the +`FilterDefinitionBuilder <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.FilterDefinitionBuilder-1.html>`__ +class. \ No newline at end of file diff --git a/source/crud/query/specify-query.txt b/source/crud/query/specify-query.txt deleted file mode 100644 index bf508679..00000000 --- a/source/crud/query/specify-query.txt +++ /dev/null @@ -1,436 +0,0 @@ -.. _csharp-specify-query: - -=============== -Specify a Query -=============== - -.. 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 _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.Filter.Empty).ToList(); - -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 ` 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 } - -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 ` 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 } - -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 `. - -For more information on the array operators, see the :manual:`Array -Query Operators ` 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 } - -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 ` 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 } - -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 ` 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 } - -Additional Information ----------------------- - -For more information about the operators mentioned in this guide, see the -following Server Manual Entries: - -- :manual:`Comparison Query Operators ` -- :manual:`Logical Query Operators ` -- :manual:`Array Query Operators ` -- :manual:`Element Query Operators ` -- :manual:`Evaluation Query Operators ` - -To learn how to specify queries using LINQ, see :ref:`csharp-linq`. - -.. TODO: integrate into existing page - -Sample Class ------------- - -The code examples in this guide demonstrate how you can use builders to -create types to interact with documents in the sample collection ``plants.flowers``. -Documents in this collection are modeled by the following ``Flower`` class: - -.. literalinclude:: /includes/fundamentals/code-examples/builders.cs - :language: csharp - :dedent: - :start-after: start-model - :end-before: end-model - -Each builder class takes a generic type parameter -``TDocument`` which represents the type of document that you are working -with. In this guide, the ``Flower`` class is the document type used in -each builder class example. - -Construct a Filter ------------------- - -The ``FilterDefinitionBuilder`` class provides a type-safe interface for -building up queries. Suppose you want to query your collection for -documents matching the following criteria: - -- ``Price`` field value less than 20 -- ``Category`` field value is "Perennial" - -Use builders to create the filter definition with the typed variant: - -.. code-block:: csharp - :copyable: true - - var builder = Builders.Filter; - var filter = builder.Lt(f => f.Price, 20) & builder.Eq(f => f.Category, "Perennial"); - -Using the typed variant form provides compile-time safety. Additionally, -your IDE can provide refactoring support. - -Alternatively, you can use string-based field names to contruct the filter: - -.. code-block:: csharp - :copyable: true - - var builder = Builders.Filter; - var filter = builder.Lt("Price", 20) & builder.Eq("Category", "Perennial"); - -If you are using LINQ, you can also use the ``Inject()`` method to apply the filter -to a LINQ query: - -.. code-block:: csharp - :copyable: true - - var builder = Builders.Filter; - var filter = builder.Lt("Price", 20) & builder.Eq("Category", "Perennial"); - var query = collection.AsQueryable().Where(f => filter.Inject()); - -Array Operators -~~~~~~~~~~~~~~~ - -If your document has properties or fields that serialize to arrays, -you can use the methods beginning with ``Any``, such as ``AnyEq()`` or -``AnyLt()``, to compare the entire array against a single item. - -Use builders to check which documents in the collection have a -``Season`` array that includes "winter": - -.. code-block:: csharp - :copyable: true - - var builder = Builders.Filter; - var filter = builder.AnyEq(f => f.Season, "winter"); - -You can also call the ``ElemMatch()`` method to find documents that have an -array field that contains at least one element that matches a specified search -criteria. The following example returns documents that contain the value -``"Summer"`` in their ``Season`` array: - -.. code-block:: csharp - :copyable: true - - var builder = Builders.Filter; - var filter = builder.ElemMatch(f => f.Season, s => s == "Summer"); - -To learn more about array operators, see the :manual:`Array Query Operators -` guide in the {+mdb-server+} manual. - -- `FilterDefinitionBuilder <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.FilterDefinitionBuilder-1.html>`__ \ No newline at end of file diff --git a/source/includes/fundamentals/code-examples/specify-query/FindAndBuilder.cs b/source/includes/fundamentals/code-examples/specify-query/FindAndBuilder.cs index 01bb7a9d..55c26c5c 100644 --- a/source/includes/fundamentals/code-examples/specify-query/FindAndBuilder.cs +++ b/source/includes/fundamentals/code-examples/specify-query/FindAndBuilder.cs @@ -4,7 +4,7 @@ var filter = builder.And(builder.Gte(g => g.EstablishedYear, 1985), builder.Ne(r => r.Make, "Kiesel")); // Finds all documents that match the filter -var result = _guitarsCollection.Find(filter).ToList(); +var result = guitarCollection.Find(filter).ToList(); foreach (var doc in result) { diff --git a/source/includes/fundamentals/code-examples/specify-query/FindAndPOCO.cs b/source/includes/fundamentals/code-examples/specify-query/FindAndPOCO.cs index 946a1a7e..17e2937d 100644 --- a/source/includes/fundamentals/code-examples/specify-query/FindAndPOCO.cs +++ b/source/includes/fundamentals/code-examples/specify-query/FindAndPOCO.cs @@ -1,6 +1,6 @@ // Finds all documents with an "establishedYear" value greater than 1985 // and a "make" value that is not equal to "Kiesel" -var results = _guitarsCollection.Find(g => g.EstablishedYear >= 1985 && r.Make != "Kiesel").ToList(); +var results = guitarCollection.Find(g => g.EstablishedYear >= 1985 && r.Make != "Kiesel").ToList(); foreach (var doc in results) { diff --git a/source/includes/fundamentals/code-examples/specify-query/FindEqBuilder.cs b/source/includes/fundamentals/code-examples/specify-query/FindEqBuilder.cs index 4b346502..7d23f57a 100644 --- a/source/includes/fundamentals/code-examples/specify-query/FindEqBuilder.cs +++ b/source/includes/fundamentals/code-examples/specify-query/FindEqBuilder.cs @@ -2,7 +2,7 @@ var filter = Builders.Filter.Eq(g => g.Make, "Fender"); // Finds all documents that match the filter -var result = _guitarsCollection.Find(filter).ToList(); +var result = guitarCollection.Find(filter).ToList(); foreach (var doc in result) { diff --git a/source/includes/fundamentals/code-examples/specify-query/FindEqPOCO.cs b/source/includes/fundamentals/code-examples/specify-query/FindEqPOCO.cs index ea031b67..a4c92c17 100644 --- a/source/includes/fundamentals/code-examples/specify-query/FindEqPOCO.cs +++ b/source/includes/fundamentals/code-examples/specify-query/FindEqPOCO.cs @@ -1,5 +1,5 @@ // Finds all documents with a "make" value of "Fender" -var results = _guitarsCollection.Find(g => g.Make == "Fender").ToList(); +var results = guitarCollection.Find(g => g.Make == "Fender").ToList(); foreach (var doc in results) { diff --git a/source/includes/fundamentals/code-examples/specify-query/FindExistsBuilder.cs b/source/includes/fundamentals/code-examples/specify-query/FindExistsBuilder.cs index 2860354f..438e33bb 100644 --- a/source/includes/fundamentals/code-examples/specify-query/FindExistsBuilder.cs +++ b/source/includes/fundamentals/code-examples/specify-query/FindExistsBuilder.cs @@ -2,7 +2,7 @@ var filter = Builders.Filter.Exists(g => g.Rating); // Finds all documents that match the filter -var result = _guitarsCollection.Find(filter).ToList(); +var result = guitarCollection.Find(filter).ToList(); foreach (var doc in result) { diff --git a/source/includes/fundamentals/code-examples/specify-query/FindGtBuilder.cs b/source/includes/fundamentals/code-examples/specify-query/FindGtBuilder.cs index 466b56fb..afee42b9 100644 --- a/source/includes/fundamentals/code-examples/specify-query/FindGtBuilder.cs +++ b/source/includes/fundamentals/code-examples/specify-query/FindGtBuilder.cs @@ -3,7 +3,7 @@ var filter = Builders.Filter.Gt(g => g.EstablishedYear, 1985); // Finds all documents that match the filter -var result = _guitarsCollection.Find(filter).ToList(); +var result = guitarCollection.Find(filter).ToList(); foreach (var doc in result) { diff --git a/source/includes/fundamentals/code-examples/specify-query/FindGtPOCO.cs b/source/includes/fundamentals/code-examples/specify-query/FindGtPOCO.cs index d3308414..7f92dcb1 100644 --- a/source/includes/fundamentals/code-examples/specify-query/FindGtPOCO.cs +++ b/source/includes/fundamentals/code-examples/specify-query/FindGtPOCO.cs @@ -1,5 +1,5 @@ -// Finds all documents with am "establishedYear" value greater than 1985 -var results = _guitarsCollection.Find(g => g.EstablishedYear > 1985).ToList(); +// Finds all documents with an "establishedYear" value greater than 1985 +var results = guitarCollection.Find(g => g.EstablishedYear > 1985).ToList(); foreach (var doc in results) { diff --git a/source/includes/fundamentals/code-examples/specify-query/FindRegexBuilder.cs b/source/includes/fundamentals/code-examples/specify-query/FindRegexBuilder.cs index efcc8c59..29e36a79 100644 --- a/source/includes/fundamentals/code-examples/specify-query/FindRegexBuilder.cs +++ b/source/includes/fundamentals/code-examples/specify-query/FindRegexBuilder.cs @@ -2,7 +2,7 @@ var filter = Builders.Filter.Regex(g => g.Make, "^G"); // Finds all documents that match the filter -var result = _guitarsCollection.Find(filter).ToList(); +var result = guitarCollection.Find(filter).ToList(); foreach (var doc in result) { diff --git a/source/includes/fundamentals/code-examples/specify-query/FindSizeBuilder.cs b/source/includes/fundamentals/code-examples/specify-query/FindSizeBuilder.cs index 02764816..7a1272b7 100644 --- a/source/includes/fundamentals/code-examples/specify-query/FindSizeBuilder.cs +++ b/source/includes/fundamentals/code-examples/specify-query/FindSizeBuilder.cs @@ -2,7 +2,7 @@ var filter = Builders.Filter.Size(g => g.Models, 3); // Finds all documents that match the filter -var result = _guitarsCollection.Find(filter).ToList(); +var result = guitarCollection.Find(filter).ToList(); foreach (var doc in result) { diff --git a/source/reference/compatibility.txt b/source/reference/compatibility.txt index ce124f4b..cee8ba3b 100644 --- a/source/reference/compatibility.txt +++ b/source/reference/compatibility.txt @@ -41,5 +41,5 @@ The first column lists the driver version. .. include:: /includes/language-compatibility-table-csharp.rst -For more information on how to read the compatibility tables, see our guide on -:ref:`MongoDB Compatibility Tables. ` +For more information about how to read the compatibility tables, see +`MongoDB Compatibility Tables `__.