Skip to content

Commit 2cd338a

Browse files
rustagirrustagir
authored
DOCSP-38758: filters builders (#27)
* DOCSP-38758: filters builders * fix toc * landing page snooty.toml
1 parent aec3939 commit 2cd338a

File tree

4 files changed

+325
-3
lines changed

4 files changed

+325
-3
lines changed

‎snooty.toml

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,8 @@ sharedinclude_root = "https://raw.githubusercontent.com/10gen/docs-shared/main/"
1010
toc_landing_pages = [
1111
"/bson",
1212
"/tutorials/connect",
13-
"/tutorials/write-ops"
13+
"/tutorials/write-ops",
14+
"/builders",
1415
]
1516

1617
[constants]

‎source/builders.txt

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
.. _scala-builders:
2+
3+
========
4+
Builders
5+
========
6+
7+
.. toctree::
8+
9+
/builders/filters/
10+
11+
The {+driver-short+} provides the following classes that make it easier to use
12+
the CRUD API:
13+
14+
- :ref:`scala-builders-filters`: Support for building query filters
15+
16+
.. TODO replace with links
17+
18+
- Projections: Support for building projections
19+
- Sorts: Support for building sort criteria
20+
- Aggregation: Support for building aggregation pipelines
21+
- Updates: Support for building updates
22+
- Indexes: Support for creating index keys
23+
24+
.. important::
25+
26+
Builders make use of the ``Bson`` helper. This type, unlike the
27+
``Document`` type, is not type-safe. Instead, conversion to BSON is
28+
done by using :driver:`Codecs and the CodecRegistry
29+
</java/sync/current/fundamentals/data-formats/codecs/>`.

‎source/builders/filters.txt

Lines changed: 291 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,291 @@
1+
.. _scala-builders-filters:
2+
3+
=======
4+
Filters
5+
=======
6+
7+
.. facet::
8+
:name: genre
9+
:values: reference
10+
11+
.. meta::
12+
:keywords: code example, match, criteria
13+
14+
.. contents:: On this page
15+
:local:
16+
:backlinks: none
17+
:depth: 2
18+
:class: singlecol
19+
20+
The ``Filters`` class provides static factory methods for the
21+
MongoDB query operators. Each method returns an instance of the ``Bson``
22+
type, which can in turn be passed to any method that expects a query
23+
filter.
24+
25+
You can import the methods of the ``Filters``
26+
class statically, as shown in the following code:
27+
28+
.. code-block:: scala
29+
30+
import org.mongodb.scala.model.Filters._
31+
32+
The examples in this guide assume this static import.
33+
34+
Comparison
35+
----------
36+
37+
The comparison operator methods include the following:
38+
39+
- ``eq``: Matches values that are equal to a specified value. Aliased to
40+
``equal`` as ``eq`` is a reserved word.
41+
- ``gt``: Matches values that are greater than a specified value.
42+
- ``gte``: Matches values that are greater than or equal to a specified value.
43+
- ``lt``: Matches values that are less than a specified value.
44+
- ``lte``: Matches values that are less than or equal to a specified value.
45+
- ``ne``: Matches all values that are not equal to a specified value.
46+
Aliased to ``notEqual`` as ``neq`` is a reserved word.
47+
- ``in``: Matches any of the values specified in an array.
48+
- ``nin``: Matches none of the values specified in an array.
49+
- ``empty``: Matches all the documents.
50+
51+
Examples
52+
~~~~~~~~
53+
54+
The following example creates a filter that selects all documents where the value
55+
of the ``qty`` field is ``20``:
56+
57+
.. code-block:: scala
58+
59+
`eq`("qty", 20)
60+
equal("qty", 20)
61+
62+
The following example creates a filter that selects all documents where
63+
the value of the ``qty`` field is either ``5`` or ``15``:
64+
65+
.. code-block:: scala
66+
67+
in("qty", 5, 15)
68+
69+
The following example creates a filter that selects all documents because the
70+
filter is empty:
71+
72+
.. code-block:: scala
73+
74+
empty()
75+
76+
Logical
77+
-------
78+
79+
The logical operator methods include the following:
80+
81+
- ``and``: Joins filters with a logical ``AND`` and selects all documents
82+
that match the conditions of both filters.
83+
- ``or``: Joins filters with a logical ``OR`` and selects all documents
84+
that match the conditions of either filter.
85+
- ``not``: Inverts the effect of a query expression and selects
86+
documents that do not match the filter.
87+
- ``nor``: Joins filters with a logical ``NOR`` and selects all documents
88+
that fail to match both filters.
89+
90+
Examples
91+
~~~~~~~~
92+
93+
The following example creates a filter that selects all documents where the value
94+
of the ``qty`` field is greater than ``20`` and the value of the ``user`` field
95+
is ``"jdoe"``:
96+
97+
.. code-block:: scala
98+
99+
and(gt("qty", 20), equal("user", "jdoe"))
100+
101+
The ``and()`` method generates an ``$and`` operator only if necessary, as the query
102+
language implicitly adds together all the elements in a filter. The
103+
preceding example renders as the following:
104+
105+
.. code-block:: json
106+
107+
{
108+
"qty" : { "$gt" : 20 },
109+
"user" : "jdoe"
110+
}
111+
112+
The following example creates a filter that selects all documents where the ``price``
113+
field value equals ``0.99`` or ``1.99``, and either the ``sale`` field value is
114+
``true`` or the ``qty`` field value is less than ``20``:
115+
116+
.. code-block:: scala
117+
118+
and(or(equal("price", 0.99), equal("price", 1.99)
119+
or(equal("sale", true), lt("qty", 20)))
120+
121+
This query cannot be constructed using an implicit ``$and`` operation,
122+
because it uses the ``$or`` operator more than once. This query renders
123+
to the following:
124+
125+
.. code-block:: json
126+
127+
{
128+
"$and" :
129+
[
130+
{ "$or" : [ { "price" : 0.99 }, { "price" : 1.99 } ] },
131+
{ "$or" : [ { "sale" : true }, { "qty" : { "$lt" : 20 } } ] }
132+
]
133+
}
134+
135+
Arrays
136+
------
137+
138+
The array operator methods include the following:
139+
140+
- ``all``: Matches arrays that contain all elements specified in the query.
141+
- ``elemMatch``: Selects documents if an element in the array field matches
142+
all the specified ``$elemMatch`` conditions.
143+
- ``size``: Selects documents if the array field is a specified size.
144+
145+
Examples
146+
~~~~~~~~
147+
148+
The following example selects documents with a ``tags`` array containing
149+
both ``"ssl"`` and ``"security"``:
150+
151+
.. code-block:: scala
152+
153+
all("tags", "ssl", "security")
154+
155+
Elements
156+
--------
157+
158+
The elements operator methods include the following:
159+
160+
- ``exists``: Selects documents that have the specified field.
161+
- ``type``: Selects documents if a field is of the specified type.
162+
Aliased to ``bsonType`` as ``type`` is a reserved word.
163+
164+
Examples
165+
~~~~~~~~
166+
167+
The following example selects documents that contain a ``qty`` field
168+
and the value of this field does not equal ``5`` or ``15``:
169+
170+
.. code-block:: scala
171+
172+
and(exists("qty"), nin("qty", 5, 15))
173+
174+
Evaluation
175+
----------
176+
177+
The evaluation operator methods include the following:
178+
179+
- ``mod``: Performs a modulo operation on the value of a field and
180+
selects documents with a specified result.
181+
- ``regex``: Selects documents where values match a specified regular expression.
182+
- ``text``: Selects documents matching a full-text search expression.
183+
- ``where``: Matches documents that satisfy a JavaScript expression.
184+
185+
Examples
186+
~~~~~~~~
187+
188+
The following example assumes a collection that has a text index in the field
189+
``abstract``. It selects documents that have an ``abstract`` field containing the
190+
term ``"coffee"``:
191+
192+
.. code-block:: scala
193+
194+
text("coffee")
195+
196+
Text indexes allow case-sensitive searches. The following example selects
197+
documents that have an ``abstract`` field containing the exact term ``"coffee"``:
198+
199+
.. code-block:: scala
200+
201+
text("coffee", TextSearchOptions().caseSensitive(true))
202+
203+
Text indexes allow diacritic-sensitive searches. This example selects
204+
documents that have an ``abstract`` field containing the exact term ``"café"``:
205+
206+
.. code-block:: scala
207+
208+
text("café", TextSearchOptions().diacriticSensitive(true))
209+
210+
Bitwise
211+
-------
212+
213+
The bitwise operator methods include the following:
214+
215+
- ``bitsAllSet``: Selects documents where all the specified bits of a
216+
field are set.
217+
- ``bitsAllClear``: Selects documents where all the specified bits of a
218+
field are clear.
219+
- ``bitsAnySet``: Selects documents where at least one of the specified
220+
bits of a field are set.
221+
- ``bitsAnyClear``: Selects documents where at least one of the
222+
specified bits of a field are clear.
223+
224+
Examples
225+
~~~~~~~~
226+
227+
The example selects documents that have a ``bitField`` field with bits set
228+
at positions of the corresponding bitmask ``50`` (``00110010``):
229+
230+
.. code-block:: scala
231+
232+
bitsAllSet("bitField", 50)
233+
234+
Geospatial
235+
----------
236+
237+
The geospatial operator methods include the following:
238+
239+
- ``geoWithin``: Selects all documents containing a field whose value is
240+
a ``GeoJSON`` geometry that falls within a bounding ``GeoJSON``
241+
geometry.
242+
- ``geoWithinBox``: Selects all documents containing a field with grid
243+
coordinates data that exist entirely within the specified box.
244+
- ``geoWithinPolygon``: Selects all documents containing a field with
245+
grid coordinates data that exist entirely within the specified
246+
polygon.
247+
- ``geoWithinCenter``: Selects all documents containing a field with
248+
grid coordinates data that exist entirely within the specified circle.
249+
- ``geoWithinCenterSphere``: Selects geometries containing a field with
250+
geospatial data (``GeoJSON`` or legacy coordinate pairs) that exist
251+
entirely within the specified circle, using spherical geometry.
252+
- ``geoIntersects``: Selects geometries that intersect with a
253+
``GeoJSON`` geometry. The ``2dsphere`` index supports ``$geoIntersects``.
254+
- ``near``: Returns geospatial objects in proximity to a point. Requires
255+
a geospatial index. The ``2dsphere`` and ``2d`` indexes support ``$near``.
256+
- ``nearSphere``: Returns geospatial objects in proximity to a point on
257+
a sphere. Requires a geospatial index. The ``2dsphere`` and ``2d`` indexes
258+
support ``$nearSphere``.
259+
260+
To make it easier to construct ``GeoJSON``-based filters, the driver
261+
also includes a full ``GeoJSON`` class hierarchy:
262+
263+
- ``Point``: Representation of a ``GeoJSON`` ``Point``
264+
- ``MultiPoint``: Representation of a ``GeoJSON`` ``MultiPoint``
265+
- ``LineString``: Representation of a ``GeoJSON`` ``LineString``
266+
- ``MultiLineString``: Representation of a ``GeoJSON`` ``MultiLineString``
267+
- ``Polygon``: Representation of a ``GeoJSON`` ``Polygon``
268+
- ``MultiPolygon``: Representation of a ``GeoJSON`` ``MultiPolygon``
269+
- ``GeometryCollection``: Representation of a ``GeoJSON`` ``GeometryCollection``
270+
271+
Examples
272+
~~~~~~~~
273+
274+
The following example creates a filter that selects all documents where the ``geo``
275+
field contains a ``GeoJSON`` ``Geometry`` object that falls within the given
276+
polygon:
277+
278+
.. code-block:: scala
279+
280+
val polygon: Polygon = Polygon(Seq(Position(0, 0), Position(4, 0),
281+
Position(4, 4), Position(0, 4),
282+
Position(0, 0)))
283+
geoWithin("geo", polygon)
284+
285+
Similarly, this example creates a filter that selects all documents
286+
where the ``geo`` field contains a ``GeoJSON`` ``Geometry`` object that intersects
287+
the given ``Point``:
288+
289+
.. code-block:: scala
290+
291+
geoIntersects("geo", Point(Position(4, 0)))

‎source/index.txt

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@
1717
/tutorials/
1818
/reference/
1919
/bson/
20+
/builders/
2021
View the Source <https://github.com/mongodb/mongo-java-driver>
2122
API Documentation <{+api+}/index.html>
2223
Previous Versions <https://mongodb.github.io/mongo-java-driver/>
@@ -27,7 +28,7 @@ Introduction
2728
Welcome to the documentation site for the {+driver-long+}, the
2829
official driver for asynchronous stream processing. Download
2930
the driver by following the :ref:`scala-install` guide, then set up a
30-
runnable project by following one of the tutorials.
31+
runnable project by following the :ref:`scala-quickstart` guide.
3132

3233
- :ref:`scala-install`
3334

@@ -39,7 +40,7 @@ runnable project by following one of the tutorials.
3940

4041
- :ref:`scala-bson`
4142

42-
.. - :ref:`scala-builders`
43+
- :ref:`scala-builders`
4344

4445
- `Driver Source GitHub Repository <https://github.com/mongodb/mongo-java-driver>`__
4546

0 commit comments

Comments
 (0)