From b03f34616320e78810b9c660c01d2ef273446b84 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Wed, 4 Jun 2025 15:03:51 -0500 Subject: [PATCH 01/11] first draft --- source/atlas-search.txt | 81 ++-- source/atlas-vector-search.txt | 27 +- source/crud/query/project.txt | 421 ++++++++++++------ .../code-examples/projection/MetaExamples.cs | 196 ++++++++ .../code-examples/projection/Movie.cs | 27 ++ .../code-examples/projection/SliceExamples.cs | 67 +++ source/includes/project/atlas-only-note.rst | 3 + 7 files changed, 611 insertions(+), 211 deletions(-) create mode 100644 source/includes/code-examples/projection/MetaExamples.cs create mode 100644 source/includes/code-examples/projection/Movie.cs create mode 100644 source/includes/code-examples/projection/SliceExamples.cs create mode 100644 source/includes/project/atlas-only-note.rst diff --git a/source/atlas-search.txt b/source/atlas-search.txt index 770674ef..499e2a39 100644 --- a/source/atlas-search.txt +++ b/source/atlas-search.txt @@ -38,7 +38,7 @@ The examples in this guide use the following documents in a collection called ``guitars``: .. code-block:: json - + { "_id": 1, "make": "Fender", "description": "Classic guitars known for their versatility.", "establishedYear": 1946, "in_stock": true, "rating": 9 } { "_id": 2, "make": "Gibson", "description": "Classic guitars known for their rich, full tones.", "establishedYear": 1902, "in_stock": true, "rating": 8 } { "_id": 3, "make": "PRS", "description": "High-end guitars known for their quality.", "establishedYear": 1985, "in_stock": true, "rating": 9 } @@ -75,7 +75,7 @@ Create an Atlas Search Index Before you can perform a search on an Atlas collection, you must first create an **Atlas Search index** on the collection. An Atlas Search index is a data structure that -categorizes data in a searchable format. +categorizes data in a searchable format. To learn how to create an Atlas Search Index see the :atlas:`Create an Atlas Search Index ` Atlas guide. @@ -103,7 +103,7 @@ collection using the string "Gib" in the ``make`` field. :dedent: .. note:: - + If the field you are searching on is indexed by a search index, you must pass the index name to the ``Autocomplete`` call. If a search index does not exist, the default index is used. The search returns the following document: @@ -112,7 +112,7 @@ The search returns the following document: { "_id" : 2, "make" : "Gibson", "description" : "Classic guitars known for their rich, full tones.", "establishedYear" : 1902, "in_stock" : true, "rating" : 8 } -To learn more about the ``autocomplete`` operator, see the :atlas:`autocomplete ` +To learn more about the ``autocomplete`` operator, see the :atlas:`autocomplete ` Atlas guide. Compound @@ -142,7 +142,7 @@ The search returns the following documents: { "_id" : 3, "make" : "PRS", "description" : "...", "establishedYear" : 1985, "in_stock" : true, "rating" : 9 } { "_id" : 5, "make" : "Ibanez", "description" : "...", "establishedYear" : 1957, "in_stock" : true, "rating" : 7 } -To learn more about the ``compound`` operator, see the :atlas:`compound ` +To learn more about the ``compound`` operator, see the :atlas:`compound ` Atlas guide. EmbeddedDocument @@ -153,7 +153,7 @@ within a field's array value. .. note:: - To search on embedded documents, you must create an + To search on embedded documents, you must create an ``embeddedDocument`` index on the array field. To learn how to define an ``embeddedDocument`` index, see @@ -218,7 +218,7 @@ The search returns the following documents: { "_id" : 5, "make" : "Ibanez", "description" : "...", "establishedYear" : 1957, "in_stock" : true, "rating" : 7 } -To learn more about the ``equals`` operator, see the :atlas:`equals ` +To learn more about the ``equals`` operator, see the :atlas:`equals ` Atlas guide. Exists @@ -246,8 +246,7 @@ The search returns the following documents: { "_id" : 3, "make" : "PRS", "description" : "...", "establishedYear" : 1985, "in_stock" : true, "rating" : 9 } { "_id" : 5, "make" : "Ibanez", "description" : "...", "establishedYear" : 1957, "in_stock" : true, "rating" : 7 } - -To learn more about the ``exists`` operator, see the :atlas:`exists ` +To learn more about the ``exists`` operator, see the :atlas:`exists ` Atlas guide. GeoShape @@ -266,7 +265,7 @@ Consider some documents in the ``guitars`` collection have added an follows: .. code-block:: json - + { "_id": 1, "make": "Fender", "description": "...", "establishedYear": 1946, "in_stock": true, "in_stock_location": { "type": "Point", "coordinates": [ -73.93615, 40.69791 ]}, "rating": 9 } { "_id": 2, "make": "Gibson", "description": "...", "establishedYear": 1902, "in_stock": true, "in_stock_location": { "type": "Point", "coordinates": [ 47.6062, 122.321 ]}, "rating": 8 } @@ -286,7 +285,7 @@ The search returns the following document: { "_id" : 1, "make" : "Fender", "description" : "...", "establishedYear" : 1946, "in_stock" : true, "in_stock_location" : { "type" : "Point", "coordinates" : ["-73.93615", "40.69791"] }, "rating" : 9 } -To learn more about the ``geoShape`` operator, see the :atlas:`geoShape ` +To learn more about the ``geoShape`` operator, see the :atlas:`geoShape ` Atlas guide. GeoWithin @@ -312,13 +311,13 @@ Consider some documents in the ``guitars`` collection have added an follows: .. code-block:: json - + { "_id": 1, "make": "Fender", "description": "...", "establishedYear": 1946, "in_stock": true, "in_stock_location": { "type": "Point", "coordinates": [ -73.93615, 40.69791 ]}, "rating": 9 } { "_id": 2, "make": "Gibson", "description": "...", "establishedYear": 1902, "in_stock": true, "in_stock_location": { "type": "Point", "coordinates": [ 47.6062, 122.321 ]}, "rating": 8 } The following example searches for all documents in which the coordinates in the ``in_stock_location`` field falls within a specified -polygon: +polygon: .. literalinclude:: /includes/fundamentals/code-examples/atlas-search/AtlasSearchExamples.cs :start-after: // start-geowithin-search @@ -332,7 +331,7 @@ The search returns the following document: { "_id" : 1, "make" : "Fender", "description" : "Classic guitars known for their versatility.", "establishedYear" : 1946, "in_stock" : true, "in_stock_location" : { "type" : "Point", "coordinates" : ["-73.93615", "40.69791"] }, "rating" : 9 } -To learn more about the ``geoWithin`` operator, see the :atlas:`geoWithin ` +To learn more about the ``geoWithin`` operator, see the :atlas:`geoWithin ` Atlas guide. In @@ -381,7 +380,7 @@ The search returns the following documents: { "_id" : 4, "make" : "Kiesel", "description" : "Quality guitars made only for custom orders.", "establishedYear" : 2015, "in_stock" : false, "rating" : null } -To learn more about the ``moreLikeThis`` operator, see the :atlas:`moreLikeThis ` +To learn more about the ``moreLikeThis`` operator, see the :atlas:`moreLikeThis ` Atlas guide. Near @@ -414,7 +413,7 @@ The search returns the following documents: { "_id" : 5, "make" : "Ibanez", "description" : "...", "establishedYear" : 1957, "in_stock" : true, "rating" : 7 } -To learn more about the ``near`` operator, see the :atlas:`near ` +To learn more about the ``near`` operator, see the :atlas:`near ` Atlas guide. Phrase @@ -456,7 +455,7 @@ This search returns the following documents: { "_id" : 4, "make" : "Kiesel", "description" : "Quality guitars made only for custom orders.", "establishedYear" : 2015, "in_stock" : false, "rating" : null } { "_id" : 2, "make" : "Gibson", "description" : "Classic guitars known for their rich, full tones.", "establishedYear" : 1902, "in_stock" : true, "rating" : 8 } -To learn more about the ``phrase`` operator, see the :atlas:`phrase ` +To learn more about the ``phrase`` operator, see the :atlas:`phrase ` Atlas guide. QueryString @@ -466,7 +465,7 @@ Use the ``QueryString()`` method to search for documents using a string with the following operators and delimiters: - ``AND`` -- ``OR`` +- ``OR`` - ``NOT`` - ``()`` @@ -490,7 +489,7 @@ The search returns the following documents: { "_id" : 3, "make" : "PRS", "description" : "High-end guitars known for their quality.", "establishedYear" : 1985, "in_stock" : true, "rating" : 9 } { "_id" : 2, "make" : "Gibson", "description" : "Classic guitars known for their rich, full tones.", "establishedYear" : 1902, "in_stock" : true, "rating" : 8 } -To learn more about the ``queryString`` operator, see the :atlas:`queryString ` +To learn more about the ``queryString`` operator, see the :atlas:`queryString ` Atlas guide. Range @@ -516,7 +515,7 @@ The search returns the following results: { "_id" : 4, "make" : "Kiesel", "description" : "Quality guitars made only for custom orders.", "establishedYear" : 2015, "in_stock" : false, "rating" : null } { "_id" : 6, "make" : "Strandberg", "description" : "Modern guitars known for their headless models.", "establishedYear" : 1982, "in_stock" : false, "rating" : null } -To learn more about the ``range`` operator, see the :atlas:`range ` +To learn more about the ``range`` operator, see the :atlas:`range ` Atlas guide. Regex @@ -558,7 +557,7 @@ The search returns the following results: search results. To learn more, see :atlas:`regex Behavior `. -To learn more about the ``regex`` operator, see the :atlas:`regex ` +To learn more about the ``regex`` operator, see the :atlas:`regex ` Atlas guide. Span @@ -593,7 +592,7 @@ Although the document with ``_id: 3`` contains the strings "guitars" and "quality", they are separated by more than one word, so the search omits this document from the results. -To learn more about the ``span`` operator, see the :atlas:`span ` +To learn more about the ``span`` operator, see the :atlas:`span ` Atlas guide. Text @@ -624,7 +623,7 @@ The search returns the following document: If your search string contains multiple terms, the method also looks for a match for each term in the string separately. -To learn more about the ``text`` operator, see the :atlas:`text ` +To learn more about the ``text`` operator, see the :atlas:`text ` Atlas guide. Wildcard @@ -640,7 +639,7 @@ characters in your search: * - Character - Description - + * - ``?`` - Matches any single character @@ -681,35 +680,5 @@ The search returns the following document: search results. To learn more, see :atlas:`wildcard Behavior `. -To learn more about the ``wildcard`` operator, see the :atlas:`wildcard ` -Atlas guide. - -.. 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. - -Build an Atlas Search Query ---------------------------- - -The ``Search`` class provides a type-safe interface for creating a -:manual:`$search ` -pipeline stage. - -To learn how to construct search queries with the ``Search`` class, see -:ref:`csharp-atlas-search`. +To learn more about the ``wildcard`` operator, see the :atlas:`wildcard ` +Atlas guide. \ No newline at end of file diff --git a/source/atlas-vector-search.txt b/source/atlas-vector-search.txt index 73e37027..3f861338 100644 --- a/source/atlas-vector-search.txt +++ b/source/atlas-vector-search.txt @@ -7,9 +7,9 @@ Atlas Vector Search .. facet:: :name: genre :values: reference - + .. meta:: - :keywords: semantic + :keywords: semantic .. contents:: On this page :local: @@ -78,22 +78,23 @@ perform the following operations: .VectorSearch(m => m.Embedding, vector, 10, options) .Project(Builders.Projection .Include(m => m.Title) - .Include(m => m.Plot)); + .Include(m => m.Plot) + .MetaVectorSearchScore(m => m.Score); The results of the preceding example contain the following documents: .. code-block:: json - { "_id" : ObjectId("573a13a0f29313caabd04a4f"), "plot" : "A reporter, learning of time travelers visiting 20th century disasters, tries to change the history they know by averting upcoming disasters.", "title" : "Thrill Seekers" } - { "_id" : ObjectId("573a13d8f29313caabda6557"), "plot" : "At the age of 21, Tim discovers he can travel in time and change what happens and has happened in his own life. His decision to make his world a better place by getting a girlfriend turns out not to be as easy as you might think.", "title" : "About Time" } - { "_id" : ObjectId("573a13a5f29313caabd13b4b"), "plot" : "Hoping to alter the events of the past, a 19th century inventor instead travels 800,000 years into the future, where he finds humankind divided into two warring races.", "title" : "The Time Machine" } - { "_id" : ObjectId("573a13aef29313caabd2e2d7"), "plot" : "After using his mother's newly built time machine, Dolf gets stuck involuntary in the year 1212. He ends up in a children's crusade where he confronts his new friends with modern techniques...", "title" : "Crusade in Jeans" } - { "_id" : ObjectId("573a1399f29313caabceec0e"), "plot" : "An officer for a security agency that regulates time travel, must fend for his life against a shady politician who has a tie to his past.", "title" : "Timecop" } - { "_id" : ObjectId("573a1399f29313caabcee36f"), "plot" : "A time-travel experiment in which a robot probe is sent from the year 2073 to the year 1973 goes terribly wrong thrusting one of the project scientists, a man named Nicholas Sinclair into a...", "title" : "A.P.E.X." } - { "_id" : ObjectId("573a13c6f29313caabd715d3"), "plot" : "Agent J travels in time to M.I.B.'s early days in 1969 to stop an alien from assassinating his friend Agent K and changing history.", "title" : "Men in Black 3" } - { "_id" : ObjectId("573a13d4f29313caabd98c13"), "plot" : "Bound by a shared destiny, a teen bursting with scientific curiosity and a former boy-genius inventor embark on a mission to unearth the secrets of a place somewhere in time and space that exists in their collective memory.", "title" : "Tomorrowland" } - { "_id" : ObjectId("573a13b6f29313caabd477fa"), "plot" : "With the help of his uncle, a man travels to the future to try and bring his girlfriend back to life.", "title" : "Love Story 2050" } - { "_id" : ObjectId("573a13e5f29313caabdc40c9"), "plot" : "A dimension-traveling wizard gets stuck in the 21st century because cell-phone radiation interferes with his magic. With his home world on the brink of war, he seeks help from a jaded ...", "title" : "The Portal" } + { "_id" : { "$oid" : "573a13a0f29313caabd04a4f" }, "plot" : "A reporter, learning of time travelers visiting 20th century disasters, tries to change the history they know by averting upcoming disasters.", "title" : "Thrill Seekers", "score" : 0.926971435546875 } + { "_id" : { "$oid" : "573a13d8f29313caabda6557" }, "plot" : "At the age of 21, Tim discovers he can travel in time and change what happens and has happened in his own life. His decision to make his world a better place by getting a girlfriend turns out not to be as easy as you might think.", "title" : "About Time", "score" : 0. 9267120361328125 } + { "_id" : { "$oid" : "573a1399f29313caabceec0e" }, "plot" : "An officer for a security agency that regulates time travel, must fend for his life against a shady politician who has a tie to his past.", "title" : "Timecop", "score" : 0.9235687255859375 } + { "_id" : { "$oid" : "573a13a5f29313caabd13b4b" }, "plot" : "Hoping to alter the events of the past, a 19th century inventor instead travels 800,000 years into the future, where he finds humankind divided into two warring races.", "title" : "The Time Machine", "score" : 0.9228668212890625 } + { "_id" : { "$oid" : "573a13aef29313caabd2e2d7" }, "plot" : "After using his mother's newly built time machine, Dolf gets stuck involuntary in the year 1212. He ends up in a children's crusade where he confronts his new friends with modern techniques...", "title" : "Crusade in Jeans", "score" : 0.9228515625 } + { "_id" : { "$oid" : "573a1399f29313caabcee36f" }, "plot" : "A time-travel experiment in which a robot probe is sent from the year 2073 to the year 1973 goes terribly wrong thrusting one of the project scientists, a man named Nicholas Sinclair into a...", "title" : "A.P.E.X.", "score" : 0.9199066162109375 } + { "_id" : { "$oid" : "573a13c6f29313caabd715d3" }, "plot" : "Agent J travels in time to M.I.B.'s early days in 1969 to stop an alien from assassinating his friend Agent K and changing history.", "title" : "Men in Black 3", "score" : 0.919403076171875 } + { "_id" : { "$oid" : "573a13d4f29313caabd98c13" }, "plot" : "Bound by a shared destiny, a teen bursting with scientific curiosity and a former boy-genius inventor embark on a mission to unearth the secrets of a place somewhere in time and space that exists in their collective memory.", "title" : "Tomorrowland", "score" : 0. 9191131591796875 } + { "_id" : { "$oid" : "573a13b6f29313caabd477fa" }, "plot" : "With the help of his uncle, a man travels to the future to try and bring his girlfriend back to life.", "title" : "Love Story 2050", "score" : 0. 917755126953125 } + { "_id" : { "$oid" : "573a13b3f29313caabd3ebd4" }, "plot" : "A romantic drama about a Chicago librarian with a gene that causes him to involuntarily time travel, and the complications it creates for his marriage.", "title" : "The Time Traveler's Wife", "score" : 0.9172210693359375 } To learn more about Atlas Vector Search, see :atlas:`Atlas Vector Search Overview ` in the Atlas manual. \ No newline at end of file diff --git a/source/crud/query/project.txt b/source/crud/query/project.txt index cd24ad2d..dd160420 100644 --- a/source/crud/query/project.txt +++ b/source/crud/query/project.txt @@ -27,205 +27,342 @@ which fields MongoDB returns from a query. Sample Data ~~~~~~~~~~~ -The examples in this guide use the ``sample_restaurants.restaurants`` collection +The examples on this page use the ``sample_mflix.movies`` collection from the :atlas:`Atlas sample datasets `. To learn how to create a free MongoDB Atlas cluster and load the sample datasets, see the :ref:``. -Projection Types ----------------- +The following class represents the documents in the ``sample_mflix.movies`` collection: -You can use a projection to specify which fields to include in a return -document, or to specify which fields to exclude. +.. literalinclude:: /includes/code-examples/projection/Movie.cs -When specifying certain fields to include in a projection, all other fields are implicitly -excluded (except the ``_id`` field, which is included by default). You cannot combine -inclusion and exclusion statements in a single projection, unless you are excluding the -``_id`` field. +.. _csharp-projection-methods: -To remove the ``_id`` field from the returned document, you must -:ref:`explicitly exclude it `. +Projection Methods +------------------ -Specify Fields to Include -~~~~~~~~~~~~~~~~~~~~~~~~~ +To create a projection, perform the following steps: -To specify the fields to include from the result, chain the ``Project()`` method -to the ``Find()`` method. When calling the ``Project()`` method, you must pass in the -projection definition as a parameter. You can construct a projection definition by using -the ``Builders.Projection.Include()`` method and passing in the field name to include -as a parameter. This method can be chained to include multiple fields in the projection. +1. Use the ``Builders.Projection`` static property to create a + ``ProjectionDefinitionBuilder object. The ``ProjectionDefinitionBuilder`` class + provides a type-safe interface for defining a projection.``TDocument`` represents the + C# class that the collection's documents map to. -The following example uses the ``Find()`` method to find all restaurants in which the ``name`` -field value is ``"Emerald Pub"``. Then, the code calls the ``Project()`` -method to instruct the find operation to include the ``name`` and ``cuisine`` fields -in the result: +#. Chain projection methods from the ``ProjectionDefinitionBuilder`` + object to specify which fields to include or exclude from the returned documents. -.. io-code-block:: - :copyable: true +#. Store the resulting ``ProjectionDefinition`` object in a variable. - .. input:: /includes/fundamentals/code-examples/Project.cs - :start-after: start-project-include - :end-before: end-project-include - :language: csharp - :dedent: +#. Pass the variable to the ``Project()`` method after performing the find or aggregation + operation. - .. output:: - :visible: false +The following sections describe the methods that you can chain from your +``ProjectionDefinitionBuilder`` object. - { "_id" : ObjectId("..."), "cuisine" : "American", "name" : "Emerald Pub" } - { "_id" : ObjectId("..."), "cuisine" : "American", "name" : "Emerald Pub" } +ElemMatch +~~~~~~~~~ -.. _csharp-project-exclude-id: +The ``ElemMatch()`` method limits the contents of an array field from the query results to +contain only the first element matching a specified condition. This is equivalent to projecting +an array element by using the ``$elemMatch`` operator in the {+query-api+}. -Exclude the ``_id`` Field -~~~~~~~~~~~~~~~~~~~~~~~~~ +For a code example that uses the ``ElemMatch()`` method, see +:manual:`$elemMatch ` +in the {+mdb-server+} manual. -When specifying fields to include, you can also exclude the ``_id`` field from -the returned document. +Expression +~~~~~~~~~~ -The following example runs the same query as the preceding example, but -excludes the ``_id`` field from the projection: +The ``Expression()`` method lets you specify the structure of the returned documents +by using a lambda expression. This is equivalent to specifying the structure of the +returned documents in the ``$project`` aggregation stage in the {+query-api+}. -.. io-code-block:: - :copyable: true +For a code example that uses the ``Expression()`` method, see +:manual:`$project ` in the {+mdb-server+} manual. - .. input:: /includes/fundamentals/code-examples/Project.cs - :start-after: start-project-include-without-id - :end-before: end-project-include-without-id - :language: csharp - :dedent: +.. note:: ``Id`` Field Exclusion - .. output:: - :visible: false + When you use a lambda expression to create a projection, the output + automatically excludes the ``Id`` field unless you explicitly include + it. - { "cuisine" : "American", "name" : "Emerald Pub" } - { "cuisine" : "American", "name" : "Emerald Pub" } +Exclude +~~~~~~~ -Specify Fields to Exclude -~~~~~~~~~~~~~~~~~~~~~~~~~ +The ``Exclude()`` method lets you specify a field to exclude from the returned documents. +This is equivalent to excluding a field in the ``$project`` aggregation stage in the +{+query-api+}. You cannot combine inclusion and exclusion statements in a single +projection unless you are excluding the ``_id`` field. -To specify the fields to exclude from the result, chain the ``Project()`` method -to the ``Find()`` method. You can exclude fields in your projection by using -the ``Builders.Projection.Exclude()`` method and passing in the field name to exclude -as a parameter. This method can be chained to exclude multiple fields in the projection. +For a code example that uses the ``Exclude()`` method, see +:manual:`$project ` in the {+mdb-server+} manual. -The following example uses the ``Find()`` method to find all restaurants in which the ``name`` -field value is ``"Emerald Pub"``. It then uses a projection to exclude the ``cuisine`` -field from the returned documents: +.. note:: Explicitly Exclude ``_id`` Field -.. io-code-block:: - :copyable: true + Returned documents include the ``_id`` field unless you explicitly exclude it. The + only exception to this is when you use the ``Expression()`` method to create a + projection. - .. input:: /includes/fundamentals/code-examples/Project.cs - :start-after: start-project-exclude - :end-before: end-project-exclude - :language: csharp - :dedent: +Include +~~~~~~~ - .. output:: - :visible: false +The ``Include()`` method lets you specify a field to include in the returned documents. +This is equivalent to including a field in the ``$project`` aggregation stage in the +{+query-api+}. - { "_id" : ObjectId("..."), "address" : { "building" : "308", "coord" : [-74.008493599999994, 40.725807199999998], "street" : "Spring Street", "zipcode" : "10013" }, "borough" : "Manhattan", "grades" : [{ "date" : ISODate("2014-02-24T00:00:00Z"), "grade" : "A", "score" : 5 }, { "date" : ISODate("2013-08-26T00:00:00Z"), "grade" : "A", "score" : 13 }, { "date" : ISODate("2013-03-04T00:00:00Z"), "grade" : "A", "score" : 12 }, { "date" : ISODate("2012-06-25T00:00:00Z"), "grade" : "A", "score" : 10 }, { "date" : ISODate("2011-12-23T00:00:00Z"), "grade" : "A", "score" : 10 }, { "date" : ISODate("2011-07-26T00:00:00Z"), "grade" : "C", "score" : 32 }], "name" : "Emerald Pub", "restaurant_id" : "40367329" } - { "_id" : ObjectId("..."), "address" : { "building" : "18301", "coord" : [-73.791184999999999, 40.740119999999997], "street" : "Horace Harding Expressway", "zipcode" : "11365" }, "borough" : "Queens", "grades" : [{ "date" : ISODate("2014-05-07T00:00:00Z"), "grade" : "A", "score" : 12 }, { "date" : ISODate("2013-04-30T00:00:00Z"), "grade" : "A", "score" : 9 }, { "date" : ISODate("2012-03-01T00:00:00Z"), "grade" : "A", "score" : 13 }], "name" : "Emerald Pub", "restaurant_id" : "40668598" } +For a code example that uses the ``Include()`` method, see +:manual:`$project ` in the {+mdb-server+} manual. -Additional Information ----------------------- +Meta +~~~~ -To learn more about projections, see the :manual:`Project Fields guide -` in the {+mdb-server+} manual. +The ``Meta()`` method lets you specify a metadata field to include in the returned +documents. This is equivalent to including a metadata field by using the +:manual:`$meta ` operator in the {+query-api+}. -API Documentation -~~~~~~~~~~~~~~~~~ +The following code example adds the ``textScore`` metadata field to the returned +documents as a field named ``searchScore``: -To learn more about any of the functions or types discussed in this -guide, see the following API Documentation: +.. literalinclude:: /includes/code-examples/projection/MetaExamples.cs + :language: csharp + :dedent: 8 + :start-after: start meta + :end-before: end meta -- `Find() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.IMongoCollectionExtensions.Find.html>`_ -- `Projection <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Builders-1.Projection.html>`_ -- `Include() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.ProjectionDefinitionBuilder-1.Include.html>`_ -- `Exclude() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.ProjectionDefinitionBuilder-1.Exclude.html>`_ +MetaSearchHighlights +~~~~~~~~~~~~~~~~~~~~ -.. TODO: integrate into existing page +.. include:: /includes/project/atlas-only-note.rst -Sample Class ------------- +The ``MetaSearchHighlights()`` includes search highlights +in the returned documents. This is equivalent to projecting search highlights +by using a ``{ "$meta": "searchHighlights" }`` object in the {+query-api+}. +To retrieve search highlights, you must create a ``SearchHighlightOptions`` object that +specifies the search field, and then pass this object to the ``Search()`` method. -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: +The following code example retrieves search highlights for the ``plot`` field, then +includes these highlights in a property named ``Highlights`` in the returned documents: -.. literalinclude:: /includes/fundamentals/code-examples/builders.cs +.. literalinclude:: /includes/code-examples/projection/MetaExamples.cs :language: csharp - :dedent: - :start-after: start-model - :end-before: end-model + :dedent: 8 + :start-after: start metaSearchHighlights + :end-before: end metaSearchHighlights -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. +To learn more about search highlights, see +:atlas:`Highlight Search Terms in Results ` +in the Atlas documentation. -.. _csharp-builders-projection: +MetaSearchScore +~~~~~~~~~~~~~~~ -Create a Projection -------------------- +.. include:: /includes/project/atlas-only-note.rst -The ``ProjectionDefinitionBuilder`` class provides a type-safe interface for -defining a projection. Suppose you want to create a projection on the -``Name`` and ``Price`` fields, but exclude the ``Id`` field. +The ``MetaSearchScore()`` method includes search scores in the returned +documents. This is equivalent to projecting search scores +by using a ``{ "$meta": "searchScore" }`` object in the {+query-api+}. -Use builders to create the projection definition with the typed variant: +The following code example projects each document's search score in a property named +``Score``: -.. code-block:: csharp - :copyable: true +.. literalinclude:: /includes/code-examples/projection/MetaExamples.cs + :language: csharp + :dedent: 8 + :start-after: start metaSearchScore + :end-before: end metaSearchScore - var builder = Builders.Projection; - var projection = builder.Include(f => f.Name).Include(f => f.Price).Exclude(f => f.Id); +To learn more about search scores, see +:atlas:`Score the Documents in the Returned Documents `. -You can also use string-based field names to define the projection: +MetaSearchScoreDetails +~~~~~~~~~~~~~~~~~~~~~~ -.. code-block:: csharp - :copyable: true +.. include:: /includes/project/atlas-only-note.rst - var builder = Builders.Projection; - var projection = builder.Include("Name").Include("Price").Exclude("Id"); +The ``MetaSearchScoreDetails()`` includes details about the search scores +in the returned documents. This is equivalent to projecting search score details +by using a ``{ "$meta": "searchScoreDetails" }`` object in the {+query-api+}. -Finally, you can use the ``Expression()`` method to define the -projection: +To retrieve score details, you must create a ``SearchOptions`` object that, set its +``ScoreDetails`` property to ``true``, and then pass this object to the ``Search()`` method. +The following code example shows this process by projecting each document's search score +details in a property named ``ScoreDetails``: -.. code-block:: csharp - :copyable: true +.. literalinclude:: /includes/code-examples/projection/MetaExamples.cs + :language: csharp + :dedent: 8 + :start-after: start metaSearchScoreDetails + :end-before: end metaSearchScoreDetails - var builder = Builders.Projection; - var projection = builder.Expression(f => new { Name = f.Name, Price = f.Price }); +To learn more about search score details, see +:atlas:`Return the Score Details ` +in the Atlas documentation. -This definition has a return type of ``ProjectionDefinition`` whereas the others return a -``ProjectionDefinition``. +MetaSearchSequenceToken +~~~~~~~~~~~~~~~~~~~~~~~ -Lambda Expressions -~~~~~~~~~~~~~~~~~~ +.. include:: /includes/project/atlas-only-note.rst -The driver supports using lambda expressions to render projections. When -you define a ``Find()`` projection with the ``Expression()`` method to -create a lambda expression, the driver inspects the expression -to determine which fields are referenced and automatically constructs a -server-side projection to return only those fields. +The ``MetaSearchSequenceToken()`` method includes a token in the returned documents +that represents a point in the search sequence. This is equivalent to projecting the search +sequence token by using a ``{ "$meta": "searchSequenceToken" }`` object in the +{+query-api+}. You can use this token to perform additional searches before or after the +specified point. -You can also use lambda expressions to create new fields by performing -operations on values in your documents. The following example shows how -you can use a lambda expression to project a new ``Profit`` field -using the ``Price`` and ``Stock`` fields: +The following code example projects each document's search sequence token in a property +named ``PaginationToken``: -.. code-block:: csharp - :copyable: true +.. literalinclude:: /includes/code-examples/projection/MetaExamples.cs + :language: csharp + :dedent: 8 + :start-after: start metaSearchSequenceToken + :end-before: end metaSearchSequenceToken - var builder = Builders.Projection; - var projection = builder.Expression(f => new { Profit = f.Price * f.Stock }); +To learn more about search sequence tokens, see +:atlas:`Paginate Search Results ` -.. note:: ``Id`` Field Exclusion +MetaTextScore +~~~~~~~~~~~~~ - When you create a projection using a lambda expression, the output - automatically excludes the ``Id`` field unless you explicitly include - is as a projection field. +The ``MetaTextScore()`` method includes the ``$text`` search scores in the returned documents. +This is equivalent to projecting the text search score by using a +``{ "$meta": "textScore" }`` object in the {+query-api+}. + +For a code example that uses the ``MetaTextScore()`` method, see +:manual:`$meta ` +in the {+mdb-server+} manual. + +MetaVectorSearchScore +~~~~~~~~~~~~~~~~~~~~~ + +.. note:: Atlas Vector Search Only + + This method is available only when projecting the results of an Atlas Vector Search. + +The ``MetaVectorSearchScore()`` method includes the Atlas Vector Search scores in the +returned documents. This is equivalent to projecting the Vector Search score by using a +``{ "$meta": "vectorSearchScore" }`` object in the {+query-api+}. + +For a code example that uses the ``MetaVectorSearchScore()`` method, see +:ref:`Atlas Vector Search `. + +To learn more about Atlas Vector Search scores, see +:atlas:`Score the Documents in the Returned Documents ` +in the Atlas documentation. + +SearchMeta +~~~~~~~~~~ + +.. include:: /includes/project/atlas-only-note.rst + +The ``SearchMeta()`` method includes a metadata results document. The structure of this +document depends on the type of the results. This is equivalent to projecting the +metadata results document by using the ``$searchMeta`` aggregation stage or the +``$$SEARCH_META`` aggregation variable in the {+query-api+}. + +For a code example that uses the ``SearchMeta()`` method, see +:atlas:`How to Use Facets with Atlas Search ` +in the Atlas documentation. + +To learn more about ``$searchMeta`` and ``$$SEARCH_META``, see the following Atlas +documentation: + +- :atlas:`$searchMeta ` +- :atlas:`$search with $$SEARCH_META ` + +Slice +~~~~~ -- `ProjectionDefinitionBuilder <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.ProjectionDefinitionBuilder-1.html>`__ \ No newline at end of file +The ``Slice()`` method specifies the number of elements in an array to return in the query +result. This is equivalent to using the ``$slice`` operator in the {+query-api+}. + +The following code example uses the ``Slice()`` method to return the first three elements +of the ``cast`` array in the returned document: + +.. io-code-block:: + + .. input:: + :language: csharp + + .. literalinclude:: /includes/code-examples/projection/SliceExamples.cs + :language: csharp + :dedent: 8 + :start-after: // start first three + :end-before: // end first three + + .. output:: + :language: json + + { "_id" : { "$oid" : "573a1398f29313caabceb500" }, + "title" : "Back to the Future Part II", + "cast" : ["Michael J. Fox", "Christopher Lloyd", "Lea Thompson"] } + +To return elements from the end of an array, pass a negative integer to the ``Slice()`` +method. The method returns the specified number of elements from the end of the array. +The following code example returns the last three elements of the ``cast`` array in the +returned document: + +.. io-code-block:: + + .. input:: + :language: csharp + + .. literalinclude:: /includes/code-examples/projection/SliceExamples.cs + :language: csharp + :dedent: 8 + :start-after: // start last three + :end-before: // end last three + + .. output:: + :language: json + + { "_id" : { "$oid" : "573a1398f29313caabceb500" }, + "title" : "Back to the Future Part II", + "cast" : ["Lea Thompson", "Thomas F. Wilson"] } + +To skip a specified number of elements in the array, pass the number of elements to skip +as the first parameter and the number of elements to return as the second +parameter. The following code example skips the first element in the +``cast`` array and returns the next three elements: + +.. io-code-block:: + + .. input:: + :language: csharp + + .. literalinclude:: /includes/code-examples/projection/SliceExamples.cs + :language: csharp + :dedent: 8 + :start-after: // start skip first limit three + :end-before: // end skip first limit three + + .. output:: + :language: json + + { "_id" : { "$oid" : "573a1398f29313caabceb500" }, + "title" : "Back to the Future Part II", + "cast" : ["Christopher Lloyd", "Lea Thompson", "Thomas F. Wilson"] } + +To learn more about the ``$slice`` operator, see +:manual:`$slice ` in the {+mdb-server+} manual. + +API Documentation +----------------- + +To learn more about any of the methods or types discussed in this +guide, see the following API documentation: + +- `Projection <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.Builders-1.Projection.html>`_ +- `ProjectionDefinitionBuilder <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.ProjectionDefinitionBuilder-1.html>`__ +- `ElemMatch() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.ProjectionDefinitionBuilder-1.ElemMatch.html>`__ +- `Exclude() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.ProjectionDefinitionBuilder-1.Exclude.html>`__ +- `Expression() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.ProjectionDefinitionBuilder-1.Expression.html>`__ +- `Include() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.ProjectionDefinitionBuilder-1.Include.html>`__ +- `Meta() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.ProjectionDefinitionBuilder-1.Meta.html>`__ +- `MetaSearchHighlights <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.ProjectionDefinitionBuilder-1.MetaSearchHighlights.html>`__ +- `MetaSearchScore() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.ProjectionDefinitionBuilder-1.MetaSearchScore.html>`__ +- `MetaSearchScoreDetails() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.ProjectionDefinitionBuilder-1.MetaSearchScoreDetails.html>`__ +- `MetaSearchSequenceToken() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.ProjectionDefinitionBuilder-1.MetaSearchSequenceToken.html>`__ +- `MetaTextScore() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.ProjectionDefinitionBuilder-1.MetaTextScore.html>`__ +- `MetaVectorSearchScore() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.ProjectionDefinitionBuilder-1.MetaVectorSearchScore.html>`__ +- `SearchMeta() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.ProjectionDefinitionBuilder-1.SearchMeta.html>`__ +- `Slice() <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.ProjectionDefinitionBuilder-1.Slice.html>`__ \ No newline at end of file diff --git a/source/includes/code-examples/projection/MetaExamples.cs b/source/includes/code-examples/projection/MetaExamples.cs new file mode 100644 index 00000000..41063c8f --- /dev/null +++ b/source/includes/code-examples/projection/MetaExamples.cs @@ -0,0 +1,196 @@ +using MongoDB.Bson; +using MongoDB.Driver; +using MongoDB.Driver.Search; + +namespace Projection; + +public class MetaExamples +{ + static string _uri = ""; + + static IMongoCollection movieCollection = new MongoClient(_uri) + .GetDatabase("sample_mflix") + .GetCollection("movies"); + + static IMongoCollection embeddedMovieCollection = new MongoClient(_uri) + .GetDatabase("sample_mflix") + .GetCollection("embedded_movies"); + + public static void CreateIndex() + { + // start createIndex + var indexModel = new CreateIndexModel( + Builders.IndexKeys.Text(m => m.Title)); + movieCollection.Indexes.CreateOne(indexModel); + // end createIndex + } + + public static List MetaTextScoreExample() + { + // start metaTextScore + var filter = Builders.Filter.Text("future"); + var projection = Builders.Projection.MetaTextScore("score"); + + var results = movieCollection.Find(filter) + .Project(projection) + .Limit(1) + .ToList(); + // end metaTextScore + + return results; + } + + public static List MetaExample() + { + // start meta + var filter = Builders.Filter.Text("future"); + var projection = Builders.Projection.Meta( + field: "searchScore", + metaFieldName: "textScore"); + + var results = movieCollection.Find(filter) + .Project(projection) + .Limit(1) + .ToList(); + // end meta + + return results; + } + + public static List MetaScoreExample() + { + // start metaScore + var filter = Builders.Search.Text(m => m.Title, "future"); + var projection = Builders.Projection.MetaScore("scoreDetails"); + + var results = movieCollection + .Aggregate() + .Search(filter) + .Project(projection) + .Limit(1) + .ToList(); + // end metaScore + + return results; + } + + public static List MetaScoreDetailsExample() + { + // start metaScoreDetails + var filter = Builders.Filter.Text("future"); + var projection = Builders.Projection.MetaScoreDetails("detailsOfTheScore"); + + var results = movieCollection.Find(filter) + .Project(projection) + .Limit(1) + .ToList(); + // end metaScoreDetails + + return results; + } + + public static List MetaSearchHighlightsExample() + { + // start metaSearchHighlights + var filter = Builders.Search.Phrase(m => m.Plot, "future"); + var projection = Builders.Projection + .MetaSearchHighlights(m => m.Highlights); + + var results = movieCollection + .Aggregate() + .Search(filter, new SearchHighlightOptions (m => m.Plot)) + .Project(projection) + .Limit(1) + .ToList(); + // end metaSearchHighlights + + return results; + } + + public static List MetaSearchScoreExample() + { + // start metaSearchScore + var filter = Builders.Search.Phrase(m => m.Plot, "future"); + var projection = Builders.Projection + .Include(m => m.Title) + .Include(m => m.Plot) + .MetaSearchScore(m => m.Score); + + var results = movieCollection + .Aggregate() + .Search(filter) + .Project(projection) + .Limit(1) + .ToList(); + // end metaSearchScore + + return results; + } + + public static List MetaSearchScoreDetailsExample() + { + // start metaSearchScoreDetails + var filter = Builders.Search.Phrase(m => m.Plot, "future"); + var projection = Builders.Projection + .Include(m => m.Title) + .Include(m => m.Plot) + .MetaSearchScore(m => m.Score) + .MetaSearchScoreDetails(m => m.ScoreDetails); + + var results = movieCollection + .Aggregate() + .Search(filter, new SearchOptions() { ScoreDetails = true}) + .Project(projection) + .Limit(1) + .ToList(); + // end metaSearchScoreDetails + + return results; + } + + public static List MetaSearchSequenceTokenExample() + { + // start metaSearchSequenceToken + var filter = Builders.Search.Phrase(m => m.Plot, "future"); + var projection = Builders.Projection + .Include(m => m.Title) + .Include(m => m.Plot) + .MetaSearchSequenceToken(m => m.PaginationToken); + + var results = movieCollection + .Aggregate() + .Search(filter) + .Limit(1) + .Project(projection) + .ToList(); + // end metaSearchSequenceToken + + return results; + } + + public static List MetaVectorSearchScoreExample() + { + // start metaVectorSearchScore + QueryVector vector = new[] { -0.0016261312, -0.028070757, -0.011342932, -0.012775794, -0.0027440966, 0.008683807, -0.02575152, -0.02020668, -0.010283281, -0.0041719596, 0.021392956, 0.028657231, -0.006634482, 0.007490867, 0.018593878, 0.0038187427, 0.029590257, -0.01451522, 0.016061379, 0.00008528442, -0.008943722, 0.01627464, 0.024311995, -0.025911469, 0.00022596726, -0.008863748, 0.008823762, -0.034921836, 0.007910728, -0.01515501, 0.035801545, -0.0035688248, -0.020299982, -0.03145631, -0.032256044, -0.028763862, -0.0071576433, -0.012769129, 0.012322609, -0.006621153, 0.010583182, 0.024085402, -0.001623632, 0.007864078, -0.021406285, 0.002554159, 0.012229307, -0.011762793, 0.0051682983, 0.0048484034, 0.018087378, 0.024325324, -0.037694257, -0.026537929, -0.008803768, -0.017767483, -0.012642504, -0.0062712682, 0.0009771782, -0.010409906, 0.017754154, -0.004671795, -0.030469967, 0.008477209, -0.005218282, -0.0058480743, -0.020153364, -0.0032805866, 0.004248601, 0.0051449724, 0.006791097, 0.007650814, 0.003458861, -0.0031223053, -0.01932697, -0.033615597, 0.00745088, 0.006321252, -0.0038154104, 0.014555207, 0.027697546, -0.02828402, 0.0066711367, 0.0077107945, 0.01794076, 0.011349596, -0.0052715978, 0.014755142, -0.019753495, -0.011156326, 0.011202978, 0.022126047, 0.00846388, 0.030549942, -0.0041386373, 0.018847128, -0.00033655585, 0.024925126, -0.003555496, -0.019300312, 0.010749794, 0.0075308536, -0.018287312, -0.016567878, -0.012869096, -0.015528221, 0.0078107617, -0.011156326, 0.013522214, -0.020646535, -0.01211601, 0.055928253, 0.011596181, -0.017247654, 0.0005939711, -0.026977783, -0.003942035, -0.009583511, -0.0055248477, -0.028737204, 0.023179034, 0.003995351, 0.0219661, -0.008470545, 0.023392297, 0.010469886, -0.015874773, 0.007890735, -0.009690142, -0.00024970944, 0.012775794, 0.0114762215, 0.013422247, 0.010429899, -0.03686786, -0.006717788, -0.027484283, 0.011556195, -0.036068123, -0.013915418, -0.0016327957, 0.0151016945, -0.020473259, 0.004671795, -0.012555866, 0.0209531, 0.01982014, 0.024485271, 0.0105431955, -0.005178295, 0.033162415, -0.013795458, 0.007150979, 0.010243294, 0.005644808, 0.017260984, -0.0045618312, 0.0024725192, 0.004305249, -0.008197301, 0.0014203656, 0.0018460588, 0.005015015, -0.011142998, 0.01439526, 0.022965772, 0.02552493, 0.007757446, -0.0019726837, 0.009503538, -0.032042783, 0.008403899, -0.04609149, 0.013808787, 0.011749465, 0.036388017, 0.016314628, 0.021939443, -0.0250051, -0.017354285, -0.012962398, 0.00006107364, 0.019113706, 0.03081652, -0.018114036, -0.0084572155, 0.009643491, -0.0034721901, 0.0072642746, -0.0090636825, 0.01642126, 0.013428912, 0.027724205, 0.0071243206, -0.6858542, -0.031029783, -0.014595194, -0.011449563, 0.017514233, 0.01743426, 0.009950057, 0.0029706885, -0.015714826, -0.001806072, 0.011856096, 0.026444625, -0.0010663156, -0.006474535, 0.0016161345, -0.020313311, 0.0148351155, -0.0018393943, 0.0057347785, 0.018300641, -0.018647194, 0.03345565, -0.008070676, 0.0071443142, 0.014301958, 0.0044818576, 0.003838736, -0.007350913, -0.024525259, -0.001142124, -0.018620536, 0.017247654, 0.007037683, 0.010236629, 0.06046009, 0.0138887605, -0.012122675, 0.037694257, 0.0055081863, 0.042492677, 0.00021784494, -0.011656162, 0.010276617, 0.022325981, 0.005984696, -0.009496873, 0.013382261, -0.0010563189, 0.0026507939, -0.041639622, 0.008637156, 0.026471283, -0.008403899, 0.024858482, -0.00066686375, -0.0016252982, 0.027590916, 0.0051449724, 0.0058647357, -0.008743787, -0.014968405, 0.027724205, -0.011596181, 0.0047650975, -0.015381602, 0.0043718936, 0.002159289, 0.035908177, -0.008243952, -0.030443309, 0.027564257, 0.042625964, -0.0033688906, 0.01843393, 0.019087048, 0.024578573, 0.03268257, -0.015608194, -0.014128681, -0.0033538956, -0.0028757197, -0.004121976, -0.032389335, 0.0034322033, 0.058807302, 0.010943064, -0.030523283, 0.008903735, 0.017500903, 0.00871713, -0.0029406983, 0.013995391, -0.03132302, -0.019660193, -0.00770413, -0.0038853872, 0.0015894766, -0.0015294964, -0.006251275, -0.021099718, -0.010256623, -0.008863748, 0.028550599, 0.02020668, -0.0012962399, -0.003415542, -0.0022509254, 0.0119360695, 0.027590916, -0.046971202, -0.0015194997, -0.022405956, 0.0016677842, -0.00018535563, -0.015421589, -0.031802863, 0.03814744, 0.0065411795, 0.016567878, -0.015621523, 0.022899127, -0.011076353, 0.02841731, -0.002679118, -0.002342562, 0.015341615, 0.01804739, -0.020566562, -0.012989056, -0.002990682, 0.01643459, 0.00042527664, 0.008243952, -0.013715484, -0.004835075, -0.009803439, 0.03129636, -0.021432944, 0.0012087687, -0.015741484, -0.0052016205, 0.00080890034, -0.01755422, 0.004811749, -0.017967418, -0.026684547, -0.014128681, 0.0041386373, -0.013742141, -0.010056688, -0.013268964, -0.0110630235, -0.028337335, 0.015981404, -0.00997005, -0.02424535, -0.013968734, -0.028310679, -0.027750863, -0.020699851, 0.02235264, 0.001057985, 0.00081639783, -0.0099367285, 0.013522214, -0.012016043, -0.00086471526, 0.013568865, 0.0019376953, -0.019020405, 0.017460918, -0.023045745, 0.008503866, 0.0064678704, -0.011509543, 0.018727167, -0.003372223, -0.0028690554, -0.0027024434, -0.011902748, -0.012182655, -0.015714826, -0.0098634185, 0.00593138, 0.018753825, 0.0010146659, 0.013029044, 0.0003521757, -0.017620865, 0.04102649, 0.00552818, 0.024485271, -0.009630162, -0.015608194, 0.0006718621, -0.0008418062, 0.012395918, 0.0057980907, 0.016221326, 0.010616505, 0.004838407, -0.012402583, 0.019900113, -0.0034521967, 0.000247002, -0.03153628, 0.0011038032, -0.020819811, 0.016234655, -0.00330058, -0.0032289368, 0.00078973995, -0.021952773, -0.022459272, 0.03118973, 0.03673457, -0.021472929, 0.0072109587, -0.015075036, 0.004855068, -0.0008151483, 0.0069643734, 0.010023367, -0.010276617, -0.023019087, 0.0068244194, -0.0012520878, -0.0015086699, 0.022046074, -0.034148756, -0.0022192693, 0.002427534, -0.0027124402, 0.0060346797, 0.015461575, 0.0137554705, 0.009230294, -0.009583511, 0.032629255, 0.015994733, -0.019167023, -0.009203636, 0.03393549, -0.017274313, -0.012042701, -0.0009930064, 0.026777849, -0.013582194, -0.0027590916, -0.017594207, -0.026804507, -0.0014236979, -0.022032745, 0.0091236625, -0.0042419364, -0.00858384, -0.0033905501, -0.020739838, 0.016821127, 0.022539245, 0.015381602, 0.015141681, 0.028817179, -0.019726837, -0.0051283115, -0.011489551, -0.013208984, -0.0047017853, -0.0072309524, 0.01767418, 0.0025658219, -0.010323267, 0.012609182, -0.028097415, 0.026871152, -0.010276617, 0.021912785, 0.0022542577, 0.005124979, -0.0019710176, 0.004518512, -0.040360045, 0.010969722, -0.0031539614, -0.020366628, -0.025778178, -0.0110030435, -0.016221326, 0.0036587953, 0.016207997, 0.003007343, -0.0032555948, 0.0044052163, -0.022046074, -0.0008822095, -0.009363583, 0.028230704, -0.024538586, 0.0029840174, 0.0016044717, -0.014181997, 0.031349678, -0.014381931, -0.027750863, 0.02613806, 0.0004136138, -0.005748107, -0.01868718, -0.0010138329, 0.0054348772, 0.010703143, -0.003682121, 0.0030856507, -0.004275259, -0.010403241, 0.021113047, -0.022685863, -0.023032416, 0.031429652, 0.001792743, -0.005644808, -0.011842767, -0.04078657, -0.0026874484, 0.06915057, -0.00056939584, -0.013995391, 0.010703143, -0.013728813, -0.022939114, -0.015261642, -0.022485929, 0.016807798, 0.007964044, 0.0144219175, 0.016821127, 0.0076241563, 0.005461535, -0.013248971, 0.015301628, 0.0085171955, -0.004318578, 0.011136333, -0.0059047225, -0.010249958, -0.018207338, 0.024645219, 0.021752838, 0.0007614159, -0.013648839, 0.01111634, -0.010503208, -0.0038487327, -0.008203966, -0.00397869, 0.0029740208, 0.008530525, 0.005261601, 0.01642126, -0.0038753906, -0.013222313, 0.026537929, 0.024671877, -0.043505676, 0.014195326, 0.024778508, 0.0056914594, -0.025951454, 0.017620865, -0.0021359634, 0.008643821, 0.021299653, 0.0041686273, -0.009017031, 0.04044002, 0.024378639, -0.027777521, -0.014208655, 0.0028623908, 0.042119466, 0.005801423, -0.028124074, -0.03129636, 0.022139376, -0.022179363, -0.04067994, 0.013688826, 0.013328944, 0.0046184794, -0.02828402, -0.0063412455, -0.0046184794, -0.011756129, -0.010383247, -0.0018543894, -0.0018593877, -0.00052024535, 0.004815081, 0.014781799, 0.018007403, 0.01306903, -0.020433271, 0.009043689, 0.033189073, -0.006844413, -0.019766824, -0.018767154, 0.00533491, -0.0024575242, 0.018727167, 0.0058080875, -0.013835444, 0.0040719924, 0.004881726, 0.012029372, 0.005664801, 0.03193615, 0.0058047553, 0.002695779, 0.009290274, 0.02361889, 0.017834127, 0.0049017193, -0.0036388019, 0.010776452, -0.019793482, 0.0067777685, -0.014208655, -0.024911797, 0.002385881, 0.0034988478, 0.020899786, -0.0025858153, -0.011849431, 0.033189073, -0.021312982, 0.024965113, -0.014635181, 0.014048708, -0.0035921505, -0.003347231, 0.030869836, -0.0017161017, -0.0061346465, 0.009203636, -0.025165047, 0.0068510775, 0.021499587, 0.013782129, -0.0024475274, -0.0051149824, -0.024445284, 0.006167969, 0.0068844, -0.00076183246, 0.030150073, -0.0055948244, -0.011162991, -0.02057989, -0.009703471, -0.020646535, 0.008004031, 0.0066378145, -0.019900113, -0.012169327, -0.01439526, 0.0044252095, -0.004018677, 0.014621852, -0.025085073, -0.013715484, -0.017980747, 0.0071043274, 0.011456228, -0.01010334, -0.0035321703, -0.03801415, -0.012036037, -0.0028990454, -0.05419549, -0.024058744, -0.024272008, 0.015221654, 0.027964126, 0.03182952, -0.015354944, 0.004855068, 0.011522872, 0.004771762, 0.0027874154, 0.023405626, 0.0004242353, -0.03132302, 0.007057676, 0.008763781, -0.0027057757, 0.023005757, -0.0071176565, -0.005238275, 0.029110415, -0.010989714, 0.013728813, -0.009630162, -0.029137073, -0.0049317093, -0.0008630492, -0.015248313, 0.0043219104, -0.0055681667, -0.013175662, 0.029723546, 0.025098402, 0.012849103, -0.0009996708, 0.03118973, -0.0021709518, 0.0260181, -0.020526575, 0.028097415, -0.016141351, 0.010509873, -0.022965772, 0.002865723, 0.0020493253, 0.0020509914, -0.0041419696, -0.00039695262, 0.017287642, 0.0038987163, 0.014795128, -0.014661839, -0.008950386, 0.004431874, -0.009383577, 0.0012604183, -0.023019087, 0.0029273694, -0.033135757, 0.009176978, -0.011023037, -0.002102641, 0.02663123, -0.03849399, -0.0044152127, 0.0004527676, -0.0026924468, 0.02828402, 0.017727496, 0.035135098, 0.02728435, -0.005348239, -0.001467017, -0.019766824, 0.014715155, 0.011982721, 0.0045651635, 0.023458943, -0.0010046692, -0.0031373003, -0.0006972704, 0.0019043729, -0.018967088, -0.024311995, 0.0011546199, 0.007977373, -0.004755101, -0.010016702, -0.02780418, -0.004688456, 0.013022379, -0.005484861, 0.0017227661, -0.015394931, -0.028763862, -0.026684547, 0.0030589928, -0.018513903, 0.028363993, 0.0044818576, -0.009270281, 0.038920518, -0.016008062, 0.0093902415, 0.004815081, -0.021059733, 0.01451522, -0.0051583014, 0.023765508, -0.017874114, -0.016821127, -0.012522544, -0.0028390652, 0.0040886537, 0.020259995, -0.031216389, -0.014115352, -0.009176978, 0.010303274, 0.020313311, 0.0064112223, -0.02235264, -0.022872468, 0.0052449396, 0.0005723116, 0.0037321046, 0.016807798, -0.018527232, -0.009303603, 0.0024858483, -0.0012662497, -0.007110992, 0.011976057, -0.007790768, -0.042999174, -0.006727785, -0.011829439, 0.007024354, 0.005278262, -0.017740825, -0.0041519664, 0.0085905045, 0.027750863, -0.038387362, 0.024391968, 0.00087721116, 0.010509873, -0.00038508154, -0.006857742, 0.0183273, -0.0037054466, 0.015461575, 0.0017394272, -0.0017944091, 0.014181997, -0.0052682655, 0.009023695, 0.00719763, -0.013522214, 0.0034422, 0.014941746, -0.0016711164, -0.025298337, -0.017634194, 0.0058714002, -0.005321581, 0.017834127, 0.0110630235, -0.03369557, 0.029190388, -0.008943722, 0.009363583, -0.0034222065, -0.026111402, -0.007037683, -0.006561173, 0.02473852, -0.007084334, -0.010110005, -0.008577175, 0.0030439978, -0.022712521, 0.0054582027, -0.0012620845, -0.0011954397, -0.015741484, 0.0129557345, -0.00042111133, 0.00846388, 0.008930393, 0.016487904, 0.010469886, -0.007917393, -0.011762793, -0.0214596, 0.000917198, 0.021672864, 0.010269952, -0.007737452, -0.010243294, -0.0067244526, -0.015488233, -0.021552904, 0.017127695, 0.011109675, 0.038067464, 0.00871713, -0.0025591573, 0.021312982, -0.006237946, 0.034628596, -0.0045251767, 0.008357248, 0.020686522, 0.0010696478, 0.0076708077, 0.03772091, -0.018700508, -0.0020676525, -0.008923728, -0.023298996, 0.018233996, -0.010256623, 0.0017860786, 0.009796774, -0.00897038, -0.01269582, -0.018527232, 0.009190307, -0.02372552, -0.042119466, 0.008097334, -0.0066778013, -0.021046404, 0.0019593548, 0.011083017, -0.0016028056, 0.012662497, -0.000059095124, 0.0071043274, -0.014675168, 0.024831824, -0.053582355, 0.038387362, 0.0005698124, 0.015954746, 0.021552904, 0.031589597, -0.009230294, -0.0006147976, 0.002625802, -0.011749465, -0.034362018, -0.0067844326, -0.018793812, 0.011442899, -0.008743787, 0.017474247, -0.021619547, 0.01831397, -0.009037024, -0.0057247817, -0.02728435, 0.010363255, 0.034415334, -0.024032086, -0.0020126705, -0.0045518344, -0.019353628, -0.018340627, -0.03129636, -0.0034038792, -0.006321252, -0.0016161345, 0.033642255, -0.000056075285, -0.005005019, 0.004571828, -0.0024075406, -0.00010215386, 0.0098634185, 0.1980148, -0.003825407, -0.025191706, 0.035161756, 0.005358236, 0.025111731, 0.023485601, 0.0023342315, -0.011882754, 0.018287312, -0.0068910643, 0.003912045, 0.009243623, -0.001355387, -0.028603915, -0.012802451, -0.030150073, -0.014795128, -0.028630573, -0.0013487226, 0.002667455, 0.00985009, -0.0033972147, -0.021486258, 0.009503538, -0.017847456, 0.013062365, -0.014341944, 0.005078328, 0.025165047, -0.015594865, -0.025924796, -0.0018177348, 0.010996379, -0.02993681, 0.007324255, 0.014475234, -0.028577257, 0.005494857, 0.00011725306, -0.013315615, 0.015941417, 0.009376912, 0.0025158382, 0.008743787, 0.023832154, -0.008084005, -0.014195326, -0.008823762, 0.0033455652, -0.032362677, -0.021552904, -0.0056081535, 0.023298996, -0.025444955, 0.0097301295, 0.009736794, 0.015274971, -0.0012937407, -0.018087378, -0.0039387033, 0.008637156, -0.011189649, -0.00023846315, -0.011582852, 0.0066411467, -0.018220667, 0.0060846633, 0.0376676, -0.002709108, 0.0072776037, 0.0034188742, -0.010249958, -0.0007747449, -0.00795738, -0.022192692, 0.03910712, 0.032122757, 0.023898797, 0.0076241563, -0.007397564, -0.003655463, 0.011442899, -0.014115352, -0.00505167, -0.031163072, 0.030336678, -0.006857742, -0.022259338, 0.004048667, 0.02072651, 0.0030156737, -0.0042119464, 0.00041861215, -0.005731446, 0.011103011, 0.013822115, 0.021512916, 0.009216965, -0.006537847, -0.027057758, -0.04054665, 0.010403241, -0.0056281467, -0.005701456, -0.002709108, -0.00745088, -0.0024841821, 0.009356919, -0.022659205, 0.004061996, -0.013175662, 0.017074378, -0.006141311, -0.014541878, 0.02993681, -0.00028448965, -0.025271678, 0.011689484, -0.014528549, 0.004398552, -0.017274313, 0.0045751603, 0.012455898, 0.004121976, -0.025458284, -0.006744446, 0.011822774, -0.015035049, -0.03257594, 0.014675168, -0.0039187097, 0.019726837, -0.0047251107, 0.0022825818, 0.011829439, 0.005391558, -0.016781142, -0.0058747325, 0.010309938, -0.013049036, 0.01186276, -0.0011246296, 0.0062112883, 0.0028190718, -0.021739509, 0.009883412, -0.0073175905, -0.012715813, -0.017181009, -0.016607866, -0.042492677, -0.0014478565, -0.01794076, 0.012302616, -0.015194997, -0.04433207, -0.020606548, 0.009696807, 0.010303274, -0.01694109, -0.004018677, 0.019353628, -0.001991011, 0.000058938927, 0.010536531, -0.17274313, 0.010143327, 0.014235313, -0.024152048, 0.025684876, -0.0012504216, 0.036601283, -0.003698782, 0.0007310093, 0.004165295, -0.0029157067, 0.017101036, -0.046891227, -0.017460918, 0.022965772, 0.020233337, -0.024072073, 0.017220996, 0.009370248, 0.0010363255, 0.0194336, -0.019606877, 0.01818068, -0.020819811, 0.007410893, 0.0019326969, 0.017887443, 0.006651143, 0.00067394477, -0.011889419, -0.025058415, -0.008543854, 0.021579562, 0.0047484366, 0.014062037, 0.0075508473, -0.009510202, -0.009143656, 0.0046817916, 0.013982063, -0.0027990784, 0.011782787, 0.014541878, -0.015701497, -0.029350337, 0.021979429, 0.01332228, -0.026244693, -0.0123492675, -0.003895384, 0.0071576433, -0.035454992, -0.00046984528, 0.0033522295, 0.039347045, 0.0005119148, 0.00476843, -0.012995721, 0.0024042083, -0.006931051, -0.014461905, -0.0127558, 0.0034555288, -0.0074842023, -0.030256703, -0.007057676, -0.00807734, 0.007804097, -0.006957709, 0.017181009, -0.034575284, -0.008603834, -0.005008351, -0.015834786, 0.02943031, 0.016861115, -0.0050849924, 0.014235313, 0.0051449724, 0.0025924798, -0.0025741523, 0.04289254, -0.002104307, 0.012969063, -0.008310596, 0.00423194, 0.0074975314, 0.0018810473, -0.014248641, -0.024725191, 0.0151016945, -0.017527562, 0.0018727167, 0.0002830318, 0.015168339, 0.0144219175, -0.004048667, -0.004358565, 0.011836103, -0.010343261, -0.005911387, 0.0022825818, 0.0073175905, 0.00403867, 0.013188991, 0.03334902, 0.006111321, 0.008597169, 0.030123414, -0.015474904, 0.0017877447, -0.024551915, 0.013155668, 0.023525586, -0.0255116, 0.017220996, 0.004358565, -0.00934359, 0.0099967085, 0.011162991, 0.03092315, -0.021046404, -0.015514892, 0.0011946067, -0.01816735, 0.010876419, -0.10124666, -0.03550831, 0.0056348112, 0.013942076, 0.005951374, 0.020419942, -0.006857742, -0.020873128, -0.021259667, 0.0137554705, 0.0057880944, -0.029163731, -0.018767154, -0.021392956, 0.030896494, -0.005494857, -0.0027307675, -0.006801094, -0.014821786, 0.021392956, -0.0018110704, -0.0018843795, -0.012362596, -0.0072176233, -0.017194338, -0.018713837, -0.024272008, 0.03801415, 0.00015880188, 0.0044951867, -0.028630573, -0.0014070367, -0.00916365, -0.026537929, -0.009576847, -0.013995391, -0.0077107945, 0.0050016865, 0.00578143, -0.04467862, 0.008363913, 0.010136662, -0.0006268769, -0.006591163, 0.015341615, -0.027377652, -0.00093136, 0.029243704, -0.020886457, -0.01041657, -0.02424535, 0.005291591, -0.02980352, -0.009190307, 0.019460259, -0.0041286405, 0.004801752, 0.0011787785, -0.001257086, -0.011216307, -0.013395589, 0.00088137644, -0.0051616337, 0.03876057, -0.0033455652, 0.00075850025, -0.006951045, -0.0062112883, 0.018140694, -0.006351242, -0.008263946, 0.018154023, -0.012189319, 0.0075508473, -0.044358727, -0.0040153447, 0.0093302615, -0.010636497, 0.032789204, -0.005264933, -0.014235313, -0.018393943, 0.007297597, -0.016114693, 0.015021721, 0.020033404, 0.0137688, 0.0011046362, 0.010616505, -0.0039453674, 0.012109346, 0.021099718, -0.0072842683, -0.019153694, -0.003768759, 0.039320387, -0.006747778, -0.0016852784, 0.018154023, 0.0010963057, -0.015035049, -0.021033075, -0.04345236, 0.017287642, 0.016341286, -0.008610498, 0.00236922, 0.009290274, 0.028950468, -0.014475234, -0.0035654926, 0.015434918, -0.03372223, 0.004501851, -0.012929076, -0.008483873, -0.0044685286, -0.0102233, 0.01615468, 0.0022792495, 0.010876419, -0.0059647025, 0.01895376, -0.0069976957, -0.0042952523, 0.017207667, -0.00036133936, 0.0085905045, 0.008084005, 0.03129636, -0.016994404, -0.014915089, 0.020100048, -0.012009379, -0.006684466, 0.01306903, 0.00015765642, -0.00530492, 0.0005277429, 0.015421589, 0.015528221, 0.032202728, -0.003485519, -0.0014286962, 0.033908837, 0.001367883, 0.010509873, 0.025271678, -0.020993087, 0.019846799, 0.006897729, -0.010216636, -0.00725761, 0.01818068, -0.028443968, -0.011242964, -0.014435247, -0.013688826, 0.006101324, -0.0022509254, 0.013848773, -0.0019077052, 0.017181009, 0.03422873, 0.005324913, -0.0035188415, 0.014128681, -0.004898387, 0.005038341, 0.0012320944, -0.005561502, -0.017847456, 0.0008538855, -0.0047884234, 0.011849431, 0.015421589, -0.013942076, 0.0029790192, -0.013702155, 0.0001199605, -0.024431955, 0.019926772, 0.022179363, -0.016487904, -0.03964028, 0.0050849924, 0.017487574, 0.022792496, 0.0012504216, 0.004048667, -0.00997005, 0.0076041627, -0.014328616, -0.020259995, 0.0005598157, -0.010469886, 0.0016852784, 0.01716768, -0.008990373, -0.001987679, 0.026417969, 0.023792166, 0.0046917885, -0.0071909656, -0.00032051947, -0.023259008, -0.009170313, 0.02071318, -0.03156294, -0.030869836, -0.006324584, 0.013795458, -0.00047151142, 0.016874444, 0.00947688, 0.00985009, -0.029883493, 0.024205362, -0.013522214, -0.015075036, -0.030603256, 0.029270362, 0.010503208, 0.021539574, 0.01743426, -0.023898797, 0.022019416, -0.0068777353, 0.027857494, -0.021259667, 0.0025758184, 0.006197959, 0.006447877, -0.00025200035, -0.004941706, -0.021246338, -0.005504854, -0.008390571, -0.0097301295, 0.027244363, -0.04446536, 0.05216949, 0.010243294, -0.016008062, 0.0122493, -0.0199401, 0.009077012, 0.019753495, 0.006431216, -0.037960835, -0.027377652, 0.016381273, -0.0038620618, 0.022512587, -0.010996379, -0.0015211658, -0.0102233, 0.007071005, 0.008230623, -0.009490209, -0.010083347, 0.024431955, 0.002427534, 0.02828402, 0.0035721571, -0.022192692, -0.011882754, 0.010056688, 0.0011904413, -0.01426197, -0.017500903, -0.00010985966, 0.005591492, -0.0077707744, -0.012049366, 0.011869425, 0.00858384, -0.024698535, -0.030283362, 0.020140035, 0.011949399, -0.013968734, 0.042732596, -0.011649498, -0.011982721, -0.016967745, -0.0060913274, -0.007130985, -0.013109017, -0.009710136 }; + + var options = new VectorSearchOptions() + { + IndexName = "vector_index", + NumberOfCandidates = 150 + }; + + // run query + var results = embeddedMovieCollection + .Aggregate() + .VectorSearch(movie => movie.PlotEmbedding, vector, 10, options) + .Project(Builders.Projection + .Include(movie => movie.Title) + .Include(movie => movie.Plot) + .MetaVectorSearchScore(m => m.Score)) + .ToList(); + + // end metaVectorSearchScore + + return results; + } +} \ No newline at end of file diff --git a/source/includes/code-examples/projection/Movie.cs b/source/includes/code-examples/projection/Movie.cs new file mode 100644 index 00000000..e9280675 --- /dev/null +++ b/source/includes/code-examples/projection/Movie.cs @@ -0,0 +1,27 @@ +public class Movie +{ + public ObjectId Id { get; set; } + + public string Title { get; set; } + + public List Genres { get; set; } + + public string Type { get; set; } + + public string Plot { get; set; } + + public List Highlights { get; set; } + + public string Score { get; set; } + + [BsonElement("scoreDetails")] + public SearchScoreDetails ScoreDetails { get; set; } + + [BsonElement("paginationToken")] + public string PaginationToken { get; set; } + + public List Cast { get; set; } + + [BsonElement("plot_embedding")] + public float[] PlotEmbedding { get; set; } +} \ No newline at end of file diff --git a/source/includes/code-examples/projection/SliceExamples.cs b/source/includes/code-examples/projection/SliceExamples.cs new file mode 100644 index 00000000..b190a5a9 --- /dev/null +++ b/source/includes/code-examples/projection/SliceExamples.cs @@ -0,0 +1,67 @@ +using MongoDB.Bson; +using MongoDB.Driver; + +namespace Projection; + +public class SliceExamples +{ + static string _uri = ""; + + static IMongoCollection movieCollection = new MongoClient(_uri) + .GetDatabase("sample_mflix") + .GetCollection("movies"); + + public static List FirstThreeExample() + { + // start first three + var filter = Builders.Filter.Text("future"); + var projection = Builders + .Projection + .Slice(m => m.Cast, 3) + .Include(m => m.Cast); + + var results = movieCollection.Find(filter) + .Project(projection) + .Limit(1) + .ToList(); + // end first three + + return results; + } + + public static List LastThreeExample() + { + // start last three + var filter = Builders.Filter.Text("future"); + var projection = Builders + .Projection + .Slice(m => m.Cast, -3) + .Include(m => m.Title); + + var results = movieCollection.Find(filter) + .Project(projection) + .Limit(1) + .ToList(); + // end last three + + return results; + } + + public static List SkipFirstLimitThreeExample() + { + // start skip first limit three + var filter = Builders.Filter.Text("future"); + var projection = Builders + .Projection + .Slice(m => m.Cast, 1, 3) + .Include(m => m.Title); + + var results = movieCollection.Find(filter) + .Project(projection) + .Limit(1) + .ToList(); + // end skip first limit three + + return results; + } +} \ No newline at end of file diff --git a/source/includes/project/atlas-only-note.rst b/source/includes/project/atlas-only-note.rst new file mode 100644 index 00000000..c44681f7 --- /dev/null +++ b/source/includes/project/atlas-only-note.rst @@ -0,0 +1,3 @@ +.. note:: Atlas Search Only + + This method is available only when projecting the results of an Atlas Search. \ No newline at end of file From 01c89a66f6c90238b6e75455eabed11125908157 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Wed, 4 Jun 2025 15:40:32 -0500 Subject: [PATCH 02/11] add missing file --- source/includes/vector-search-intro.rst | 106 ++++++++++++++++++++++++ 1 file changed, 106 insertions(+) create mode 100644 source/includes/vector-search-intro.rst diff --git a/source/includes/vector-search-intro.rst b/source/includes/vector-search-intro.rst new file mode 100644 index 00000000..c930af0b --- /dev/null +++ b/source/includes/vector-search-intro.rst @@ -0,0 +1,106 @@ +The ``$vectorSearch`` aggregation stage performs an *approximate nearest neighbor* search +on a vector in the specified field. Your collection *must* have a +defined Atlas Vector Search index before you can perform a vector search on your data. + +.. tip:: + + To obtain the sample dataset used in the following example, see :ref:`csharp-quickstart`. + To create the sample Atlas Vector Search index used in the following example, see + :atlas:`Create an Atlas Vector Search Index ` in the + Atlas manual. + +To create a ``$vectorSearch`` pipeline stage, call the ``VectorSearch()`` method on a +``PipelineStageDefinitionBuilder`` object. The ``VectorSearch()`` method accepts the +following parameters: + +.. list-table:: + :header-rows: 1 + :widths: 20 80 + + * - Parameter + - Description + + * - ``field`` + - The field to perform the vector search on. + + **Data type**: ``Expression>`` + + * - ``queryVector`` + - The encoded vector that will be matched with values from the database. + Although the data type of this parameter is ``QueryVector``, you can also pass an + array of ``float`` values. + + **Data type**: `QueryVector <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.QueryVector.html>`__ + + * - ``limit`` + - The maximum number of documents to return. + + **Data type**: {+int-data-type+} + + * - ``options`` + - Configuration options for the vector search operation. + + **Data type**: `VectorSearchOptions <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.VectorSearchOptions-1.html>`__ + +You can use the ``options`` parameter to configure your vector search operation. The +``VectorSearchOptions`` class contains the following properties: + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + + * - Property + - Description + + * - ``Exact`` + - Whether the vector search uses the exact nearest neighbor (ENN) algorithm. + If this property is set to ``false``, the vector search uses the approximate nearest + neighbor (ANN) algorithm. If this property is set to ``true``, the + ``NumberOfCandidates`` property must be ``null``. + + | **Data type**: {+bool-data-type+} + | **Default**: ``false`` + + * - ``Filter`` + - Additional search criteria that the found documents must match. + + | **Data Type:** `FilterDefinition <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.FilterDefinition-1.html>`__ + | **Default**: ``null`` + + * - ``IndexName`` + - The index to perform the vector search on. + + | **Data type**: {+string-data-type+} + | **Default**: ``null`` + + * - ``NumberOfCandidates`` + - The number of neighbors to search in the index. + + | **Data type**: ``int?`` + | **Default**: ``null`` + +Consider the ``embedded_movies`` collection in the ``sample_mflix`` database. +The following ``EmbeddedMovie`` class represents a document in this database: + +.. code-block:: csharp + + public class EmbeddedMovie + { + [BsonElement("title")] + public string Title { get; set; } + + [BsonElement("plot_embedding")] + public double[] Embedding { get; set; } + + [BsonElement("score")] + public double Score { get; set; } + } + +You can use a ``$vectorSearch`` stage to perform a semantic search on the ``plot_embedding`` +field of the documents in the collection. +The following example shows how to use |mechanism| to generate an aggregation pipeline to +perform the following operations: + +- Perform a vector search on the Atlas Vector Search index of the ``plot_embedding`` + field by using vector embeddings for the string ``"time travel"`` +- Fetch the ``Title`` and ``Plot`` fields from documents found in the vector search \ No newline at end of file From 6c63bd6ec55e1397ce33376fd1dcf9b4a9bbf1de Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Wed, 4 Jun 2025 15:43:20 -0500 Subject: [PATCH 03/11] build fixes --- source/aggregation.txt | 1 + source/aggregation/linq.txt | 4 ++-- source/aggregation/stages.txt | 1 - 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/source/aggregation.txt b/source/aggregation.txt index 037ec1a5..10d1a7b6 100644 --- a/source/aggregation.txt +++ b/source/aggregation.txt @@ -22,6 +22,7 @@ Aggregation Operations :maxdepth: 1 Pipeline Stages + LINQ Overview -------- diff --git a/source/aggregation/linq.txt b/source/aggregation/linq.txt index 73fc6053..0218fea2 100644 --- a/source/aggregation/linq.txt +++ b/source/aggregation/linq.txt @@ -36,7 +36,7 @@ The {+driver-short+} automatically translates LINQ queries into The examples in this guide use the ``restaurants`` collection in the ``sample_restaurants`` database provided in the :atlas:`Atlas sample datasets `. To learn how to create a free MongoDB Atlas cluster and load the sample datasets, -see the :ref:``. +see :ref:``. The following ``Restaurant``, ``Address`` and ``GradeEntry`` classes model the documents in this collection: @@ -1025,7 +1025,7 @@ aggregation stages: - ``$out`` To learn how to create an aggregation pipeline with the ``$out`` stage by using Builders, see -the :ref:`` section. +:ref:``. Supported Methods ----------------- diff --git a/source/aggregation/stages.txt b/source/aggregation/stages.txt index 673d84b4..482f92dd 100644 --- a/source/aggregation/stages.txt +++ b/source/aggregation/stages.txt @@ -1,6 +1,5 @@ .. _csharp-aggregation-stages: .. _csharp-builders-aggregation: -.. _csharp-linq: =========================== Aggregation Pipeline Stages From 6db627671173db1181ff1b2f01f88e533fe58a66 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Wed, 4 Jun 2025 15:52:17 -0500 Subject: [PATCH 04/11] build fix --- source/includes/vector-search-intro.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/includes/vector-search-intro.rst b/source/includes/vector-search-intro.rst index c930af0b..c380225d 100644 --- a/source/includes/vector-search-intro.rst +++ b/source/includes/vector-search-intro.rst @@ -4,7 +4,7 @@ defined Atlas Vector Search index before you can perform a vector search on your .. tip:: - To obtain the sample dataset used in the following example, see :ref:`csharp-quickstart`. + To obtain the sample dataset used in the following example, see :ref:`csharp-get-started`. To create the sample Atlas Vector Search index used in the following example, see :atlas:`Create an Atlas Vector Search Index ` in the Atlas manual. From f07726ce6494ddd808bc3af4b373897949ae7c0b Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Wed, 4 Jun 2025 21:03:17 -0500 Subject: [PATCH 05/11] add output examples --- source/crud/query/project.txt | 339 +++++++++++++++++++++++----------- 1 file changed, 231 insertions(+), 108 deletions(-) diff --git a/source/crud/query/project.txt b/source/crud/query/project.txt index dd160420..8b60342c 100644 --- a/source/crud/query/project.txt +++ b/source/crud/query/project.txt @@ -13,7 +13,7 @@ Specify Fields To Return .. facet:: :name: genre :values: reference - + .. meta:: :keywords: read, filter, project, select @@ -34,17 +34,18 @@ free MongoDB Atlas cluster and load the sample datasets, see the :ref:`.Projection`` static property to create a - ``ProjectionDefinitionBuilder object. The ``ProjectionDefinitionBuilder`` class - provides a type-safe interface for defining a projection.``TDocument`` represents the + ``ProjectionDefinitionBuilder`` object. The ``ProjectionDefinitionBuilder`` class + provides a type-safe interface for defining a projection. ``TDocument`` represents the C# class that the collection's documents map to. #. Chain projection methods from the ``ProjectionDefinitionBuilder`` @@ -58,6 +59,12 @@ To create a projection, perform the following steps: The following sections describe the methods that you can chain from your ``ProjectionDefinitionBuilder`` object. +Field Projection Methods +------------------------ + +The following methods let you specify which fields to include or exclude from the returned +documents. + ElemMatch ~~~~~~~~~ @@ -112,6 +119,102 @@ This is equivalent to including a field in the ``$project`` aggregation stage in For a code example that uses the ``Include()`` method, see :manual:`$project ` in the {+mdb-server+} manual. +Slice +~~~~~ + +The ``Slice()`` method specifies the number of elements in an array to return in the query +result. This is equivalent to using the ``$slice`` operator in the {+query-api+}. + +The following code example uses the ``Slice()`` method to return the first three elements +of the ``cast`` array in the returned document: + +.. io-code-block:: + + .. input:: /includes/code-examples/projection/SliceExamples.cs + :language: csharp + :dedent: 8 + :start-after: // start first three + :end-before: // end first three + + .. output:: + :language: json + + { + "_id": { + "$oid": "573a1398f29313caabceb500" + }, + "title": "Back to the Future Part II", + "cast": [ + "Michael J. Fox", + "Christopher Lloyd", + "Lea Thompson" + ] + } + +To return elements from the end of an array, pass a negative integer to the ``Slice()`` +method. The method returns the specified number of elements from the end of the array. +The following code example returns the last three elements of the ``cast`` array in the +returned document: + +.. io-code-block:: + + .. input:: /includes/code-examples/projection/SliceExamples.cs + :language: csharp + :dedent: 8 + :start-after: // start last three + :end-before: // end last three + + .. output:: + :language: json + + { + "_id": { + "$oid": "573a1398f29313caabceb500" + }, + "title": "Back to the Future Part II", + "cast": [ + "Lea Thompson", + "Thomas F. Wilson" + ] + } + +To skip a specified number of elements in the array, pass the number of elements to skip +as the first parameter and the number of elements to return as the second +parameter. The following code example skips the first element in the +``cast`` array and returns the next three elements: + +.. io-code-block:: + + .. input:: /includes/code-examples/projection/SliceExamples.cs + :language: csharp + :dedent: 8 + :start-after: // start skip first limit three + :end-before: // end skip first limit three + + .. output:: + :language: json + + { + "_id": { + "$oid": "573a1398f29313caabceb500" + }, + "title": "Back to the Future Part II", + "cast": [ + "Christopher Lloyd", + "Lea Thompson", + "Thomas F. Wilson" + ] + } + +To learn more about the ``$slice`` operator, see +:manual:`$slice ` in the {+mdb-server+} manual. + +Metadata Projection Methods +--------------------------- + +The following methods let you specify which metadata fields to include or exclude +from the returned documents. Metadata fields are hidden by default. + Meta ~~~~ @@ -120,13 +223,27 @@ documents. This is equivalent to including a metadata field by using the :manual:`$meta ` operator in the {+query-api+}. The following code example adds the ``textScore`` metadata field to the returned -documents as a field named ``searchScore``: +documents as a field named ``score``: -.. literalinclude:: /includes/code-examples/projection/MetaExamples.cs - :language: csharp - :dedent: 8 - :start-after: start meta - :end-before: end meta +.. io-code-block:: + + .. input:: /includes/code-examples/projection/MetaExamples.cs + :language: csharp + :dedent: 8 + :start-after: // start meta + :end-before: // end meta + + .. output:: + :language: json + + { + "_id": { + "$oid": "..." + }, + "plot": "...", + "title": "...", + "score": "..." + } MetaSearchHighlights ~~~~~~~~~~~~~~~~~~~~ @@ -142,11 +259,44 @@ specifies the search field, and then pass this object to the ``Search()`` method The following code example retrieves search highlights for the ``plot`` field, then includes these highlights in a property named ``Highlights`` in the returned documents: -.. literalinclude:: /includes/code-examples/projection/MetaExamples.cs - :language: csharp - :dedent: 8 - :start-after: start metaSearchHighlights - :end-before: end metaSearchHighlights +.. io-code-block:: + + .. input:: /includes/code-examples/projection/MetaExamples.cs + :language: csharp + :dedent: 8 + :start-after: // start metaSearchHighlights + :end-before: // end metaSearchHighlights + + .. output:: + :language: json + + { + "_id": { + "$oid": "573a13def29313caabdb5661" + }, + "plot": "She Can See Her Future, But Can't Escape Her Past.", + "title": "West", + "highlights": [ + { + "score": 1.286744475364685, + "path": "plot", + "texts": [ + { + "value": "She Can See Her ", + "type": "text" + }, + { + "value": "Future", + "type": "hit" + }, + { + "value": ", But Can't Escape Her Past.", + "type": "text" + } + ] + } + ] + } To learn more about search highlights, see :atlas:`Highlight Search Terms in Results ` @@ -164,11 +314,25 @@ by using a ``{ "$meta": "searchScore" }`` object in the {+query-api+}. The following code example projects each document's search score in a property named ``Score``: -.. literalinclude:: /includes/code-examples/projection/MetaExamples.cs - :language: csharp - :dedent: 8 - :start-after: start metaSearchScore - :end-before: end metaSearchScore +.. io-code-block:: + + .. input:: /includes/code-examples/projection/MetaExamples.cs + :language: csharp + :dedent: 8 + :start-after: // start metaSearchScore + :end-before: // end metaSearchScore + + .. output:: + :language: json + + { + "_id": { + "$oid": "573a13def29313caabdb5661" + }, + "plot": "She Can See Her Future, But Can't Escape Her Past.", + "title": "West", + "score": 2.8259084224700928 + } To learn more about search scores, see :atlas:`Score the Documents in the Returned Documents `. @@ -187,11 +351,32 @@ To retrieve score details, you must create a ``SearchOptions`` object that, set The following code example shows this process by projecting each document's search score details in a property named ``ScoreDetails``: -.. literalinclude:: /includes/code-examples/projection/MetaExamples.cs - :language: csharp - :dedent: 8 - :start-after: start metaSearchScoreDetails - :end-before: end metaSearchScoreDetails +.. io-code-block:: + + .. input:: /includes/code-examples/projection/MetaExamples.cs + :language: csharp + :dedent: 8 + :start-after: // start metaSearchScoreDetails + :end-before: // end metaSearchScoreDetails + + .. output:: + :language: json + + { + "_id": { + "$oid": "573a13def29313caabdb5661" + }, + ... + "scoreDetails": { + "value": 2.8259084224700928, + "description": "$type:string/plot:future [BM25Similarity], result of:", + "details": [ + { + "value": 2.8259084224700928, + "description": "score(freq=1.0), computed as boost * idf * tf from:", + "details": [ + ... + } To learn more about search score details, see :atlas:`Return the Score Details ` @@ -211,11 +396,25 @@ specified point. The following code example projects each document's search sequence token in a property named ``PaginationToken``: -.. literalinclude:: /includes/code-examples/projection/MetaExamples.cs - :language: csharp - :dedent: 8 - :start-after: start metaSearchSequenceToken - :end-before: end metaSearchSequenceToken +.. io-code-block:: + + .. input:: /includes/code-examples/projection/MetaExamples.cs + :language: csharp + :dedent: 8 + :start-after: // start metaSearchSequenceToken + :end-before: // end metaSearchSequenceToken + + .. output:: + :language: json + + { + "_id": { + "$oid": "573a13def29313caabdb5661" + }, + "plot": "She Can See Her Future, But Can't Escape Her Past.", + "title": "West", + "paginationToken": "CIeaARWv2zRAIg5aDFc6E97ykxPKq9tWYQ==" + } To learn more about search sequence tokens, see :atlas:`Paginate Search Results ` @@ -228,7 +427,7 @@ This is equivalent to projecting the text search score by using a ``{ "$meta": "textScore" }`` object in the {+query-api+}. For a code example that uses the ``MetaTextScore()`` method, see -:manual:`$meta ` +:manual:`$meta ` in the {+mdb-server+} manual. MetaVectorSearchScore @@ -269,82 +468,6 @@ documentation: - :atlas:`$searchMeta ` - :atlas:`$search with $$SEARCH_META ` -Slice -~~~~~ - -The ``Slice()`` method specifies the number of elements in an array to return in the query -result. This is equivalent to using the ``$slice`` operator in the {+query-api+}. - -The following code example uses the ``Slice()`` method to return the first three elements -of the ``cast`` array in the returned document: - -.. io-code-block:: - - .. input:: - :language: csharp - - .. literalinclude:: /includes/code-examples/projection/SliceExamples.cs - :language: csharp - :dedent: 8 - :start-after: // start first three - :end-before: // end first three - - .. output:: - :language: json - - { "_id" : { "$oid" : "573a1398f29313caabceb500" }, - "title" : "Back to the Future Part II", - "cast" : ["Michael J. Fox", "Christopher Lloyd", "Lea Thompson"] } - -To return elements from the end of an array, pass a negative integer to the ``Slice()`` -method. The method returns the specified number of elements from the end of the array. -The following code example returns the last three elements of the ``cast`` array in the -returned document: - -.. io-code-block:: - - .. input:: - :language: csharp - - .. literalinclude:: /includes/code-examples/projection/SliceExamples.cs - :language: csharp - :dedent: 8 - :start-after: // start last three - :end-before: // end last three - - .. output:: - :language: json - - { "_id" : { "$oid" : "573a1398f29313caabceb500" }, - "title" : "Back to the Future Part II", - "cast" : ["Lea Thompson", "Thomas F. Wilson"] } - -To skip a specified number of elements in the array, pass the number of elements to skip -as the first parameter and the number of elements to return as the second -parameter. The following code example skips the first element in the -``cast`` array and returns the next three elements: - -.. io-code-block:: - - .. input:: - :language: csharp - - .. literalinclude:: /includes/code-examples/projection/SliceExamples.cs - :language: csharp - :dedent: 8 - :start-after: // start skip first limit three - :end-before: // end skip first limit three - - .. output:: - :language: json - - { "_id" : { "$oid" : "573a1398f29313caabceb500" }, - "title" : "Back to the Future Part II", - "cast" : ["Christopher Lloyd", "Lea Thompson", "Thomas F. Wilson"] } - -To learn more about the ``$slice`` operator, see -:manual:`$slice ` in the {+mdb-server+} manual. - API Documentation ----------------- From a027cd1faaadaaaff78bc0112b2281a238818196 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Wed, 4 Jun 2025 21:06:19 -0500 Subject: [PATCH 06/11] update code file --- .../code-examples/projection/MetaExamples.cs | 42 ++++++++++--------- 1 file changed, 22 insertions(+), 20 deletions(-) diff --git a/source/includes/code-examples/projection/MetaExamples.cs b/source/includes/code-examples/projection/MetaExamples.cs index 41063c8f..18b11e2a 100644 --- a/source/includes/code-examples/projection/MetaExamples.cs +++ b/source/includes/code-examples/projection/MetaExamples.cs @@ -16,20 +16,14 @@ public class MetaExamples .GetDatabase("sample_mflix") .GetCollection("embedded_movies"); - public static void CreateIndex() - { - // start createIndex - var indexModel = new CreateIndexModel( - Builders.IndexKeys.Text(m => m.Title)); - movieCollection.Indexes.CreateOne(indexModel); - // end createIndex - } - public static List MetaTextScoreExample() { // start metaTextScore var filter = Builders.Filter.Text("future"); - var projection = Builders.Projection.MetaTextScore("score"); + var projection = Builders.Projection + .Include(m => m.Title) + .Include(m => m.Plot) + .MetaTextScore("score"); var results = movieCollection.Find(filter) .Project(projection) @@ -44,9 +38,10 @@ public static List MetaExample() { // start meta var filter = Builders.Filter.Text("future"); - var projection = Builders.Projection.Meta( - field: "searchScore", - metaFieldName: "textScore"); + var projection = Builders.Projection + .Include(m => m.Title) + .Include(m => m.Plot) + .Meta(field: "score", metaFieldName: "textScore"); var results = movieCollection.Find(filter) .Project(projection) @@ -61,7 +56,10 @@ public static List MetaScoreExample() { // start metaScore var filter = Builders.Search.Text(m => m.Title, "future"); - var projection = Builders.Projection.MetaScore("scoreDetails"); + var projection = Builders.Projection + .Include(m => m.Title) + .Include(m => m.Plot) + .MetaScore(m => m.ScoreDetails); var results = movieCollection .Aggregate() @@ -78,7 +76,10 @@ public static List MetaScoreDetailsExample() { // start metaScoreDetails var filter = Builders.Filter.Text("future"); - var projection = Builders.Projection.MetaScoreDetails("detailsOfTheScore"); + var projection = Builders.Projection + .Include(m => m.Title) + .Include(m => m.Plot) + .MetaScoreDetails(m => m.ScoreDetails); var results = movieCollection.Find(filter) .Project(projection) @@ -92,8 +93,10 @@ public static List MetaScoreDetailsExample() public static List MetaSearchHighlightsExample() { // start metaSearchHighlights - var filter = Builders.Search.Phrase(m => m.Plot, "future"); + var filter = Builders.Search.Text(path: m => m.Plot, query: "future"); var projection = Builders.Projection + .Include(m => m.Title) + .Include(m => m.Plot) .MetaSearchHighlights(m => m.Highlights); var results = movieCollection @@ -110,7 +113,7 @@ public static List MetaSearchHighlightsExample() public static List MetaSearchScoreExample() { // start metaSearchScore - var filter = Builders.Search.Phrase(m => m.Plot, "future"); + var filter = Builders.Search.Text(m => m.Plot, "future"); var projection = Builders.Projection .Include(m => m.Title) .Include(m => m.Plot) @@ -130,7 +133,7 @@ public static List MetaSearchScoreExample() public static List MetaSearchScoreDetailsExample() { // start metaSearchScoreDetails - var filter = Builders.Search.Phrase(m => m.Plot, "future"); + var filter = Builders.Search.Text(m => m.Plot, "future"); var projection = Builders.Projection .Include(m => m.Title) .Include(m => m.Plot) @@ -151,7 +154,7 @@ public static List MetaSearchScoreDetailsExample() public static List MetaSearchSequenceTokenExample() { // start metaSearchSequenceToken - var filter = Builders.Search.Phrase(m => m.Plot, "future"); + var filter = Builders.Search.Text(m => m.Plot, "future"); var projection = Builders.Projection .Include(m => m.Title) .Include(m => m.Plot) @@ -188,7 +191,6 @@ public static List MetaVectorSearchScoreExample() .Include(movie => movie.Plot) .MetaVectorSearchScore(m => m.Score)) .ToList(); - // end metaVectorSearchScore return results; From 3bc0624473940245b76bc0920ea37fb9ab17ccce Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Wed, 4 Jun 2025 21:16:14 -0500 Subject: [PATCH 07/11] hide output --- source/crud/query/project.txt | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/source/crud/query/project.txt b/source/crud/query/project.txt index 8b60342c..47629391 100644 --- a/source/crud/query/project.txt +++ b/source/crud/query/project.txt @@ -137,6 +137,7 @@ of the ``cast`` array in the returned document: :end-before: // end first three .. output:: + :visible: false :language: json { @@ -165,6 +166,7 @@ returned document: :end-before: // end last three .. output:: + :visible: false :language: json { @@ -192,6 +194,7 @@ parameter. The following code example skips the first element in the :end-before: // end skip first limit three .. output:: + :visible: false :language: json { @@ -234,6 +237,7 @@ documents as a field named ``score``: :end-before: // end meta .. output:: + :visible: false :language: json { @@ -268,6 +272,7 @@ includes these highlights in a property named ``Highlights`` in the returned doc :end-before: // end metaSearchHighlights .. output:: + :visible: false :language: json { @@ -323,6 +328,7 @@ The following code example projects each document's search score in a property n :end-before: // end metaSearchScore .. output:: + :visible: false :language: json { @@ -360,6 +366,7 @@ details in a property named ``ScoreDetails``: :end-before: // end metaSearchScoreDetails .. output:: + :visible: false :language: json { @@ -405,6 +412,7 @@ named ``PaginationToken``: :end-before: // end metaSearchSequenceToken .. output:: + :visible: false :language: json { From 091cdb624602aaa1c335f0fb9ba16432cf829bbf Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Fri, 6 Jun 2025 10:37:04 -0500 Subject: [PATCH 08/11] rm feedback --- source/crud/query/project.txt | 33 +++++++++---------- .../code-examples/projection/MetaExamples.cs | 2 +- .../code-examples/projection/Movie.cs | 3 ++ 3 files changed, 20 insertions(+), 18 deletions(-) diff --git a/source/crud/query/project.txt b/source/crud/query/project.txt index 47629391..c1808682 100644 --- a/source/crud/query/project.txt +++ b/source/crud/query/project.txt @@ -44,9 +44,9 @@ Create a Projection To create a projection, perform the following steps: 1. Use the ``Builders.Projection`` static property to create a - ``ProjectionDefinitionBuilder`` object. The ``ProjectionDefinitionBuilder`` class - provides a type-safe interface for defining a projection. ``TDocument`` represents the - C# class that the collection's documents map to. + ``ProjectionDefinitionBuilder`` object, where ``TDocument`` represents the + C# class that the collection's documents map to. The ``ProjectionDefinitionBuilder`` class + provides a type-safe interface for defining a projection. #. Chain projection methods from the ``ProjectionDefinitionBuilder`` object to specify which fields to include or exclude from the returned documents. @@ -122,11 +122,11 @@ For a code example that uses the ``Include()`` method, see Slice ~~~~~ -The ``Slice()`` method specifies the number of elements in an array to return in the query -result. This is equivalent to using the ``$slice`` operator in the {+query-api+}. +The ``Slice()`` method specifies the number of elements of a list or array to return in the query +result field. This is equivalent to using the ``$slice`` operator in the {+query-api+}. The following code example uses the ``Slice()`` method to return the first three elements -of the ``cast`` array in the returned document: +of the ``Cast`` list in the returned document's ``cast`` array: .. io-code-block:: @@ -152,10 +152,9 @@ of the ``cast`` array in the returned document: ] } -To return elements from the end of an array, pass a negative integer to the ``Slice()`` -method. The method returns the specified number of elements from the end of the array. -The following code example returns the last three elements of the ``cast`` array in the -returned document: +To return elements from the end of a collection, pass a negative integer to the ``Slice()`` +method. The following code example returns the last three elements of the ``Cast`` list in +the returned document's ``cast`` array: .. io-code-block:: @@ -180,10 +179,10 @@ returned document: ] } -To skip a specified number of elements in the array, pass the number of elements to skip +To skip a specified number of elements in a collection, pass the number of elements to skip as the first parameter and the number of elements to return as the second parameter. The following code example skips the first element in the -``cast`` array and returns the next three elements: +``Cast`` list and returns the next three elements in the ``cast`` array: .. io-code-block:: @@ -316,8 +315,8 @@ The ``MetaSearchScore()`` method includes search scores in the returned documents. This is equivalent to projecting search scores by using a ``{ "$meta": "searchScore" }`` object in the {+query-api+}. -The following code example projects each document's search score in a property named -``Score``: +The following code example projects each document's search score in a field named +``score``: .. io-code-block:: @@ -352,10 +351,10 @@ The ``MetaSearchScoreDetails()`` includes details about the search scores in the returned documents. This is equivalent to projecting search score details by using a ``{ "$meta": "searchScoreDetails" }`` object in the {+query-api+}. -To retrieve score details, you must create a ``SearchOptions`` object that, set its -``ScoreDetails`` property to ``true``, and then pass this object to the ``Search()`` method. +To retrieve score details, create a ``SearchOptions`` object with its +``ScoreDetails`` property set to ``true``, and then pass this object to the ``Search()`` method. The following code example shows this process by projecting each document's search score -details in a property named ``ScoreDetails``: +details in a field named ``searchScoreDetails``: .. io-code-block:: diff --git a/source/includes/code-examples/projection/MetaExamples.cs b/source/includes/code-examples/projection/MetaExamples.cs index 18b11e2a..12253454 100644 --- a/source/includes/code-examples/projection/MetaExamples.cs +++ b/source/includes/code-examples/projection/MetaExamples.cs @@ -138,7 +138,7 @@ public static List MetaSearchScoreDetailsExample() .Include(m => m.Title) .Include(m => m.Plot) .MetaSearchScore(m => m.Score) - .MetaSearchScoreDetails(m => m.ScoreDetails); + .MetaSearchScoreDetails(m => m.SearchScoreDetails); var results = movieCollection .Aggregate() diff --git a/source/includes/code-examples/projection/Movie.cs b/source/includes/code-examples/projection/Movie.cs index e9280675..8cc8046f 100644 --- a/source/includes/code-examples/projection/Movie.cs +++ b/source/includes/code-examples/projection/Movie.cs @@ -17,6 +17,9 @@ public class Movie [BsonElement("scoreDetails")] public SearchScoreDetails ScoreDetails { get; set; } + [BsonElement("searchScoreDetails")] + public SearchScoreDetails SearchScoreDetails { get; set; } + [BsonElement("paginationToken")] public string PaginationToken { get; set; } From 6220d9edccba7bc7d003aa254043711bc1b1444f Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Fri, 6 Jun 2025 10:37:33 -0500 Subject: [PATCH 09/11] rm feedback --- source/atlas-vector-search.txt | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/source/atlas-vector-search.txt b/source/atlas-vector-search.txt index 3f861338..cef66072 100644 --- a/source/atlas-vector-search.txt +++ b/source/atlas-vector-search.txt @@ -86,15 +86,15 @@ The results of the preceding example contain the following documents: .. code-block:: json { "_id" : { "$oid" : "573a13a0f29313caabd04a4f" }, "plot" : "A reporter, learning of time travelers visiting 20th century disasters, tries to change the history they know by averting upcoming disasters.", "title" : "Thrill Seekers", "score" : 0.926971435546875 } - { "_id" : { "$oid" : "573a13d8f29313caabda6557" }, "plot" : "At the age of 21, Tim discovers he can travel in time and change what happens and has happened in his own life. His decision to make his world a better place by getting a girlfriend turns out not to be as easy as you might think.", "title" : "About Time", "score" : 0. 9267120361328125 } - { "_id" : { "$oid" : "573a1399f29313caabceec0e" }, "plot" : "An officer for a security agency that regulates time travel, must fend for his life against a shady politician who has a tie to his past.", "title" : "Timecop", "score" : 0.9235687255859375 } - { "_id" : { "$oid" : "573a13a5f29313caabd13b4b" }, "plot" : "Hoping to alter the events of the past, a 19th century inventor instead travels 800,000 years into the future, where he finds humankind divided into two warring races.", "title" : "The Time Machine", "score" : 0.9228668212890625 } - { "_id" : { "$oid" : "573a13aef29313caabd2e2d7" }, "plot" : "After using his mother's newly built time machine, Dolf gets stuck involuntary in the year 1212. He ends up in a children's crusade where he confronts his new friends with modern techniques...", "title" : "Crusade in Jeans", "score" : 0.9228515625 } - { "_id" : { "$oid" : "573a1399f29313caabcee36f" }, "plot" : "A time-travel experiment in which a robot probe is sent from the year 2073 to the year 1973 goes terribly wrong thrusting one of the project scientists, a man named Nicholas Sinclair into a...", "title" : "A.P.E.X.", "score" : 0.9199066162109375 } - { "_id" : { "$oid" : "573a13c6f29313caabd715d3" }, "plot" : "Agent J travels in time to M.I.B.'s early days in 1969 to stop an alien from assassinating his friend Agent K and changing history.", "title" : "Men in Black 3", "score" : 0.919403076171875 } - { "_id" : { "$oid" : "573a13d4f29313caabd98c13" }, "plot" : "Bound by a shared destiny, a teen bursting with scientific curiosity and a former boy-genius inventor embark on a mission to unearth the secrets of a place somewhere in time and space that exists in their collective memory.", "title" : "Tomorrowland", "score" : 0. 9191131591796875 } - { "_id" : { "$oid" : "573a13b6f29313caabd477fa" }, "plot" : "With the help of his uncle, a man travels to the future to try and bring his girlfriend back to life.", "title" : "Love Story 2050", "score" : 0. 917755126953125 } - { "_id" : { "$oid" : "573a13b3f29313caabd3ebd4" }, "plot" : "A romantic drama about a Chicago librarian with a gene that causes him to involuntarily time travel, and the complications it creates for his marriage.", "title" : "The Time Traveler's Wife", "score" : 0.9172210693359375 } + { "_id" : { "$oid" : "573a13d8f29313caabda6557" }, "plot" : "At the age of 21, Tim discovers he can travel in time and change what happens and has happened in his own life. His decision to make his world a better place by getting a girlfriend turns out not to be as easy as you might think.", "title" : "About Time", "score" : 0. 9267120361328125 } + { "_id" : { "$oid" : "573a1399f29313caabceec0e" }, "plot" : "An officer for a security agency that regulates time travel, must fend for his life against a shady politician who has a tie to his past.", "title" : "Timecop", "score" : 0.9235687255859375 } + { "_id" : { "$oid" : "573a13a5f29313caabd13b4b" }, "plot" : "Hoping to alter the events of the past, a 19th century inventor instead travels 800,000 years into the future, where he finds humankind divided into two warring races.", "title" : "The Time Machine", "score" : 0.9228668212890625 } + { "_id" : { "$oid" : "573a13aef29313caabd2e2d7" }, "plot" : "After using his mother's newly built time machine, Dolf gets stuck involuntary in the year 1212. He ends up in a children's crusade where he confronts his new friends with modern techniques...", "title" : "Crusade in Jeans", "score" : 0.9228515625 } + { "_id" : { "$oid" : "573a1399f29313caabcee36f" }, "plot" : "A time-travel experiment in which a robot probe is sent from the year 2073 to the year 1973 goes terribly wrong thrusting one of the project scientists, a man named Nicholas Sinclair into a...", "title" : "A.P.E.X.", "score" : 0.9199066162109375 } + { "_id" : { "$oid" : "573a13c6f29313caabd715d3" }, "plot" : "Agent J travels in time to M.I.B.'s early days in 1969 to stop an alien from assassinating his friend Agent K and changing history.", "title" : "Men in Black 3", "score" : 0.919403076171875 } + { "_id" : { "$oid" : "573a13d4f29313caabd98c13" }, "plot" : "Bound by a shared destiny, a teen bursting with scientific curiosity and a former boy-genius inventor embark on a mission to unearth the secrets of a place somewhere in time and space that exists in their collective memory.", "title" : "Tomorrowland", "score" : 0.9191131591796875 } + { "_id" : { "$oid" : "573a13b6f29313caabd477fa" }, "plot" : "With the help of his uncle, a man travels to the future to try and bring his girlfriend back to life.", "title" : "Love Story 2050", "score" : 0. 917755126953125 } + { "_id" : { "$oid" : "573a13b3f29313caabd3ebd4" }, "plot" : "A romantic drama about a Chicago librarian with a gene that causes him to involuntarily time travel, and the complications it creates for his marriage.", "title" : "The Time Traveler's Wife", "score" : 0.9172210693359375 } To learn more about Atlas Vector Search, see :atlas:`Atlas Vector Search Overview ` in the Atlas manual. \ No newline at end of file From 809dd33494fccbc5e35e09230c2b5960aaaa1d24 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Fri, 6 Jun 2025 10:49:22 -0500 Subject: [PATCH 10/11] broken link --- source/serialization/poco.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/serialization/poco.txt b/source/serialization/poco.txt index 196249ad..09769147 100644 --- a/source/serialization/poco.txt +++ b/source/serialization/poco.txt @@ -675,7 +675,7 @@ serialization-related attributes: - ``[BsonDateTimeOptions(DateOnly = true)]``, which specifies that the ``DateTime`` property represents only a date value, with no associated time -.. literalinclude:: ../../includes/fundamentals/code-examples/Clothing.cs +.. literalinclude:: /includes/fundamentals/code-examples/Clothing.cs :start-after: start-model :end-before: end-model :language: csharp From 9cb131155ba237d8565d35fb9a038b4b5ec20b37 Mon Sep 17 00:00:00 2001 From: Mike Woofter <108414937+mongoKart@users.noreply.github.com> Date: Fri, 6 Jun 2025 10:54:21 -0500 Subject: [PATCH 11/11] build errors --- source/reference/quick-reference.txt | 2 +- source/serialization.txt | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/source/reference/quick-reference.txt b/source/reference/quick-reference.txt index 3e81573a..60cea226 100644 --- a/source/reference/quick-reference.txt +++ b/source/reference/quick-reference.txt @@ -528,7 +528,7 @@ their related reference and API documentation. * - | **Project Document Fields When Retrieving Them** | | `API Documentation <{+new-api-root+}/MongoDB.Driver/MongoDB.Driver.ProjectionDefinitionBuilder-1.html>`__ - | :ref:`Fundamentals ` + | :ref:`Fundamentals ` - .. io-code-block:: :copyable: true diff --git a/source/serialization.txt b/source/serialization.txt index f652628c..15e3253d 100644 --- a/source/serialization.txt +++ b/source/serialization.txt @@ -21,7 +21,7 @@ Serialization :caption: Custom Types Class Mapping - POCOs + POCOs Polymorphic Objects GUIDs