Skip to content

Commit 9764ff9

Browse files
shuangelashuangela
committed
atlas search page
1 parent 4be94d7 commit 9764ff9

File tree

3 files changed

+242
-1
lines changed

3 files changed

+242
-1
lines changed

‎source/atlas-search.txt

Lines changed: 155 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,4 +2,158 @@
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 :ref:`Atlas Search <kotlin-sync-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 of 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. For a
103+
detailed list of version availability, see the MongoDB Atlas documentation
104+
on :atlas:`$searchMeta </atlas-search/query-syntax/#-searchmeta>`.
105+
106+
The following example shows the ``near`` metadata for an Atlas search
107+
aggregation stage:
108+
109+
.. literalinclude:: /includes/aggregation/search-meta-agg.kt
110+
:start-after: // begin atlasSearchMeta
111+
:end-before: // end atlasSearchMeta
112+
:language: kotlin
113+
:dedent:
114+
115+
.. _kotlin-atlas-search-helpers:
116+
117+
Create Pipeline Search Stages
118+
-----------------------------
119+
120+
.. sharedinclude:: dbx/jvm/atlas-search-operator-helpers.rst
121+
122+
.. replacement:: as-idx-link
123+
124+
the :ref:`kotlin-sync-atlas-search-index-create` section of the Indexes guide
125+
126+
.. replacement:: atlas-query-operators-example
127+
128+
.. io-code-block::
129+
130+
.. input:: /includes/aggregation/aggregation.kt
131+
:language: kotlin
132+
:start-after: // start-atlas-searchoperator-helpers
133+
:end-before: // end-atlas-searchoperator-helpers
134+
:dedent:
135+
136+
.. output::
137+
:language: console
138+
:visible: false
139+
140+
{"_id": ..., "genres": ["Comedy", "Romance"], "title": "Love at First Bite", "year": 1979}
141+
{"_id": ..., "genres": ["Comedy", "Drama"], "title": "Love Affair", "year": 1994}
142+
143+
Additional Information
144+
----------------------
145+
146+
To learn more about Atlas Search, see :atlas:`Atlas Search </atlas-search/>`
147+
in the Atlas documentation.
148+
149+
API Documentation
150+
~~~~~~~~~~~~~~~~~
151+
152+
To learn more about the methods mentioned in this guide, see
153+
the following API documentation:
154+
155+
- `aggregate() <{+driver-api+}/-mongo-collection/aggregate.html>`__
156+
- `Aggregates.search() <{+core-api+}/client/model/Aggregates.html#search(com.mongodb.client.model.search.SearchCollector)>`__
157+
- `Aggregates.searchMeta() <{+core-api+}/client/model/Aggregates.html#searchMeta(com.mongodb.client.model.search.SearchCollector)>`__
158+
- `Aggregates.project() <{+core-api+}/client/model/Aggregates.html#project(org.bson.conversions.Bson)>`__
159+
- `SearchOperator <{+core-api+}/client/model/search/SearchOperator.html>`__

‎source/includes/aggregation/search-meta-agg.kt

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
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+
private const val CONNECTION_URI = "<connection URI>"
13+
14+
fun runAtlasTextSearchMeta(collection: MongoCollection<Document>) {
15+
val textSearchMeta =
16+
// begin atlasSearchMeta
17+
searchMeta(
18+
SearchOperator.near(2010, 1, fieldPath("year"))
19+
)
20+
// end atlasSearchMeta
21+
22+
val aggregateStages = listOf(textSearchMeta)
23+
println("aggregateStages: $aggregateStages")
24+
25+
collection.aggregate(aggregateStages).forEach { result ->
26+
println(result)
27+
}
28+
}
29+
30+
fun main() {
31+
val uri = CONNECTION_URI
32+
33+
val settings = MongoClientSettings.builder()
34+
.applyConnectionString(ConnectionString(uri))
35+
.retryWrites(true)
36+
.build()
37+
38+
MongoClient.create(settings).use { mongoClient ->
39+
val database = mongoClient.getDatabase("sample_mflix")
40+
val collection = database.getCollection<Document>("movies")
41+
42+
// Uncomment the methods that correspond to what you're testing
43+
// runAtlasTextSearchMeta(collection)
44+
}
45+
}

‎source/includes/atlas-search.kt

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
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+
// Queries for documents that have a "title" value containing the word "Alabama"
29+
// begin-atlas-search
30+
val pipeline: List<Bson> = listOf(
31+
search(SearchOperator.text(
32+
fieldPath("title"), "Alabama")),
33+
project(Projections.include("title"))
34+
)
35+
36+
val results = collection.aggregate(pipeline)
37+
38+
results.forEach { doc ->
39+
println(doc.toJson())
40+
}
41+
// end-atlas-search
42+
}

0 commit comments

Comments
 (0)