Skip to content

Commit 36884a3

Browse files
davidhou17davidhou17
authored
(DOCSP-32019): Add Atlas UI procedure to Query Arrays page (#4898)
* Add Atlas UI procedure * copy review feedback
1 parent 3d687aa commit 36884a3

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
@@ -22,14 +22,13 @@ Query an Array
2222
:backlinks: none
2323
:depth: 1
2424

25-
----------
25+
You can query arrays in MongoDB using the following methods:
2626

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

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

32-
----------
31+
.. include:: /includes/language-selector-instructions.rst
3332

3433
.. tabs-selector:: drivers
3534

@@ -141,7 +140,163 @@ elements. For example, the following selects documents where the array
141140

142141
.. include:: /includes/driver-examples/driver-example-query-28.rst
143142

143+
.. _query-array-atlas-ui:
144144

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

0 commit comments

Comments
 (0)