Skip to content

Commit 4da72b7

Browse files
committed
aggregation page
1 parent aeb5777 commit 4da72b7

File tree

3 files changed

+145
-61
lines changed

3 files changed

+145
-61
lines changed

source/atlas-search.txt

Lines changed: 113 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -30,23 +30,28 @@ search and which fields to index.
3030
Sample Data
3131
~~~~~~~~~~~
3232

33-
The example in this guide uses the ``movies`` collection in the ``sample_mflix``
33+
The examples in this guide use the ``movies`` collection in the ``sample_mflix``
3434
database from the :atlas:`Atlas sample datasets </sample-data>`. To learn how to
3535
create a free MongoDB Atlas cluster and load the sample datasets, see the
36-
:atlas:`Get Started with Atlas </getting-started>` guide.
36+
:atlas:`Get Started with Atlas </getting-started>` guide. To learn more about
37+
aggregation operations and builders, see the :ref:`java-aggregation` guide.
3738

3839
Run an Atlas Search Query
3940
-------------------------
4041

4142
This section shows how to create an aggregation pipeline to run an
4243
Atlas Search query on a collection. You can use the ``Aggregates.search()`` builder
4344
method to create a ``$search`` pipeline stage, which specifies the search
44-
criteria. Then, call the ``aggregate()`` method and pass your pipeline as a parameter.
45+
criteria. Then, call the ``aggregate()`` method and pass your pipeline as a
46+
parameter.
4547

46-
.. tip::
48+
.. note:: Only Available on Atlas for MongoDB v4.2 and later
4749

48-
To learn more about aggregation operations and builders, see the :ref:`java-aggregation`
49-
guide.
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 <java-atlas-search>` documentation.
5055

5156
Before running an Atlas Search query, you must create an Atlas Search index
5257
on your collection. To learn how to programmatically create an Atlas Search
@@ -90,6 +95,107 @@ following actions:
9095
Search queries, see :atlas:`Atlas Search Tutorials </atlas-search/tutorials/>`
9196
in the Atlas documentation.
9297

98+
Atlas Search Metadata
99+
---------------------
100+
101+
Use the ``searchMeta()`` method to create a
102+
:manual:`$searchMeta </reference/operator/aggregation/searchMeta/>`
103+
pipeline stage which returns only the metadata part of the results from
104+
Atlas full-text search queries.
105+
106+
.. tip:: Only Available on Atlas for MongoDB v4.4.11 and later
107+
108+
This aggregation pipeline operator is only available
109+
on :atlas:`MongoDB Atlas </>` clusters running v4.4.11 and later. For a
110+
detailed list of version availability, see the MongoDB Atlas documentation
111+
on :atlas:`$searchMeta </atlas-search/query-syntax/#-searchmeta>`.
112+
113+
The following example shows the ``count`` metadata for an Atlas search
114+
aggregation stage:
115+
116+
.. literalinclude:: /includes/fundamentals/code-snippets/builders/AggregateSearchBuilderExample.java
117+
:start-after: // begin atlasSearchMeta
118+
:end-before: // end atlasSearchMeta
119+
:language: java
120+
:dedent:
121+
122+
Learn more about this helper from the
123+
`searchMeta() API documentation <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/Aggregates.html#searchMeta(com.mongodb.client.model.search.SearchCollector)>`__.
124+
125+
SearchOperator Helper Methods
126+
-----------------------------
127+
128+
To make building pipeline stages easier, the {+driver-short+} provides helper methods
129+
for the following operations:
130+
131+
- :atlas:`autocomplete </atlas-search/autocomplete/>`: Performs a search for a
132+
word or phrase that contains a sequence of characters from an incomplete
133+
input string.
134+
135+
- :atlas:`compound </atlas-search/compound/>`: Combines two or more operators
136+
into a single query.
137+
138+
- :atlas:`equals </atlas-search/equals/>` (``equals()`` and ``equalsNull()``): Checks
139+
whether a field matches a value you specify.
140+
141+
- :atlas:`exists </atlas-search/exists/>`: Tests if a path to a specified
142+
indexed field name exists in a document.
143+
144+
- :atlas:`in </atlas-search/in/>`: Performs a search for an array of BSON
145+
number, date, boolean, objectId, uuid, or string values at the given path
146+
and returns documents where the value of the field equals any value in the
147+
specified array.
148+
149+
- :atlas:`moreLikeThis </atlas-search/moreLikeThis/>`: Returns documents similar
150+
to input documents.
151+
152+
- :atlas:`near </atlas-search/near/>`: Supports querying and scoring numeric,
153+
date, and GeoJSON point values.
154+
155+
- :atlas:`phrase </atlas-search/phrase/>`: Performs a search for documents
156+
containing an ordered sequence of terms using the analyzer specified in the
157+
index configuration.
158+
159+
- :atlas:`queryString </atlas-search/queryString/>`: Supports querying a
160+
combination of indexed fields and values.
161+
162+
- :atlas:`range </atlas-search/range/>` (``numberRange()`` and ``dateRange()``): Supports
163+
querying and scoring numeric, date, and string values.
164+
165+
- :atlas:`regex </atlas-search/regex/>`: Interprets the query field as a regular
166+
expression.
167+
168+
- :atlas:`text </atlas-search/text/>`: Performs a full-text search using the
169+
analyzer that you specify in the index configuration.
170+
171+
- :atlas:`wildcard </atlas-search/wildcard/>`: Enables queries which use special
172+
characters in the search string that can match any character.
173+
174+
Example Pipeline Search Stage
175+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
176+
177+
.. note:: Atlas Sample Dataset
178+
179+
This example uses the MongoDB Atlas sample dataset. Specifically, the
180+
``movies`` collection in the ``sample_mflix`` database. You can learn how
181+
to set up your own free-tier Atlas cluster and how to load the sample dataset
182+
in our :ref:`quick start guide <java-get-started>`.
183+
184+
The following code creates a search stage for a pipeline with the following filters:
185+
186+
- Movies in the drama genre
187+
- Movies that include Sylvester Stallone in the cast, accounting for possible misspellings
188+
- Movies made between 1980 and 1989, inclusive
189+
- Movies with titles that begin with the word ``"Rocky"``
190+
191+
.. literalinclude:: /includes/fundamentals/code-snippets/builders/AggregateSearchBuilderExample.java
192+
:start-after: // begin atlasHelperMethods
193+
:end-before: // end atlasHelperMethods
194+
:language: java
195+
:dedent:
196+
197+
To learn more about the helper methods, see the `SearchOperator Interface API documentation <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/search/SearchOperator.html>`__.
198+
93199
Additional Information
94200
----------------------
95201

@@ -105,3 +211,4 @@ the following API documentation:
105211
- `MongoCollection.aggregate() <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoCollection.html#aggregate(java.util.List)>`__
106212
- `Aggregates.search() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/Aggregates.html#search(com.mongodb.client.model.search.SearchCollector)>`__
107213
- `Aggregates.project() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/Aggregates.html#project(org.bson.conversions.Bson)>`__
214+
- `SearchOperator <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/search/SearchOperator.html>`__

source/crud/builders/aggregates.txt

Lines changed: 4 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -17,10 +17,6 @@ Aggregates Builders
1717
:depth: 2
1818
:class: singlecol
1919

20-
.. toctree::
21-
22-
Atlas Vector Search </atlas-vector-search>
23-
2420
Overview
2521
--------
2622

@@ -931,55 +927,8 @@ by the aggregate stage:
931927
See the `fill package API documentation <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/fill/package-summary.html>`__
932928
for more information.
933929

934-
Atlas Full-Text Search
935-
----------------------
936-
937-
Use the ``search()`` method to create a :manual:`$search </reference/operator/aggregation/search/>`
938-
pipeline stage that specifies a full-text search of one or more fields.
939-
940-
.. tip:: Only Available on Atlas for MongoDB v4.2 and later
941-
942-
This aggregation pipeline operator is only available for collections hosted
943-
on :atlas:`MongoDB Atlas </>` clusters running v4.2 or later that are
944-
covered by an :atlas:`Atlas search index </reference/atlas-search/index-definitions/>`.
945-
Learn more about the required setup and the functionality of this operator
946-
from the :ref:`Atlas Search <fts-top-ref>` documentation.
947-
948-
The following example creates a pipeline stage that searches the ``title``
949-
field for text that contains the word "Future":
950-
951-
.. literalinclude:: /includes/fundamentals/code-snippets/builders/AggregateSearchBuilderExample.java
952-
:start-after: // begin atlasTextSearch
953-
:end-before: // end atlasTextSearch
954-
:language: java
955-
:dedent:
956-
957-
Learn more about the builders from the
958-
`search package API documentation <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/search/package-summary.html>`__.
959-
960-
Atlas Search Metadata
961-
---------------------
962-
963-
Use the ``searchMeta()`` method to create a
964-
:manual:`$searchMeta </reference/operator/aggregation/searchMeta/>`
965-
pipeline stage which returns only the metadata part of the results from
966-
Atlas full-text search queries.
967-
968-
.. tip:: Only Available on Atlas for MongoDB v4.4.11 and later
969-
970-
This aggregation pipeline operator is only available
971-
on :atlas:`MongoDB Atlas </>` clusters running v4.4.11 and later. For a
972-
detailed list of version availability, see the MongoDB Atlas documentation
973-
on :atlas:`$searchMeta </atlas-search/query-syntax/#-searchmeta>`.
974-
975-
The following example shows the ``count`` metadata for an Atlas search
976-
aggregation stage:
977-
978-
.. literalinclude:: /includes/fundamentals/code-snippets/builders/AggregateSearchBuilderExample.java
979-
:start-after: // begin atlasSearchMeta
980-
:end-before: // end atlasSearchMeta
981-
:language: java
982-
:dedent:
930+
Atlas Search
931+
------------
983932

984-
Learn more about this helper from the
985-
`searchMeta() API documentation <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/Aggregates.html#searchMeta(com.mongodb.client.model.search.SearchCollector)>`__.
933+
To learn about building Atlas Search pipelines, see the :ref:`Atlas Search
934+
<java-atlas-search>` and :ref:`Atlas Vector Search <java-atlas-vector-search>` pages.

source/includes/fundamentals/code-snippets/builders/AggregateSearchBuilderExample.java

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,34 @@ private static void runAtlasTextSearch(MongoCollection<Document> collection) {
5454
collection.aggregate(aggregateStages).forEach(result -> System.out.println(result));
5555
}
5656

57+
/*
58+
* Atlas search aggregation
59+
* Requires Atlas cluster and full text search index
60+
* See https://www.mongodb.com/docs/atlas/atlas-search/tutorial/ for more info on requirements
61+
*/
62+
private static void runAtlasSearchWithSearchHelperMethods(MongoCollection<Document> collection) {
63+
// begin atlasHelperMethods
64+
Bson search_stage = Aggregates.search(
65+
SearchOperator.compound()
66+
.filter(
67+
List.of(
68+
SearchOperator.text(fieldPath("genres"), "Drama"),
69+
SearchOperator.phrase(fieldPath("cast"), "sylvester stallone"),
70+
SearchOperator.numberRange(fieldPath("year")).gtLt(1980, 1989),
71+
SearchOperator.wildcard("Rocky *", fieldPath("title"))
72+
)));
73+
// end atlasHelperMethods
74+
75+
// To condense result data, add this projection into the pipeline
76+
// Bson projection = Aggregates.project(Projections.fields(Projections.include("title", "released")));
77+
78+
List<Bson> aggregateStages = List.of(searchStageFilters);
79+
System.out.println("aggregateStages: " + aggregateStages);
80+
81+
System.out.println("explain:\n" + collection.aggregate(aggregateStages).explain());
82+
collection.aggregate(aggregateStages).forEach(result -> System.out.println(result));
83+
}
84+
5785
/*
5886
* Atlas search aggregation
5987
* Requires Atlas cluster and full text search index

0 commit comments

Comments
 (0)