Skip to content

Commit a430efd

Browse files
davidhou17davidhou17
authored
(DOCSP-32019): Add Atlas UI procedure to Query Arrays page (#4898) (#4987)
* Add Atlas UI procedure * copy review feedback
1 parent a9264a8 commit a430efd

File tree

2 files changed

+162
-7
lines changed

2 files changed

+162
-7
lines changed

‎source/includes/steps-nav-atlas-sample-movies.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,5 +2,5 @@ a. In the {+atlas+} UI, click :guilabel:`Database` in the sidebar.
22
#. For the database deployment that contains the sample data,
33
click :guilabel:`Browse Collections`.
44
#. In the left navigation pane, select the
5-
:guilabel:`sample_mflix` database.
6-
#. Select the :guilabel:`movies` collection.
5+
``sample_mflix`` database.
6+
#. Select the ``movies`` collection.

‎source/tutorial/query-arrays.txt‎

Lines changed: 160 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -18,14 +18,13 @@ Query an Array
1818
:backlinks: none
1919
:depth: 1
2020

21-
----------
21+
You can query arrays in MongoDB using the following methods:
2222

23-
.. |arrow| unicode:: U+27A4
23+
.. |atlas-ref| replace:: :ref:`query-array-atlas-ui`
2424

25-
|arrow| Use the **Select your language** drop-down menu in the
26-
upper-right to set the language of the following examples.
25+
.. include:: /includes/fact-methods.rst
2726

28-
----------
27+
.. include:: /includes/language-selector-instructions.rst
2928

3029
.. tabs-selector:: drivers
3130

@@ -137,7 +136,163 @@ elements. For example, the following selects documents where the array
137136

138137
.. include:: /includes/driver-examples/driver-example-query-28.rst
139138

139+
.. _query-array-atlas-ui:
140140

141+
Query an Array with {+atlas+}
142+
---------------------------------
143+
144+
The example in this section uses the :atlas:`sample movies dataset
145+
</sample-data/sample-mflix/>`. To learn how to load the sample dataset
146+
into your {+atlas+} deployment, see :atlas:`Load Sample Data
147+
</sample-data/#std-label-load-sample-data>`.
148+
149+
To query an array in {+atlas+}, follow these steps:
150+
151+
.. procedure::
152+
:style: normal
153+
154+
.. step:: Navigate to the collection.
155+
156+
.. include:: /includes/steps-nav-atlas-sample-movies.rst
157+
158+
.. step:: Specify a query filter document.
159+
160+
To query a document that contains an array,
161+
specify a :ref:`query filter document <document-query-filter>`.
162+
A query filter document uses :ref:`query operators
163+
<csfle-supported-query-operators>` to specify search conditions.
164+
Use the following example documents to query array fields in the
165+
``sample_mflix.movies`` collection.
166+
167+
To apply a query filter, copy an example document into the
168+
:guilabel:`Filter` search bar and click :guilabel:`Apply`.
169+
170+
.. tabs::
171+
172+
.. tab:: Match an Array
173+
:tabid: match
174+
175+
To specify an equality condition on an array, use the query
176+
document ``{ <field>: <value> }`` where ``<value>`` is
177+
the exact array to match, including the order of the elements.
178+
The following example finds documents that have a ``genres``
179+
field that contains the ``["Action", "Comedy"]`` array in the
180+
specified order:
181+
182+
.. code-block::
183+
184+
{ genres: ["Action", "Comedy"] }
185+
186+
To find an array that contains both the elements ``Action`` and
187+
``Comedy``, without regard to order or other elements
188+
in the array, use the :query:`$all` operator:
189+
190+
.. code-block::
191+
192+
{ genres: { $all: ["Action", "Comedy"] } }
193+
194+
.. tab:: Query for an Element
195+
:tabid: element
196+
197+
To query if the array field contains at least one element with the
198+
specified value, use the filter ``{ <field>: <value> }`` where
199+
``<value>`` is the element value.
200+
201+
The following example queries for all documents where the
202+
``genres`` field contains the string ``Short`` as one
203+
of its elements:
204+
205+
.. code-block::
206+
207+
{ genres: "Short" }
208+
209+
To specify conditions on the elements in the array field,
210+
use :ref:`query operators <query-selectors>` in the
211+
:ref:`query filter document <document-query-filter>`:
212+
213+
.. code-block::
214+
215+
{ <array field>: { <operator1>: <value1>, ... } }
216+
217+
For example, the following operation uses the
218+
:query:`$nin` operator to query for all documents
219+
where the ``genres`` field does not contain ``Drama``.
220+
221+
.. code-block::
222+
223+
{ genres: { $nin: ["Drama"] } }
224+
225+
.. tab:: Specify Multiple Conditions
226+
:tabid: multiple
227+
228+
When specifying compound conditions on array elements, you can specify
229+
the query such that either a single array element meets these condition
230+
or any combination of array elements meets the conditions.
231+
232+
Query an Array with Compound Filter Conditions on the Array Elements
233+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
234+
235+
The following example queries for documents where the ``cast``
236+
array contains elements that in some combination satisfy the query
237+
conditions. For example, the following filter uses the :query:`$regex`
238+
and :query:`$eq` operators to return documents where a single array element
239+
ends in ``Olsen`` and another element equals ``Mary-Kate Olsen`` or
240+
a single element that satisfies both conditions:
241+
242+
.. code-block::
243+
244+
{ cast: { $regex: "Olsen$", $eq: "Mary-Kate Olsen" } }
245+
246+
This query filter returns movies that include ``Mary-Kate Olsen`` in
247+
their cast, and movies that include both ``Mary-Kate Olsen`` and
248+
``Ashley Olsen`` in their cast.
249+
250+
Query for an Array Element that Meets Multiple Criteria
251+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
252+
253+
Use :query:`$elemMatch` operator to specify multiple criteria on the
254+
elements of an array such that at least one array element satisfies all
255+
the specified criteria.
256+
257+
The following example uses the :query:`$elemMatch` and :query:`$ne`
258+
operators to query for documents where the ``languages`` array contains
259+
at least one element that is both not ``null`` and does not equal ``English``.
260+
261+
.. code-block::
262+
263+
{ languages: { $elemMatch: { $ne: null, $ne: "English" } } }
264+
265+
Query for an Element by the Array Index Position
266+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
267+
268+
Using :term:`dot notation`, you can specify query conditions for an
269+
element at a particular index or position of the array. The array uses
270+
zero-based indexing.
271+
272+
.. note::
273+
274+
When querying using dot notation, the field and nested field must be
275+
inside quotation marks.
276+
277+
The following example uses the :query:`$ne` operator to query
278+
for all documents where the first element in the ``countries``
279+
array is not equal to ``USA``:
280+
281+
.. code-block::
282+
283+
{ "countries.0": { $ne: "USA" }
284+
285+
Query an Array by Array Length
286+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
287+
288+
Use the :query:`$size` operator to query for arrays by number of
289+
elements. For example, the following selects documents where the array
290+
``genres`` has 3 elements.
291+
292+
.. code-block::
293+
294+
{ genres: { $size: 3 } }
295+
141296
Additional Query Tutorials
142297
--------------------------
143298

0 commit comments

Comments
 (0)