diff --git a/.github/workflows/vale-tdbx.yml b/.github/workflows/vale-tdbx.yml index 284033ab..8e4b6f49 100644 --- a/.github/workflows/vale-tdbx.yml +++ b/.github/workflows/vale-tdbx.yml @@ -12,6 +12,9 @@ jobs: - name: checkout uses: actions/checkout@master + - name: Install docutils + run: sudo apt-get install -y docutils + - id: files uses: masesgroup/retrieve-changed-files@v2 with: diff --git a/source/fundamentals/linq.txt b/source/fundamentals/linq.txt index bf8b4345..491c98e7 100644 --- a/source/fundamentals/linq.txt +++ b/source/fundamentals/linq.txt @@ -7,7 +7,7 @@ LINQ .. contents:: On this page :local: :backlinks: none - :depth: 2 + :depth: 3 :class: singlecol .. facet:: @@ -73,10 +73,11 @@ object that links to the collection. To create the object, use the ``AsQueryable as follows: .. code-block:: csharp - :emphasize-lines: 2 + :emphasize-lines: 3 - var restaurantsCollection = restaurantsDatabase.GetCollection("restaurants"); - var queryableCollection = restaurantsCollection.AsQueryable(); + var restaurantsDatabase = client.GetDatabase("sample_restaurants"); + var restaurantsCollection = restaurantsDatabase.GetCollection("restaurants"); + var queryableCollection = restaurantsCollection.AsQueryable(); Once you have the queryable object, you can compose a query using **method syntax**. Some pipeline stages also support **query comprehension syntax**, @@ -587,6 +588,181 @@ in the Atlas manual. For more examples about running Atlas Vector Search queries {+driver-short+}, see :atlas:`Run Vector Search Queries ` in the Atlas manual and select :guilabel:`C#` from the language dropdown. +Bitwise Operators +~~~~~~~~~~~~~~~~~ + +This section describes the :wikipedia:`bitwise operators ` +supported by the {+driver-short+} that you can use in an aggregation pipeline. +You can use multiple bitwise operators in the same +stage. The following guidelines apply when using bitwise operators: + +- All operands must be of type ``int`` or ``long``. + +- ``$bitAnd``, ``$bitOr``, and ``$bitXor`` take two or more operands. ``$bitNot`` takes one operand. + +- Bitwise operations are evaluated from left to right. + +The examples in this section use the following documents in a collection called +``ingredients``: + +.. code-block:: json + + { "_id" : 1, "name" : "watermelon", "is_available" : 1, "is_cheap" : 1 }, + { "_id" : 2, "name" : "onions", "is_available" : 1, "is_cheap" : 0 }, + { "_id" : 3, "name" : "eggs", "is_available" : 0, "is_cheap" : 0 }, + { "_id" : 4, "name" : "potatoes", "is_available" : 1, "is_cheap" : 1 }, + { "_id" : 5, "name" : "pasta", "is_available" : 0, "is_cheap" : 1 }, + { "_id" : 6, "name" : "cheese", "is_available" : 1 } + +The ``"is_available"`` field represents if an ingredient is available. If this +field has a value of ``0``, the ingredient is not available. If it has a value +of ``1``, the ingredient is available. + +The ``"is_cheap"`` field represents if an ingredient is cheap. If this field has +a value of ``0``, the ingredient is not cheap. If it has a value of ``1``, the +ingredient is cheap. + +The following ``Ingredient`` class models the documents in the ``ingredients`` +collection: + +.. literalinclude:: /includes/fundamentals/code-examples/linq.cs + :language: csharp + :dedent: + :start-after: start-ingredient-model + :end-before: end-ingredient-model + +.. note:: Missing or Undefined Operands + + If the operands you pass to any bitwise operator are of type `nullable `__ + ``int`` or ``long`` and contain a missing or undefined value, the entire expression + evaluates to ``null``. If the operands are of type non-nullable ``int`` or + ``long`` and contain a missing or undefined value, the {+driver-short+} will + throw an error. + +$bitAnd ++++++++ + +The ``$bitAnd`` aggregation operator performs a bitwise AND operation on the given +arguments. You can use the ``$bitAnd`` operator by connecting two or more +clauses with a ``&`` character. + +The following example shows how to create a ``$bitAnd`` stage by using LINQ. The +code retrieves the document in which the ``Name`` field has the +value ``"watermelon"``. It then performs a bitwise AND operation on the values of the +``IsAvailable`` and ``IsCheap`` fields in this document. + +.. literalinclude:: /includes/fundamentals/code-examples/linq.cs + :language: csharp + :dedent: + :start-after: start-bitAnd-example + :end-before: end-bitAnd-example + +The preceding code returns ``1``, the result of the AND operation on the values +of the ``IsAvailable`` field (``1``) and the ``IsCheap`` field (``1``). + +The following example performs the same bitwise AND operation on all +documents in the collection: + +.. io-code-block:: + :copyable: true + + .. input:: /includes/fundamentals/code-examples/linq.cs + :language: csharp + :dedent: + :start-after: start-bitAnd-collection-example + :end-before: end-bitAnd-collection-example + + .. output:: + :language: json + :visible: false + + 1 + 0 + 0 + 1 + 0 + null + +The ``null`` result comes from the document where the ``Name`` field +has the value of ``"cheese"``. This document is missing an ``IsCheap`` field, so +the expression evaluates to ``null``. + +$bitOr +++++++ + +The ``$bitOr`` aggregation operator performs a bitwise OR operation on the given +arguments. You can use the ``$bitOr`` operator by connecting two or more +clauses with a ``|`` character. + +The following example shows how to create a ``$bitOr`` stage by using LINQ. The +code retrieves the document in which the ``Name`` field has the +value ``"onions"``. It then performs a bitwise OR operation on the values of the +``IsAvailable`` and ``IsCheap`` fields in this document. + +.. literalinclude:: /includes/fundamentals/code-examples/linq.cs + :language: csharp + :dedent: + :start-after: start-bitOr-example + :end-before: end-bitOr-example + +The preceding code returns ``1``, the result of the OR operation on the values +of the ``IsAvailable`` field (``1``) and the ``IsCheap`` field (``0``). + +$bitNot ++++++++ + +The ``$bitNot`` aggregation operator performs a bitwise NOT operation on the given +argument. You can use the ``$bitNot`` operator by preceding an +operand with a ``~`` character. ``$bitNot`` only takes one argument. The +following example shows how to create a ``$bitNot`` stage by using LINQ: + +.. io-code-block:: + :copyable: true + + .. input:: /includes/fundamentals/code-examples/linq.cs + :language: csharp + :dedent: + :start-after: start-bitNot-example + :end-before: end-bitNot-example + + .. output:: + :language: json + :visible: false + + -2 + -1 + -1 + -2 + -2 + null + +$bitXor ++++++++ + +The ``$bitXor`` aggregation operator performs a bitwise XOR operation on the given +arguments. You can use the ``$bitXor`` operator by connecting two or more +clauses with a ``^`` character. + +The following example shows how to create a ``$bitXor`` stage by using LINQ. The +code retrieves the documents in which the ``Name`` field has +the value ``"watermelon"`` or ``"onions"``. It then performs a bitwise XOR +operation on the values of the ``IsAvailable`` and ``IsCheap`` fields in these +documents. + +.. literalinclude:: /includes/fundamentals/code-examples/linq.cs + :language: csharp + :dedent: + :start-after: start-bitXor-example + :end-before: end-bitXor-example + +The result contains the following values: + +.. code-block:: json + + 0 + 1 + + Unsupported Aggregation Stages ------------------------------ diff --git a/source/includes/convention-pack-note.rst b/source/includes/convention-pack-note.rst index cb322ef4..97338a26 100644 --- a/source/includes/convention-pack-note.rst +++ b/source/includes/convention-pack-note.rst @@ -1,6 +1,6 @@ .. note:: - The documents in the ``restaurants`` collection use the camel-case naming + The documents in the ``restaurants`` collection use the snake-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 ``Restaurant`` class. diff --git a/source/includes/fundamentals/code-examples/linq.cs b/source/includes/fundamentals/code-examples/linq.cs index aa4336e8..de5ab12e 100644 --- a/source/includes/fundamentals/code-examples/linq.cs +++ b/source/includes/fundamentals/code-examples/linq.cs @@ -26,7 +26,7 @@ public class Address public string Building { get; set; } [BsonElement("coord")] - public float[] Coordinates { get; set; } + public double[] Coordinates { get; set; } public string Street { get; set; } @@ -63,3 +63,58 @@ public class Review } // end-review-model + +// start-ingredient-model + +public class Ingredient +{ + public int Id { get; set; } + + public string Name { get; set; } + + [BsonElement("is_available")] + public int? IsAvailable { get; set; } + + [BsonElement("is_cheap")] + public int? IsCheap { get; set; } +} + +// end-ingredient-model + +// start-bitAnd-example + +var query = queryableCollection + .Where(i => i.Name == "watermelon") + .Select(i => i.IsAvailable & i.IsCheap); + +// end-bitAnd-example + +// start-bitAnd-collection-example + +var query = queryableCollection + .Select(i => i.IsAvailable & i.IsCheap); + +// end-bitAnd-collection-example + +// start-bitOr-example + +var query = queryableCollection + .Where(i => i.Name == "onions") + .Select(i => i.IsAvailable | i.IsCheap); + +// end-bitOr-example + +// start-bitNot-example + +var query = queryableCollection + .Select(i => ~i.IsCheap); + +// end-bitNot-example + +// start-bitXor-example + +var query = queryableCollection + .Where(i => i.Name == "watermelon" || i.Name == "onions") + .Select(i => i.IsAvailable ^ i.IsCheap); + +// end-bitXor-example \ No newline at end of file