DOCSP-38759: projections builder (#28)

* DOCSP-38759: projections builder

* fix tags

Author: rustagir

source/builders.txt

@@ -7,15 +7,16 @@ Builders
 .. toctree::
 
    /builders/filters/
+   /builders/projections/
 
 The {+driver-short+} provides the following classes that make it easier to use
 the CRUD API:
 
 - :ref:`scala-builders-filters`: Support for building query filters
+- :ref:`scala-builders-projections`: Support for building projections
 
 .. TODO replace with links
 
-- Projections: Support for building projections
 - Sorts: Support for building sort criteria
 - Aggregation: Support for building aggregation pipelines
 - Updates: Support for building updates

source/builders/projections.txt

@@ -0,0 +1,155 @@
+.. _scala-builders-projections:
+
+===========
+Projections
+===========
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: code example, create fields, customize results
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+The ``Projections`` class provides static factory methods for the
+MongoDB projection operators. Each method returns an instance of the
+``Bson`` type, which can in turn be passed to any method that expects a
+projection.
+
+You can import the methods of the ``Filters``
+class statically, as shown in the following code:
+
+.. code-block:: scala
+   
+   import org.mongodb.scala.model.Projections._
+
+The examples in this guide assume this static import.
+
+Inclusion
+---------
+
+By default, all fields of each document are included in the results. To specify the
+inclusion of one or more fields, which implicitly excludes all other
+fields except ``_id``, use the ``include()`` method.
+
+The following example includes the ``quantity`` field and, implicitly, the
+``_id`` field:
+
+.. code-block:: scala
+   
+   include("quantity")
+
+The following example includes the ``quantity`` and ``totalAmount``
+fields and, implicitly, the ``_id`` field:
+
+.. code-block:: scala
+   
+   include("quantity", "totalAmount")
+
+Exclusion
+---------
+
+To specify the exclusion of one or more fields, which implicitly
+includes all other fields, use the ``exclude()`` method.
+
+The following example excludes the ``quantity`` field:
+
+exclude("quantity")
+This example excludes the quantity and totalAmount fields:
+
+.. code-block:: scala
+   
+   exclude("quantity", "totalAmount")
+
+Exclusion of _id Field
+----------------------
+
+To specify the exclusion of the ``_id`` field, use the ``excludeId()``
+method:
+
+.. code-block:: scala
+   
+   excludeId()
+
+This is equivalent to the following code:
+
+.. code-block:: scala
+   
+   exclude("_id")
+
+Array Element Match with a Specified Filter
+-------------------------------------------
+
+To specify a projection that includes only the first element of an array
+that matches a supplied query filter, use the
+``elemMatch()`` method that takes a field name and a filter.
+
+The following example projects the first element of the ``orders`` array field,
+where the ``quantity`` field is greater than ``3``:
+
+.. code-block:: scala
+   
+   elemMatch("orders", Filters.gt("quantity", 3))
+
+Array Element Match with an Implicit Filter
+-------------------------------------------
+
+To specify a projection that includes only the first element of an array
+that matches the filter supplied as part of the query, use the
+``elemMatch()`` method that takes just a field name.
+
+The following example projects the first element of the ``orders`` array
+that matches the query filter:
+
+.. code-block:: scala
+   
+   elemMatch("orders")
+
+Slice
+-----
+
+To project a slice of an array, use one of the ``slice()`` methods.
+
+The following example projects the first ``7`` elements of the ``tags`` array:
+
+.. code-block:: scala
+   
+   slice("tags", 7)
+
+The following example skips the first ``2`` elements of the ``tags``
+array and projects the next ``5``:
+
+.. code-block:: scala
+   
+   slice("tags", 2, 5)
+
+Text Score
+----------
+
+To specify a projection of the score of a ``$text`` query, use the
+``metaTextScore()`` method to specify the name of the projected field.
+
+The following example projects the text score as the value of the
+``score`` field:
+
+.. code-block:: scala
+   
+   metaTextScore("score")
+
+Combining Projections
+---------------------
+
+To combine multiple projections, use the fields method.
+
+The following example includes the ``quantity`` and ``totalAmount``
+fields and excludes the ``_id`` field:
+
+.. code-block:: scala
+   
+   fields(include("quantity", "totalAmount"), excludeId())