Skip to content

Commit 1239596

Browse files
jyeminjyemin
committed
Added reference documentation for the Filters builder methods.
1 parent b1ec094 commit 1239596

File tree

2 files changed

+219
-0
lines changed

2 files changed

+219
-0
lines changed

‎docs/reference/content/builders/filters.md

Lines changed: 205 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,205 @@
1+
+++
2+
date = "2015-03-19T14:27:51-04:00"
3+
title = "Filters"
4+
[menu.main]
5+
parent = "Builders"
6+
weight = 10
7+
pre = "<i class='fa'></i>"
8+
+++
9+
10+
## Filters
11+
12+
The [`Filters`]({{< apiref "com/mongodb/client/model/Filters" >}}) class provides static factory methods for all the MongoDB query
13+
operators. Each method returns an instance of the [`Bson`]({{< relref "bson/documents.md#bson" >}}) type, which can in turn be passed to
14+
any method that expects a query filter.
15+
16+
For brevity, you may choose to import the methods of the `Filters` class statically:
17+
18+
```java
19+
import com.mongodb.client.model.Filters.*;
20+
```
21+
22+
All the examples below assume this static import.
23+
24+
### Comparison
25+
26+
The comparison operator methods include:
27+
28+
- `eq`: Matches values that are equal to a specified value.
29+
- `gt`: Matches values that are greater than a specified value.
30+
- `gte`: Matches values that are greater than or equal to a specified value.
31+
- `lt`: Matches values that are less than a specified value.
32+
- `lte`: Matches values that are less than or equal to a specified value.
33+
- `ne`: Matches all values that are not equal to a specified value.
34+
- `in`: Matches any of the values specified in an array.
35+
- `nin`: Matches none of the values specified in an array.
36+
37+
#### Examples
38+
39+
This example creates a filter that selects all documents where the value of the `qty` field equals `20`:
40+
41+
```java
42+
eq("qty", 20)
43+
```
44+
45+
which will render as:
46+
47+
```json
48+
{
49+
"qty" : 20
50+
}
51+
```
52+
53+
This example creates a filter that selects all documents where the value of the `qty` field is either `5` or `20`:
54+
55+
```java
56+
in("qty", 5, 15)
57+
```
58+
59+
### Logical
60+
61+
The logical operator methods include:
62+
63+
- `and`: Joins filters with a logical AND and selects all documents that match the conditions of both filters.
64+
- `or`: Joins filters with a logical OR and selects all documents that match the conditions of either filters.
65+
- `not`: Inverts the effect of a query expression and selects documents that do not match the filter.
66+
- `nor`: Joins filters with a logical NOR and selects all documents that fail to match both filters.
67+
68+
#### Examples
69+
70+
This example creates a filter that selects all documents where ther value of the `qty` field is greater than `20` and the value of the
71+
`user` field equals `"jdoe"`:
72+
73+
```java
74+
and(gt("qty", 20), eq("user", "jdoe"))
75+
```
76+
77+
The `and` method generates a `$and` operator only if necessary, as the query language implicity ands together all the elements in a
78+
filter. So the above example will render as:
79+
80+
```json
81+
{
82+
"qty" : { "$gt" : 20 },
83+
"user" : "jdoe"
84+
}
85+
```
86+
87+
This example creates a filter that selects all documents where the `price` field value equals `0.99` or `1.99`; and the `sale` field value
88+
is equal to `true` or the `qty` field value is less than `20`:
89+
90+
```java
91+
and(or(eq("price", 0.99), eq("price", 1.99)
92+
or(eq("sale", true), lt("qty", 20)))
93+
```
94+
95+
This query cannot be constructed using an implicit and operation, because it uses the `$or` operator more than once. So it will render as:
96+
97+
```json
98+
{
99+
"$and" :
100+
[
101+
{ "$or" : [ { "price" : 0.99 }, { "price" : 1.99 } ] },
102+
{ "$or" : [ { "sale" : true }, { "qty" : { "$lt" : 20 } } ] }
103+
]
104+
}
105+
```
106+
107+
### Arrays
108+
109+
The array operator methods include:
110+
111+
- `all`: Matches arrays that contain all elements specified in the query
112+
- `elemMatch`: Selects documents if element in the array field matches all the specified $elemMatch conditions
113+
- `size`: Selects documents if the array field is a specified size
114+
115+
#### Examples
116+
117+
This example selects documents with a `tags` array containing both `"ssl"` and `"security"`:
118+
119+
```java
120+
all("tags", Arrays.asList("ssl", "security"))
121+
```
122+
123+
### Elements
124+
125+
The elements operator methods include:
126+
127+
- `exists`: Selects documents that have the specified field.
128+
- `type`: Selects documents if a field is of the specified type.
129+
130+
#### Examples
131+
132+
This example selects documents that have a `qty` field and its value does not equal `5` or `15`:
133+
134+
```java
135+
and(exists("qty"), nin("qty", 5, 15))
136+
```
137+
138+
### Evaluation
139+
140+
The evaluation operator methods include:
141+
142+
- `mod`: Performs a modulo operation on the value of a field and selects documents with a specified result.
143+
- `regex`: Selects documents where values match a specified regular expression.
144+
- `text`: Selects documemts matching a full-text search expression.
145+
- `where`: Matches documents that satisfy a JavaScript expression.
146+
147+
#### Examples
148+
149+
This example assumes a collection that has a text index in the field `abstract`. It selects documents that have a `abstract` field
150+
containing the term `coffee`:
151+
152+
```java
153+
text("abstract", "coffee")
154+
```
155+
156+
### Geospatial
157+
158+
The geospatial operator methods include:
159+
160+
- `geoWithin`: Selects all documents containing a field whose value is a GeoJSON geometry that falls within within a bounding GeoJSON
161+
geometry.
162+
- `geoWithinBox`: Selects all documents containing a field with grid coordinates data that exist entirely within the specified box.
163+
- `geoWithinPolygon`: Selects all documents containing a field with grid coordinates data that exist entirely within the specified polygon.
164+
- `geoWithinCenter`: Selects all documents containing a field with grid coordinates data that exist entirely within the specified circle.
165+
- `geoWithinCenterSphere`: Selects geometries containing a field with geospatial data (GeoJSON or legacy coordinate pairs) that exist
166+
entirely within the specified circle, using spherical geometry.
167+
- `geoIntersects`: Selects geometries that intersect with a GeoJSON geometry. The 2dsphere index supports $geoIntersects.
168+
- `near`: Returns geospatial objects in proximity to a point. Requires a geospatial index. The 2dsphere and 2d indexes support $near.
169+
- `nearSphere`: Returns geospatial objects in proximity to a point on a sphere. Requires a geospatial index. The 2dsphere and 2d
170+
indexes support $nearSphere.
171+
172+
To make it easier to construct GeoJSON-based filters, the driver also include a full GeoJSON class hierarchy:
173+
174+
- [`Point`]({{< apiref "com/mongodb/client/model/geojson/Point" >}}): A representation of a GeoJSON Point.
175+
- [`MultiPoint`]({{< apiref "com/mongodb/client/model/geojson/MultiPoint" >}}): A representation of a GeoJSON MultiPoint.
176+
- [`LineString`]({{< apiref "com/mongodb/client/model/geojson/LineString" >}}): A representation of a GeoJSON LineString.
177+
- [`MultiLineString`]({{< apiref "com/mongodb/client/model/geojson/MultiLineString" >}}): A representation of a GeoJSON MultiLineString.
178+
- [`Polygon`]({{< apiref "com/mongodb/client/model/geojson/Polygon" >}}): A representation of a GeoJSON Polygon.
179+
- [`MultiPolygon`]({{< apiref "com/mongodb/client/model/geojson/MultiPolygon" >}}): A representation of a GeoJSON MultiPolygon.
180+
- [`GeometryCollection`]({{< apiref "com/mongodb/client/model/geojson/GeometryCollection" >}}): A representation of a GeoJSON
181+
GeometryCollection.
182+
183+
184+
#### Examples
185+
186+
This example creates a filter that selects all documents where the `geo` field contains a GeoJSON Geometry object that falls within the
187+
given polygon:
188+
189+
```java
190+
Polygon polygon = new Polygon(Arrays.asList(new Position(0, 0),
191+
new Position(4, 0),
192+
new Position(4, 4),
193+
new Position(0, 4),
194+
new Position(0, 0)));
195+
geoWithin('geo', polygon))
196+
```
197+
198+
Similarly, this example creates a filter that selects all documents where the `geo` field contains a GeoJSON Geometry object that
199+
intersects the given Point:
200+
201+
```java
202+
geoIntersects('geo', new Point(new Position(4, 0)))
203+
```
204+
205+

‎docs/reference/content/builders/index.md

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
+++
2+
date = "2015-03-19T12:53:30-04:00"
3+
title = "Builders"
4+
[menu.main]
5+
identifier = "Builders"
6+
weight = 50
7+
pre = "<i class='fa fa-th'></i>"
8+
+++
9+
10+
## Builders
11+
12+
The driver provides several classes that make it easier to use the CRUD API.
13+
14+
- [Filters]({{< relref "filters.md" >}}): Documentation of the driver's support for query filters

0 commit comments

Comments
 (0)