|
| 1 | +.. _kotlin-sync-atlas-search: |
| 2 | + |
| 3 | +========================= |
| 4 | +Run an Atlas Search Query |
| 5 | +========================= |
| 6 | + |
| 7 | +.. facet:: |
| 8 | + :name: genre |
| 9 | + :values: reference |
| 10 | + |
| 11 | +.. meta:: |
| 12 | + :keywords: full text, text analyzer, meta, pipeline, scoring, Lucene |
| 13 | + :description: Learn about how to use Atlas Search in the {+driver-long+}. |
| 14 | + |
| 15 | +.. contents:: On this page |
| 16 | + :local: |
| 17 | + :backlinks: none |
| 18 | + :depth: 2 |
| 19 | + :class: singlecol |
| 20 | + |
| 21 | +Overview |
| 22 | +-------- |
| 23 | + |
| 24 | +In this guide, you can learn how to use the {+driver-short+} to |
| 25 | +run :atlas:`Atlas Search </atlas-search/>` queries on a collection. |
| 26 | +Atlas Search enables you to perform full-text searches on collections |
| 27 | +hosted on MongoDB Atlas. Atlas Search indexes specify the behavior of the |
| 28 | +search and which fields to index. |
| 29 | + |
| 30 | +Sample Data |
| 31 | +~~~~~~~~~~~ |
| 32 | + |
| 33 | +The examples in this guide use the ``movies`` collection in the ``sample_mflix`` |
| 34 | +database from the :atlas:`Atlas sample datasets </sample-data>`. To learn how to |
| 35 | +create a free MongoDB Atlas cluster and load the sample datasets, see the |
| 36 | +:atlas:`Get Started with Atlas </getting-started>` guide. To learn more about |
| 37 | +aggregation operations and builders, see the :ref:`kotlin-sync-aggregation` guide. |
| 38 | + |
| 39 | +Run an Atlas Search Query |
| 40 | +------------------------- |
| 41 | + |
| 42 | +This section shows how to create an aggregation pipeline to run an |
| 43 | +Atlas Search query on a collection. You can use the ``Aggregates.search()`` builder |
| 44 | +method to create a ``$search`` pipeline stage, which specifies the search |
| 45 | +criteria. Then, call the ``aggregate()`` method and pass your pipeline as a |
| 46 | +parameter. |
| 47 | + |
| 48 | +.. note:: Only Available on Atlas for MongoDB v4.2 and later |
| 49 | + |
| 50 | + This aggregation pipeline operator is only available for collections hosted |
| 51 | + on :atlas:`MongoDB Atlas </>` clusters running v4.2 or later that are |
| 52 | + covered by an :atlas:`Atlas Search index </reference/atlas-search/index-definitions/>`. |
| 53 | + Learn more about the required setup and the functionality of this operator |
| 54 | + from the :atlas:`Atlas Search </atlas-search/>` documentation. |
| 55 | + |
| 56 | +Before running an Atlas Search query, you must create an Atlas Search index |
| 57 | +on your collection. To learn how to programmatically create an Atlas Search |
| 58 | +index, see the :ref:`kotlin-sync-atlas-search-index-create` section in the Indexes guide. |
| 59 | + |
| 60 | +Atlas Search Example |
| 61 | +~~~~~~~~~~~~~~~~~~~~ |
| 62 | + |
| 63 | +This example runs an Atlas Search query by performing the |
| 64 | +following actions: |
| 65 | + |
| 66 | +- Constructs a ``$search`` stage by using the ``Aggregates.search()`` builder method, |
| 67 | + instructing the driver to query for documents in which the ``title`` |
| 68 | + field contains the word ``"Alabama"`` |
| 69 | + |
| 70 | +- Constructs a ``$project`` stage by using the ``Aggregates.project()`` builder method, |
| 71 | + instructing the driver to include the ``title`` field in the query results |
| 72 | + |
| 73 | +- Passes the pipeline stages to the ``aggregate()`` method and prints the results |
| 74 | + |
| 75 | +.. io-code-block:: |
| 76 | + :copyable: |
| 77 | + |
| 78 | + .. input:: /includes/atlas-search.kt |
| 79 | + :start-after: begin-atlas-search |
| 80 | + :end-before: end-atlas-search |
| 81 | + :language: kotlin |
| 82 | + :dedent: |
| 83 | + |
| 84 | + .. output:: |
| 85 | + :language: console |
| 86 | + :visible: false |
| 87 | + |
| 88 | + {"_id": {"$oid": "..."}, "title": "Alabama Moon"} |
| 89 | + {"_id": {"$oid": "..."}, "title": "Crazy in Alabama"} |
| 90 | + {"_id": {"$oid": "..."}, "title": "Sweet Home Alabama"} |
| 91 | + |
| 92 | +Atlas Search Metadata |
| 93 | +--------------------- |
| 94 | + |
| 95 | +Use the ``searchMeta()`` method to create a :manual:`$searchMeta |
| 96 | +</reference/operator/aggregation/searchMeta/>` pipeline stage, which returns |
| 97 | +only the metadata from the Atlas full-text search results. |
| 98 | + |
| 99 | +.. tip:: Only Available on Atlas for MongoDB v4.4.11 and later |
| 100 | + |
| 101 | + This aggregation pipeline operator is available only |
| 102 | + on :atlas:`MongoDB Atlas </>` clusters running v4.4.11 and later. |
| 103 | + |
| 104 | +The following example shows the ``near`` metadata for an Atlas Search |
| 105 | +aggregation stage: |
| 106 | + |
| 107 | +.. literalinclude:: /includes/aggregation/search-meta-agg.kt |
| 108 | + :start-after: // begin atlasSearchMeta |
| 109 | + :end-before: // end atlasSearchMeta |
| 110 | + :language: kotlin |
| 111 | + :dedent: |
| 112 | + |
| 113 | +.. _kotlin-atlas-search-helpers: |
| 114 | + |
| 115 | +Create Pipeline Search Stages |
| 116 | +----------------------------- |
| 117 | + |
| 118 | +.. sharedinclude:: dbx/jvm/atlas-search-operator-helpers.rst |
| 119 | + |
| 120 | + .. replacement:: as-idx-link |
| 121 | + |
| 122 | + the :ref:`kotlin-sync-atlas-search-index-create` section of the Indexes guide |
| 123 | + |
| 124 | + .. replacement:: atlas-query-operators-example |
| 125 | + |
| 126 | + .. io-code-block:: |
| 127 | + |
| 128 | + .. input:: /includes/aggregation/aggregation.kt |
| 129 | + :language: kotlin |
| 130 | + :start-after: // start-atlas-searchoperator-helpers |
| 131 | + :end-before: // end-atlas-searchoperator-helpers |
| 132 | + :dedent: |
| 133 | + |
| 134 | + .. output:: |
| 135 | + :language: console |
| 136 | + :visible: false |
| 137 | + |
| 138 | + {"_id": ..., "genres": ["Comedy", "Romance"], "title": "Love at First Bite", "year": 1979} |
| 139 | + {"_id": ..., "genres": ["Comedy", "Drama"], "title": "Love Affair", "year": 1994} |
| 140 | + |
| 141 | +Additional Information |
| 142 | +---------------------- |
| 143 | + |
| 144 | +To learn more about Atlas Search, see :atlas:`Atlas Search </atlas-search/>` |
| 145 | +in the Atlas documentation. |
| 146 | + |
| 147 | +API Documentation |
| 148 | +~~~~~~~~~~~~~~~~~ |
| 149 | + |
| 150 | +To learn more about the methods mentioned in this guide, see |
| 151 | +the following API documentation: |
| 152 | + |
| 153 | +- `aggregate() <{+driver-api+}/-mongo-collection/aggregate.html>`__ |
| 154 | +- `Aggregates.search() <{+core-api+}/client/model/Aggregates.html#search(com.mongodb.client.model.search.SearchCollector)>`__ |
| 155 | +- `Aggregates.searchMeta() <{+core-api+}/client/model/Aggregates.html#searchMeta(com.mongodb.client.model.search.SearchCollector)>`__ |
| 156 | +- `Aggregates.project() <{+core-api+}/client/model/Aggregates.html#project(org.bson.conversions.Bson)>`__ |
| 157 | +- `SearchOperator <{+core-api+}/client/model/search/SearchOperator.html>`__ |
0 commit comments