Skip to content

Commit 9fdfbe5

Browse files
rustagirrustagir
authored
DOCSP-46269: atlas search & atlas vector search pages (#3255)
* DOCSP-46269: as & avs * wip * wip * wip * JT small fix * wip * wip * link fix * merge upstream and make some changes from last PR * revert changes to sessions page - will separate into another PR * LM PR fixes 1 * small note * filename change * LM PR fixes 2 * wip * wip * fix term links * fixes * JT small fixes * indentation fix
1 parent f68e0c2 commit 9fdfbe5

File tree

5 files changed

+576
-0
lines changed

5 files changed

+576
-0
lines changed

Diff for: ‎docs/fundamentals.txt

+4
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,8 @@ Fundamentals
2020
Read Operations </fundamentals/read-operations>
2121
Write Operations </fundamentals/write-operations>
2222
Aggregation Builder </fundamentals/aggregation-builder>
23+
Atlas Search </fundamentals/atlas-search>
24+
Atlas Vector Search </fundamentals/vector-search>
2325

2426
Learn more about the following concepts related to {+odm-long+}:
2527

@@ -28,3 +30,5 @@ Learn more about the following concepts related to {+odm-long+}:
2830
- :ref:`laravel-fundamentals-read-ops`
2931
- :ref:`laravel-fundamentals-write-ops`
3032
- :ref:`laravel-aggregation-builder`
33+
- :ref:`laravel-atlas-search`
34+
- :ref:`laravel-vector-search`

Diff for: ‎docs/fundamentals/atlas-search.txt

+241
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,241 @@
1+
.. _laravel-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. {+odm-long+} provides an API to
25+
perform Atlas Search queries directly with your models. This guide
26+
describes how to create Atlas Search indexes and provides examples of
27+
how to use the {+odm-short+} to perform searches.
28+
29+
.. note:: Deployment Compatibility
30+
31+
You can use the Atlas Search feature only when
32+
you connect to MongoDB Atlas clusters. This feature is not
33+
available for self-managed deployments.
34+
35+
To learn more about Atlas Search, see the :atlas:`Overview
36+
</atlas-search/atlas-search-overview/>` in the
37+
Atlas documentation. The Atlas Search API internally uses the
38+
``$search`` aggregation operator to perform queries. To learn more about
39+
this operator, see the :atlas:`$search
40+
</atlas-search/aggregation-stages/search/>` reference in the Atlas
41+
documentation.
42+
43+
.. note::
44+
45+
You might not be able to use the methods described in
46+
this guide for every type of Atlas Search query.
47+
For more complex use cases, create an aggregation pipeline by using
48+
the :ref:`laravel-aggregation-builder`.
49+
50+
To perform searches on vector embeddings in MongoDB, you can use the
51+
{+odm-long+} Atlas Vector Search API. To learn about this feature, see
52+
the :ref:`laravel-vector-search` guide.
53+
54+
.. _laravel-as-index:
55+
56+
Create an Atlas Search Index
57+
----------------------------
58+
59+
.. TODO in DOCSP-46230
60+
61+
Perform Queries
62+
---------------
63+
64+
In this section, you can learn how to use the Atlas Search API in the
65+
{+odm-short+}.
66+
67+
General Queries
68+
~~~~~~~~~~~~~~~
69+
70+
The {+odm-short+} provides the ``search()`` method as a query
71+
builder method and as an Eloquent model method. You can use the
72+
``search()`` method to run Atlas Search queries on documents in your
73+
collections.
74+
75+
You must pass an ``operator`` parameter to the ``search()`` method that
76+
is an instance of ``SearchOperatorInterface`` or an array that contains
77+
the operator type, field name, and query value. You can
78+
create an instance of ``SearchOperatorInterface`` by calling the
79+
``Search::text()`` method and passing the field you are
80+
querying and your search term or phrase.
81+
82+
You must include the following import statement in your application to
83+
create a ``SearchOperatorInterface`` instance:
84+
85+
.. code-block:: php
86+
87+
use MongoDB\Builder\Search;
88+
89+
The following code performs an Atlas Search query on the ``Movie``
90+
model's ``title`` field for the term ``'dream'``:
91+
92+
.. io-code-block::
93+
:copyable: true
94+
95+
.. input:: /includes/fundamentals/as-avs/AtlasSearchTest.php
96+
:language: php
97+
:dedent:
98+
:start-after: start-search-query
99+
:end-before: end-search-query
100+
101+
.. output::
102+
:language: json
103+
:visible: false
104+
105+
[
106+
{ "title": "Dreaming of Jakarta",
107+
"year": 1990
108+
},
109+
{ "title": "See You in My Dreams",
110+
"year": 1996
111+
}
112+
]
113+
114+
You can use the ``search()`` method to perform many types of Atlas
115+
Search queries. Depending on your desired query, you can pass the
116+
following optional parameters to ``search()``:
117+
118+
.. list-table::
119+
:header-rows: 1
120+
121+
* - Optional Parameter
122+
- Type
123+
- Description
124+
125+
* - ``index``
126+
- ``string``
127+
- Provides the name of the Atlas Search index to use
128+
129+
* - ``highlight``
130+
- ``array``
131+
- Specifies highlighting options for displaying search terms in their
132+
original context
133+
134+
* - ``concurrent``
135+
- ``bool``
136+
- Parallelizes search query across segments on dedicated search nodes
137+
138+
* - ``count``
139+
- ``string``
140+
- Specifies the count options for retrieving a count of the results
141+
142+
* - ``searchAfter``
143+
- ``string``
144+
- Specifies a reference point for returning documents starting
145+
immediately following that point
146+
147+
* - ``searchBefore``
148+
- ``string``
149+
- Specifies a reference point for returning documents starting
150+
immediately preceding that point
151+
152+
* - ``scoreDetails``
153+
- ``bool``
154+
- Specifies whether to retrieve a detailed breakdown of the score
155+
for results
156+
157+
* - ``sort``
158+
- ``array``
159+
- Specifies the fields on which to sort the results
160+
161+
* - ``returnStoredSource``
162+
- ``bool``
163+
- Specifies whether to perform a full document lookup on the
164+
backend database or return only stored source fields directly
165+
from Atlas Search
166+
167+
* - ``tracking``
168+
- ``array``
169+
- Specifies the tracking option to retrieve analytics information
170+
on the search terms
171+
172+
To learn more about these parameters, see the :atlas:`Fields
173+
</atlas-search/aggregation-stages/search/#fields>` section of the
174+
``$search`` operator reference in the Atlas documentation.
175+
176+
Autocomplete Queries
177+
~~~~~~~~~~~~~~~~~~~~
178+
179+
The {+odm-short+} provides the ``autocomplete()`` method as a query
180+
builder method and as an Eloquent model method. You can use the
181+
``autocomplete()`` method to run autocomplete searches on documents in your
182+
collections. This method returns only the values of the field you
183+
specify as the query path.
184+
185+
To learn more about this type of Atlas Search query, see the
186+
:atlas:`autocomplete </atlas-search/autocomplete/>` reference in the
187+
Atlas documentation.
188+
189+
.. note::
190+
191+
You must create an Atlas Search index with an autocomplete configuration
192+
on your collection before you can perform autocomplete searches. See the
193+
:ref:`laravel-as-index` section of this guide to learn more about
194+
creating Search indexes.
195+
196+
The following code performs an Atlas Search autocomplete query for the
197+
string ``"jak"`` on the ``title`` field:
198+
199+
.. io-code-block::
200+
:copyable: true
201+
202+
.. input:: /includes/fundamentals/as-avs/AtlasSearchTest.php
203+
:language: php
204+
:dedent:
205+
:start-after: start-auto-query
206+
:end-before: end-auto-query
207+
208+
.. output::
209+
:language: json
210+
:visible: false
211+
212+
[
213+
"Dreaming of Jakarta",
214+
"Jakob the Liar",
215+
"Emily Calling Jake"
216+
]
217+
218+
You can also pass the following optional parameters to the ``autocomplete()``
219+
method to customize the query:
220+
221+
.. list-table::
222+
:header-rows: 1
223+
224+
* - Optional Parameter
225+
- Type
226+
- Description
227+
- Default Value
228+
229+
* - ``fuzzy``
230+
- ``bool`` or ``array``
231+
- Enables fuzzy search and fuzzy search options
232+
- ``false``
233+
234+
* - ``tokenOrder``
235+
- ``string``
236+
- Specifies order in which to search for tokens
237+
- ``'any'``
238+
239+
To learn more about these parameters, see the :atlas:`Options
240+
</atlas-search/autocomplete/#options>` section of the
241+
``autocomplete`` operator reference in the Atlas documentation.

0 commit comments

Comments
 (0)