DOCSP-37545 Atlas Search Page

source/atlas-search.txt

@@ -0,0 +1,124 @@
+.. _pymongo-atlas-search:
+
+============
+Atlas Search
+============
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: search, atlas, read
+
+Overview
+--------
+
+In this guide, you can learn how to query an Atlas Search index and use advanced search 
+functionality in your {+driver-short+} applications. You can query a search index by 
+using a ``$search`` aggregation pipeline stage.
+
+To learn more about the ``$search`` pipeline stage, see the :manual:`$search
+</reference/operator/aggregation/search/>` guide in the {+mdb-server+} manual.
+
+.. note:: Only Available on Atlas for MongoDB v4.2 and Later
+
+   The ``$search`` aggregation-pipeline operator is available only for collections hosted
+   on :atlas:`MongoDB Atlas </>` clusters running MongoDB v4.2 or later that are
+   covered by an :atlas:`Atlas search index </reference/atlas-search/index-definitions/>`.
+   To learn more about the required setup and the functionality of this operator,
+   see the :ref:`Atlas Search <fts-top-ref>` documentation.
+
+Sample Data
+~~~~~~~~~~~
+
+The examples in this guide use the ``sample_mflix.movies`` collection
+from the :atlas:`Atlas sample datasets </sample-data>`. To learn how to create a
+free MongoDB Atlas cluster and load the sample datasets, see
+:ref:`<pymongo-get-started>`.
+
+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. To learn how to create an Atlas Search Index,
+see :ref:`pymongo-atlas-search-index`.
+
+Search Your Data
+----------------
+
+To use the ``$search`` aggregation pipeline stage, you must specify an Atlas Search query
+operator that indicates the type of query you want to run. You can also optionally specify
+a collector that groups results by values or ranges. To view a table of all the operators
+and collectors available with Atlas Search, see :atlas:`Use Operators and Collectors in 
+Atlas Search Queries </atlas-search/operators-and-collectors>`. 
+
+The following example uses the ``phrase`` operator, which performs a search for documents
+that contain an ordered sequence of terms. To learn more about the ``phrase`` operator, see the :atlas:`Phrase </atlas-search/phrase>` guide in the MongoDB Atlas documentation. 
+
+The example performs a basic search of the ``title`` field for the query string ``"new york"``.
+The query also includes the following stages:
+
+- :pipeline:`$limit`, to limit the output to 10 results.
+- :pipeline:`$project`, to exclude all fields except
+  ``title`` and add a field named ``score``.
+
+.. io-code-block::
+   :copyable: true
+
+   .. input::
+      :language: python
+
+      client = pymongo.MongoClient("<connection-string>")
+      result = client["sample_mflix"]["movies"].aggregate([
+               {
+                  "$search": {
+                  "index": "pymongoindex",
+                  "phrase": {
+                  "path": "title",
+                  "query": "new york"
+                 }
+                }
+               },
+               { "$limit": 10 },
+               {
+                 "$project": {
+                 "_id": 0,
+                 "title": 1,
+                 "score": { "$meta": "searchScore" }
+                 }
+                }
+              ])
+
+      for i in result:
+         print(i)
+
+   .. output::
+      :language: none
+      :visible: false
+
+      { title: 'New York, New York', score: 6.786321640014648 }
+      { title: 'New York', score: 6.258549213409424 }
+      { title: 'New York Stories', score: 5.3813982009887695 }
+      { title: 'New York Minute', score: 5.3813982009887695 }
+      { title: 'Synecdoche, New York', score: 5.3813982009887695 }
+      { title: 'New York Doll', score: 5.3813982009887695 }
+      { title: 'Little New York', score: 5.3813982009887695 }
+      { title: 'Escape from New York', score: 4.719893455505371 }
+      { title: 'Naked in New York', score: 4.719893455505371 }
+      { title: 'Autumn in New York', score: 4.719893455505371 }
+
+Additional Information
+----------------------
+
+To learn more about the available Atlas Search operators, see the :atlas:`Operators and Collectors </atlas-search/operators-and-collectors>` guide in the MongoDB Atlas documentation.
+
+For more information about Atlas Search, and to view more query examples, see the
+:atlas:`Atlas Search documentation </atlas-search>`. 

source/index.txt

@@ -18,6 +18,7 @@ MongoDB {+driver-short+} Documentation
    Write Data </write-operations>
    Read Data </read>
    Run a Database Command </run-command>
+   Atlas Search </atlas-search>
    Indexes </indexes>
    Aggregation </aggregation>
    Security </security>