Skip to content

Commit 3daba83

Browse files
rustagirrustagir
authored
DOCSP-45770: atlas search queries (#197)
* DOCSP-45770: atlas search queries * fix indentation * fix indentation * fix indentation * fix indentation * snooty landing page * snooty landing page * indentation fix * netlify trigger * whats new * RM PR fixes 1 * comments * small fix * JT tech review 1 * indentation fix * fix * small fixes * small fixes * remov Pipeline type
1 parent 1543f93 commit 3daba83

File tree

8 files changed

+747
-9
lines changed

8 files changed

+747
-9
lines changed

‎snooty.toml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,7 @@ toc_landing_pages = [
3030
"/security",
3131
"/data-formats",
3232
"/upgrade",
33+
"/aggregation"
3334
]
3435

3536
sharedinclude_root = "https://raw.githubusercontent.com/10gen/docs-shared/main/"

‎source/aggregation.txt

Lines changed: 18 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -18,12 +18,12 @@ Transform Your Data with Aggregation
1818
:depth: 2
1919
:class: singlecol
2020

21-
.. TODO:
22-
.. toctree::
23-
:titlesonly:
24-
:maxdepth: 1
21+
.. toctree::
22+
:titlesonly:
23+
:maxdepth: 1
2524

26-
/aggregation/aggregation-tutorials
25+
Atlas Search </aggregation/atlas-search>
26+
Atlas Vector Search </aggregation/vector-search>
2727

2828
Overview
2929
--------
@@ -88,7 +88,7 @@ Aggregation Example
8888
-------------------
8989

9090
.. note::
91-
91+
9292
The examples in this guide use the ``restaurants`` collection in the ``sample_restaurants``
9393
database from the :atlas:`Atlas sample datasets </sample-data>`. To learn how to create a
9494
free MongoDB Atlas cluster and load the sample datasets, see the :atlas:`Get Started with Atlas
@@ -110,7 +110,7 @@ of New York. To do so, it uses an aggregation pipeline that contains the followi
110110
.. io-code-block::
111111
:copyable:
112112

113-
.. input:: /includes/aggregation.php
113+
.. input:: /includes/aggregation/aggregation.php
114114
:start-after: start-match-group
115115
:end-before: end-match-group
116116
:language: php
@@ -146,13 +146,13 @@ from the preceding :ref:`php-aggregation-example`:
146146
.. io-code-block::
147147
:copyable:
148148

149-
.. input:: /includes/aggregation.php
149+
.. input:: /includes/aggregation/aggregation.php
150150
:start-after: start-explain
151151
:end-before: end-explain
152152
:language: php
153153
:dedent:
154154

155-
.. output::
155+
.. output::
156156
:visible: false
157157

158158
{"explainVersion":"2","queryPlanner":{"namespace":"sample_restaurants.restaurants",
@@ -188,6 +188,15 @@ pages in the {+mdb-server+} manual:
188188
:manual:`Explain Output </reference/explain-results/>` and
189189
:manual:`Query Plans </core/query-plans/>`.
190190

191+
Atlas Search and Vector Search
192+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
193+
194+
You can perform full-text searches by using the Atlas Search feature. To
195+
learn more, see the :ref:`php-atlas-search` guide.
196+
197+
You can perform similarity searches on vector embeddings by using the
198+
Atlas Vector Search feature. To learn more, see the :ref:`php-vector-search` guide.
199+
191200
.. TODO:
192201
Aggregation Tutorials
193202
~~~~~~~~~~~~~~~~~~~~~

‎source/aggregation/atlas-search.txt

Lines changed: 256 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,256 @@
1+
.. _php-atlas-search:
2+
3+
============
4+
Atlas Search
5+
============
6+
7+
.. facet::
8+
:name: genre
9+
:values: reference
10+
11+
.. meta::
12+
:keywords: code example, semantic, text
13+
14+
.. contents:: On this page
15+
:local:
16+
:backlinks: none
17+
:depth: 2
18+
:class: singlecol
19+
20+
Overview
21+
--------
22+
23+
In this guide, you can learn how to perform searches on your documents
24+
by using the Atlas Search feature. The {+library-short+} allows you to
25+
perform Atlas Search queries by using the :ref:`Aggregation Builder API
26+
<TODO DOCSP-43919>`.
27+
28+
.. note:: Deployment Compatibility
29+
30+
You can use the Atlas Search feature only when
31+
you connect to MongoDB Atlas clusters. This feature is not
32+
available for self-managed deployments.
33+
34+
To learn more about Atlas Search, see the :atlas:`Atlas Search Overview
35+
</atlas-search/atlas-search-overview/>`. The Atlas Search implementation
36+
for the {+library-short+} internally uses the ``$search`` aggregation operator
37+
to perform queries. To learn more about this operator, see the
38+
:atlas:`$search </atlas-search/aggregation-stages/search/>` reference in
39+
the Atlas documentation.
40+
41+
.. note:: Atlas Vector Search
42+
43+
To perform searches on vector embeddings in MongoDB, you can use the
44+
Atlas Vector Search API. To learn about this feature, see
45+
the :ref:`php-vector-search` guide.
46+
47+
Atlas Search Index
48+
~~~~~~~~~~~~~~~~~~
49+
50+
Before you can perform Atlas Search queries, you must create an Atlas
51+
Search index on your collection. To learn more about creating this index
52+
type, see the :ref:`php-atlas-search-index` guide.
53+
54+
Search Aggregation Stage
55+
------------------------
56+
57+
Import the following classes into your application to perform Atlas
58+
Search queries by using the Aggregation Builder:
59+
60+
.. literalinclude:: /includes/aggregation/atlas-search.php
61+
:language: php
62+
:dedent:
63+
:start-after: start-imports
64+
:end-before: end-imports
65+
66+
To create a ``$search`` stage in your aggregation pipeline, perform the
67+
following actions:
68+
69+
1. Create an array to store the pipeline stages
70+
71+
#. Call the ``Stage::search()`` method to create the Atlas Search stage
72+
73+
#. Within the body of the ``search()`` method, use methods from the
74+
``Search`` builder class to construct your Search query criteria
75+
76+
The following code demonstrates the template for constructing basic Atlas Search
77+
queries:
78+
79+
.. code-block:: php
80+
81+
$pipeline = [
82+
Stage::search(
83+
/* Atlas Search query specifications
84+
Search::compound(...) */
85+
),
86+
];
87+
88+
Atlas Search Query Examples
89+
---------------------------
90+
91+
In this section, you can learn how to perform different types of Atlas
92+
Search queries by using the Aggregation Builder. The examples in this
93+
section use sample data from the ``sample_restaurants.restaurants``
94+
collection.
95+
96+
Compound Query with Filter
97+
~~~~~~~~~~~~~~~~~~~~~~~~~~
98+
99+
Use the ``Search::compound()`` method to combine two or more operators
100+
into a single query. This method takes named arguments for your clauses,
101+
such as ``must`` and ``filter``. In each clause, use the
102+
``Search::text()`` method to specify the strings to look for when
103+
performing the full-text search.
104+
105+
This example performs an Atlas Search query that has the following
106+
specifications:
107+
108+
- Includes a ``must`` clause to search the ``name`` field for the string
109+
``"kitchen"``
110+
- Includes a ``should`` clause to highly rank documents in which the
111+
``cuisine`` field includes ``"american"``
112+
- Includes a ``filter`` field to include only documents in which the
113+
``borough`` value is ``"Queens"`` in the results
114+
115+
.. io-code-block::
116+
:copyable: true
117+
118+
.. input:: /includes/aggregation/atlas-search.php
119+
:language: php
120+
:dedent:
121+
:start-after: start-compound-search-query
122+
:end-before: end-compound-search-query
123+
124+
.. output::
125+
:language: json
126+
:visible: false
127+
128+
{"_id":...,"borough":"Queens","cuisine":"American","name":"Kitchen Door"}
129+
{"_id":...,"borough":"Queens","cuisine":"American","name":"Cc Kitchen"}
130+
{"_id":...,"borough":"Queens","cuisine":"American","name":"Suite Kitchen"}
131+
// Results truncated
132+
133+
Autocomplete Query
134+
~~~~~~~~~~~~~~~~~~
135+
136+
The {+library-short+} provides the ``Search::autocomplete()`` method to run
137+
autocomplete searches on documents in your collections.
138+
139+
To learn more about this type of Atlas Search query, see the
140+
:atlas:`autocomplete </atlas-search/autocomplete/>` reference in the
141+
Atlas documentation.
142+
143+
.. note::
144+
145+
Your Atlas Search index must be configured for autocomplete queries.
146+
To learn more, see :atlas:`How to Index Fields for Autocompletion
147+
</atlas-search/field-types/autocomplete-type/>` in the Atlas
148+
documentation.
149+
150+
The following code performs an Atlas Search autocomplete query for the
151+
string ``"Lucy"`` on the ``name`` field:
152+
153+
.. io-code-block::
154+
:copyable: true
155+
156+
.. input:: /includes/aggregation/atlas-search.php
157+
:language: php
158+
:dedent:
159+
:start-after: start-autocomplete-search-query
160+
:end-before: end-autocomplete-search-query
161+
162+
.. output::
163+
:language: json
164+
:visible: false
165+
166+
{"name":"Juicy Lucy"}
167+
{"name":"Lucy'S Vietnamese Kitchen"}
168+
{"name":"Lucy'S Cantina Royale"}
169+
// Results Truncated
170+
171+
You can also pass the following optional parameters to the ``autocomplete()``
172+
method to customize the query:
173+
174+
.. list-table::
175+
:header-rows: 1
176+
177+
* - Optional Parameter
178+
- Description
179+
- Default Value
180+
181+
* - ``fuzzy``
182+
- Enables fuzzy search and fuzzy search options
183+
- ``false``
184+
185+
* - ``tokenOrder``
186+
- Specifies order in which to search for tokens
187+
- ``'any'``
188+
189+
To learn more about these parameters, see the :atlas:`Options
190+
</atlas-search/autocomplete/#options>` section of the
191+
``autocomplete`` operator reference in the Atlas documentation.
192+
193+
Search Options
194+
--------------
195+
196+
You can use the ``search()`` method to perform many types of Atlas
197+
Search queries. Depending on your desired query, you can pass the
198+
following optional parameters to ``search()``:
199+
200+
.. list-table::
201+
:header-rows: 1
202+
203+
* - Optional Parameter
204+
- Type
205+
- Description
206+
207+
* - ``index``
208+
- ``string``
209+
- Provides the name of the Atlas Search index to use
210+
211+
* - ``highlight``
212+
- ``array``
213+
- Specifies highlighting options for displaying search terms in their
214+
original context
215+
216+
* - ``concurrent``
217+
- ``bool``
218+
- Parallelizes search query across segments on dedicated search nodes
219+
220+
* - ``count``
221+
- ``string``
222+
- Specifies the count options for retrieving a count of the results
223+
224+
* - ``searchAfter``
225+
- ``string``
226+
- Specifies a reference point for returning documents starting
227+
immediately following that point
228+
229+
* - ``searchBefore``
230+
- ``string``
231+
- Specifies a reference point for returning documents starting
232+
immediately preceding that point
233+
234+
* - ``scoreDetails``
235+
- ``bool``
236+
- Specifies whether to retrieve a detailed breakdown of the score
237+
for results
238+
239+
* - ``sort``
240+
- ``array``
241+
- Specifies the fields on which to sort the results
242+
243+
* - ``returnStoredSource``
244+
- ``bool``
245+
- Specifies whether to perform a full document lookup on the
246+
backend database or return only stored source fields directly
247+
from Atlas Search
248+
249+
* - ``tracking``
250+
- ``array``
251+
- Specifies the tracking option to retrieve analytics information
252+
on the search terms
253+
254+
To learn more about these parameters, see the :atlas:`Fields
255+
</atlas-search/aggregation-stages/search/#fields>` section of the
256+
``$search`` operator reference in the Atlas documentation.

0 commit comments

Comments
 (0)