Skip to content

Commit 9084089

Browse files
authored
DOCSP-51348-atlas-search-page (#122)
* atlas search page * fix link * sa feedback * nathan feedback
1 parent 48d1336 commit 9084089

File tree

3 files changed

+236
-1
lines changed

3 files changed

+236
-1
lines changed

source/atlas-search.txt

Lines changed: 153 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,4 +2,156 @@
22

33
=========================
44
Run an Atlas Search Query
5-
=========================
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>`__
Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
package org.example
2+
3+
import com.mongodb.ConnectionString
4+
import com.mongodb.kotlin.client.MongoClient
5+
import com.mongodb.MongoClientSettings
6+
import com.mongodb.client.model.Aggregates.searchMeta
7+
import com.mongodb.client.model.search.SearchOperator
8+
import com.mongodb.client.model.search.SearchPath.fieldPath
9+
import com.mongodb.kotlin.client.MongoCollection
10+
import org.bson.Document
11+
12+
fun runAtlasTextSearchMeta(collection: MongoCollection<Document>) {
13+
val textSearchMeta =
14+
// begin atlasSearchMeta
15+
searchMeta(
16+
SearchOperator.near(2010, 1, fieldPath("year"))
17+
)
18+
// end atlasSearchMeta
19+
20+
val aggregateStages = listOf(textSearchMeta)
21+
println("aggregateStages: $aggregateStages")
22+
23+
collection.aggregate(aggregateStages).forEach { result ->
24+
println(result)
25+
}
26+
}
27+
28+
fun main() {
29+
val uri = "<connection string>"
30+
31+
val settings = MongoClientSettings.builder()
32+
.applyConnectionString(ConnectionString(uri))
33+
.retryWrites(true)
34+
.build()
35+
36+
MongoClient.create(settings).use { mongoClient ->
37+
val database = mongoClient.getDatabase("sample_mflix")
38+
val collection = database.getCollection<Document>("movies")
39+
40+
runAtlasTextSearchMeta(collection)
41+
}
42+
}

source/includes/atlas-search.kt

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
// Runs an Atlas Search query by using the Kotlin sync driver
2+
3+
package org.example
4+
5+
import com.mongodb.ConnectionString
6+
import com.mongodb.kotlin.client.MongoClient
7+
import com.mongodb.MongoClientSettings
8+
import com.mongodb.client.model.Aggregates.project
9+
import com.mongodb.client.model.Aggregates.search
10+
import com.mongodb.client.model.Projections
11+
import com.mongodb.client.model.search.SearchOperator
12+
import com.mongodb.client.model.search.SearchPath.fieldPath
13+
import org.bson.Document
14+
import org.bson.conversions.Bson
15+
16+
fun main() {
17+
val uri = "<connection string>"
18+
19+
val settings = MongoClientSettings.builder()
20+
.applyConnectionString(ConnectionString(uri))
21+
.retryWrites(true)
22+
.build()
23+
24+
val mongoClient = MongoClient.create(settings)
25+
val database = mongoClient.getDatabase("sample_mflix")
26+
val collection = database.getCollection<Document>("movies")
27+
28+
// begin-atlas-search
29+
val pipeline: List<Bson> = listOf(
30+
search(SearchOperator.text(
31+
fieldPath("title"), "Alabama")),
32+
project(Projections.include("title"))
33+
)
34+
35+
val results = collection.aggregate(pipeline)
36+
37+
results.forEach { doc ->
38+
println(doc.toJson())
39+
}
40+
// end-atlas-search
41+
}

0 commit comments

Comments
 (0)