Skip to content

Commit 9063297

Browse files
kyuan-mongodbkyuan-mongodb
authored
DOCSP-9560 crud skip (#67)
* added CRUD > Skip Returned Results
1 parent 5446a79 commit 9063297

File tree

4 files changed

+229
-145
lines changed

4 files changed

+229
-145
lines changed

‎source/fundamentals/crud/read-operations.txt

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,10 +7,10 @@ Read Operations
77
- :doc:`/fundamentals/crud/read-operations/cursor`
88
- :doc:`/fundamentals/crud/read-operations/sort`
99
- :doc:`/fundamentals/crud/read-operations/limit`
10+
- :doc:`/fundamentals/crud/read-operations/skip`
1011

1112
..
1213
- :doc:`/fundamentals/crud/read-operations/retrieve`
13-
- :doc:`/fundamentals/crud/read-operations/skip`
1414
- :doc:`/fundamentals/crud/read-operations/project`
1515
- :doc:`/fundamentals/crud/read-operations/geo`
1616
- :doc:`/fundamentals/crud/read-operations/text`
@@ -21,8 +21,8 @@ Read Operations
2121
/fundamentals/crud/read-operations/cursor
2222
/fundamentals/crud/read-operations/sort
2323
/fundamentals/crud/read-operations/limit
24+
/fundamentals/crud/read-operations/skip
2425
..
25-
/fundamentals/crud/read-operations/skip
2626
/fundamentals/crud/read-operations/retrieve
2727
/fundamentals/crud/read-operations/project
2828
/fundamentals/crud/read-operations/geo

‎source/fundamentals/crud/read-operations/skip.txt

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
=====================
2+
Skip Returned Results
3+
=====================
4+
5+
.. default-domain:: mongodb
6+
7+
In this guide, we show you how to skip a specified number of returned results.
8+
9+
You can skip results on the returned results of a query by using the
10+
``skip()`` method. You can also skip documents at a specific stage in an
11+
aggregation pipeline by specifying a ``$skip`` aggregation stage.
12+
13+
The ``skip()`` method takes an integer that specifies the number of documents
14+
to omit from the beginning of the list of documents returned by the
15+
:java-docs:`FindIterable </apidocs/mongodb-driver-sync/com/mongodb/client/FindIterable.html#skip(int)>`.
16+
17+
You can use the ``skip()`` method to skip the first two documents as follows:
18+
19+
.. code-block:: java
20+
21+
collection.find().skip(2);
22+
23+
:java-docs:`Aggregates.skip() </apidocs/mongodb-driver-core/com/mongodb/client/model/Aggregates.html#skip(int)>`
24+
is an optional stage in the aggregation pipeline that specifies how many
25+
documents to omit from the beginning of the results of the prior stage.
26+
27+
You can use the ``Aggregates.skip()`` method to skip the first two documents as follows:
28+
29+
.. code-block:: java
30+
31+
import com.mongodb.client.model.Aggregates;
32+
33+
collection.aggregate(Arrays.asList(Aggregates.match(), Aggregates.skip(2)));
34+
35+
Examples
36+
~~~~~~~~
37+
38+
The following example is about a paint store that sells eight different
39+
colors of paint. The best colors sell quicker than the other colors.
40+
One day, a customer asks what the three best-selling (lowest inventory)
41+
colors are. The paint store keeps track of inventory in the ``qty``
42+
field in their ``paint_inventory`` collection:
43+
44+
.. code-block:: json
45+
46+
{ "_id": 1, "color": "red", "qty": 5 }
47+
{ "_id": 2, "color": "purple", "qty": 10 }
48+
{ "_id": 3, "color": "blue", "qty": 9 }
49+
{ "_id": 4, "color": "white", "qty": 6 }
50+
{ "_id": 5, "color": "yellow", "qty": 11 }
51+
{ "_id": 6, "color": "pink", "qty": 3 }
52+
{ "_id": 7, "color": "green", "qty": 8 }
53+
{ "_id": 8, "color": "orange", "qty": 7 }
54+
55+
56+
To address the scenario, the paint store needs to query the
57+
``paint_inventory`` collection with an empty filter, sort the documents
58+
by ``qty`` field and omit the first five results.
59+
60+
Using the ``skip()`` method:
61+
````````````````````````````
62+
63+
.. literalinclude:: /includes/fundamentals/code-snippets/Skip.java
64+
:language: java
65+
:dedent:
66+
:start-after: begin skipExample
67+
:end-before: end skipExample
68+
69+
- The ``find()`` method returns all documents.
70+
- The ``sort()`` method specifies documents to display from highest to lowest based on the ``qty`` field.
71+
- The ``skip()`` method specifies to omit the first five documents.
72+
73+
Using ``Aggregates.skip()``:
74+
````````````````````````````
75+
76+
.. literalinclude:: /includes/fundamentals/code-snippets/Skip.java
77+
:language: java
78+
:dedent:
79+
:start-after: begin skipAggregateExample
80+
:end-before: end skipAggregateExample
81+
82+
- The ``match()`` stage returns all documents.
83+
- The ``sort()`` stage specifies documents to display from highest to lowest based on the ``qty`` field.
84+
- The ``skip()`` stage specifies to omit the first five documents.
85+
86+
The following shows the output of both queries specified above:
87+
88+
.. code-block:: json
89+
:copyable: false
90+
91+
{ "_id": 4, "color": "white", "qty": 6 }
92+
{ "_id": 1, "color": "red", "qty": 5 }
93+
{ "_id": 6, "color": "pink", "qty": 3 }
94+
95+
After the paint store runs the query, they find the three best-selling colors are pink,
96+
red, and white.
97+
98+
.. note::
99+
If the value of skip is greater than or equal to the number of matched
100+
documents for a query, that query returns no documents.
101+
102+
If the ``skip()`` method from the example above skips the first nine
103+
documents, no results would return since the specified quantity
104+
exceeds the number of matched documents.
105+
106+
.. literalinclude:: /includes/fundamentals/code-snippets/Skip.java
107+
:language: java
108+
:dedent:
109+
:start-after: begin noResultsExample
110+
:end-before: end noResultsExample

‎source/includes/fundamentals/code-snippets/Indexes.java

Lines changed: 0 additions & 143 deletions
This file was deleted.

‎source/includes/fundamentals/code-snippets/Skip.java

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
package docs;
2+
3+
import com.mongodb.client.MongoClient;
4+
import com.mongodb.client.MongoClients;
5+
import com.mongodb.client.MongoCollection;
6+
import com.mongodb.client.MongoDatabase;
7+
8+
import org.bson.Document;
9+
import org.bson.conversions.Bson;
10+
11+
import java.util.ArrayList;
12+
import java.util.Arrays;
13+
import java.util.List;
14+
15+
import com.mongodb.client.model.Filters;
16+
import com.mongodb.client.model.Sorts;
17+
import com.mongodb.client.model.Aggregates;
18+
19+
public class Skip {
20+
21+
private final MongoCollection<Document> collection;
22+
private final MongoClient mongoClient;
23+
private final MongoDatabase database;
24+
25+
private Skip() {
26+
final String uri = System.getenv("DRIVER_REF_URI");
27+
28+
mongoClient = MongoClients.create(uri);
29+
database = mongoClient.getDatabase("crudOps");
30+
collection = database.getCollection("skip");
31+
// end declaration
32+
}
33+
34+
public static void main (String [] args){
35+
Skip skip = new Skip();
36+
// skip.setupPaintCollection();
37+
skip.skipExample();
38+
skip.noResultsExample();
39+
}
40+
41+
private void skipExample(){
42+
// begin skipExample
43+
import com.mongodb.client.model.Filters;
44+
import com.mongodb.client.model.Sorts;
45+
46+
// <MongoCollection setup code here>
47+
48+
Bson filter = Filters.empty();
49+
collection.find(filter)
50+
.sort(Sorts.descending("qty"))
51+
.skip(5)
52+
.forEach(doc -> System.out.println(doc.toJson()));
53+
// end skipExample
54+
}
55+
56+
private void noResultsExample(){
57+
// begin noResultsExample
58+
Bson filter = Filters.empty();
59+
collection.find(filter)
60+
.sort(Sorts.descending("qty"))
61+
.skip(9)
62+
.forEach(doc -> System.out.println(doc.toJson()));
63+
// end noResultsExample
64+
}
65+
66+
private void skipAggregateExample(){
67+
// begin skipAggregateExample
68+
import com.mongodb.client.model.Filters;
69+
import com.mongodb.client.model.Sorts;
70+
import com.mongodb.client.model.Aggregates;
71+
72+
// <MongoCollection setup code here>
73+
74+
Bson filter = Filters.empty();
75+
collection.aggregate(Arrays.asList(
76+
Aggregates.match(filter),
77+
Aggregates.sort(Sorts.descending("qty")),
78+
Aggregates.skip(5)))
79+
.forEach(doc -> System.out.println(doc.toJson()));
80+
// end skipAggregateExample
81+
}
82+
83+
private void setupPaintCollection() {
84+
85+
// List<Document> filterdata = new ArrayList<>();
86+
87+
// Document p1 = new Document("_id", 1).append("color", "red").append("qty", 5);
88+
// Document p2 = new Document("_id", 2).append("color", "purple").append("qty", 10);
89+
// Document p3 = new Document("_id", 3).append("color", "blue").append("qty", 9);
90+
// Document p4 = new Document("_id", 4).append("color", "white").append("qty", 6);
91+
// Document p5 = new Document("_id", 5).append("color", "yellow").append("qty", 11);
92+
// Document p6 = new Document("_id", 6).append("color", "pink").append("qty", 3);
93+
// Document p7 = new Document("_id", 7).append("color", "green").append("qty", 8);
94+
// Document p8 = new Document("_id", 8).append("color", "orange").append("qty", 7);
95+
96+
// filterdata.add(p1);
97+
// filterdata.add(p2);
98+
// filterdata.add(p3);
99+
// filterdata.add(p4);
100+
// filterdata.add(p5);
101+
// filterdata.add(p6);
102+
// filterdata.add(p7);
103+
// filterdata.add(p8);
104+
105+
collection.drop();
106+
collection.insertMany(Arrays.asList(
107+
new Document("_id", 1).append("color", "red").append("qty", 5),
108+
new Document("_id", 2).append("color", "purple").append("qty", 10),
109+
new Document("_id", 3).append("color", "blue").append("qty", 9),
110+
new Document("_id", 4).append("color", "white").append("qty", 6),
111+
new Document("_id", 5).append("color", "yellow").append("qty", 11),
112+
new Document("_id", 6).append("color", "pink").append("qty", 3),
113+
new Document("_id", 7).append("color", "green").append("qty", 8),
114+
new Document("_id", 8).append("color", "orange").append("qty", 7)
115+
));
116+
}
117+
}

0 commit comments

Comments
 (0)