Skip to content

Commit d30a55c

Browse files
kyuan-mongodbkyuan-mongodb
authored
DOCSP-13837 crud skip (#62)
* added the CRUD Skip page
1 parent 3827fc5 commit d30a55c

File tree

10 files changed

+229
-38
lines changed

10 files changed

+229
-38
lines changed

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,11 +6,11 @@ Read Operations
66

77
- :doc:`/fundamentals/crud/read-operations/retrieve`
88
- :doc:`/fundamentals/crud/read-operations/sort`
9+
- :doc:`/fundamentals/crud/read-operations/skip`
910

1011
..
1112
- :doc:`/fundamentals/crud/read-operations/cursor`
1213
- :doc:`/fundamentals/crud/read-operations/limit`
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`
@@ -20,10 +20,10 @@ Read Operations
2020

2121
/fundamentals/crud/read-operations/retrieve
2222
/fundamentals/crud/read-operations/sort
23+
/fundamentals/crud/read-operations/skip
2324
..
2425
/fundamentals/crud/read-operations/cursor
2526
/fundamentals/crud/read-operations/limit
26-
/fundamentals/crud/read-operations/skip
2727
/fundamentals/crud/read-operations/project
2828
/fundamentals/crud/read-operations/geo
2929
/fundamentals/crud/read-operations/text

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

Lines changed: 1 addition & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -33,13 +33,7 @@ collection of the ``tea`` database:
3333
:start-after: begin insert docs
3434
:end-before: end insert docs
3535

36-
Each document contains a rating for a type of tea, which corresponds to
37-
the ``type`` and ``rating`` fields.
38-
39-
.. note::
40-
41-
Each example truncates the ``ObjectID`` value since the driver
42-
generates them uniquely.
36+
.. include:: /includes/fundamentals/tea-sample-data-ending.rst
4337

4438
.. _retrieve-find:
4539

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

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
=====================
2+
Skip Returned Results
3+
=====================
4+
5+
.. default-domain:: mongodb
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 2
11+
:class: singlecol
12+
13+
Overview
14+
--------
15+
16+
In this guide, you can learn how to skip a specified number of returned
17+
results from read operations.
18+
19+
Sample Data
20+
~~~~~~~~~~~
21+
22+
Run the following snippet to load the documents into the ``ratings``
23+
collection of the ``tea`` database:
24+
25+
.. literalinclude:: /includes/fundamentals/code-snippets/CRUD/skip.go
26+
:language: go
27+
:dedent:
28+
:start-after: begin insertDocs
29+
:end-before: end insertDocs
30+
31+
.. include:: /includes/fundamentals/tea-sample-data-ending.rst
32+
33+
Skip
34+
----
35+
36+
To skip a specified number of returned results from a query, pass the
37+
number of documents you want to skip to the ``SetSkip()`` function of
38+
the read operation's options.
39+
40+
Specify the options as the last parameter to the following read
41+
operation functions:
42+
43+
- ``Find()``
44+
- ``FindOne()``
45+
- ``CountDocuments()``
46+
- ``gridfs.Bucket.Find()``
47+
48+
If the number of documents exceeds the number of matched documents for a
49+
query, that query returns no documents.
50+
51+
.. tip::
52+
53+
Passing in a negative number to the ``SetSkip()`` function results
54+
in a runtime error.
55+
56+
Documents return in a natural order, which can lead to skipping random
57+
documents. To avoid this, use a ``SetSort()`` function before the
58+
``SetSkip()`` function.
59+
60+
Example
61+
~~~~~~~
62+
63+
The following example performs the following actions in order with the
64+
``Find()`` function:
65+
66+
- Sorts all the matched documents in ascending order
67+
- Skips the first two documents
68+
69+
.. literalinclude:: /includes/fundamentals/code-snippets/CRUD/skip.go
70+
:language: go
71+
:dedent:
72+
:start-after: begin skip
73+
:end-before: end skip
74+
75+
After running the preceding example, the output resembles the following:
76+
77+
.. code-block:: none
78+
:copyable: false
79+
80+
//results truncated
81+
[{_id ObjectID("...")} {type Oolong} {rating 7}]
82+
[{_id ObjectID("...")} {type Earl Grey} {rating 8}]
83+
[{_id ObjectID("...")} {type Masala} {rating 10}]
84+
85+
.. tip:: Using Aggregation
86+
87+
You can also include the :manual:`$skip </reference/operator/aggregation/skip/>`
88+
stage to specify a skip in an aggregation pipeline.
89+
90+
The following example specifies the same sort and skip from the
91+
preceding example in an aggregation pipeline:
92+
93+
.. literalinclude:: /includes/fundamentals/code-snippets/CRUD/skip.go
94+
:language: go
95+
:dedent:
96+
:start-after: begin aggregate skip
97+
:end-before: end aggregate skip
98+
99+
Additional Information
100+
----------------------
101+
102+
For more information on performing read operations, see our guide on
103+
:doc:`retrieving data </fundamentals/crud/read-operations/retrieve>`.
104+
105+
For information on specifying a sort, see our guide on :doc:`sorting
106+
results </fundamentals/crud/read-operations/sort>`.
107+
108+
API Documentation
109+
~~~~~~~~~~~~~~~~~
110+
111+
For more information on any of the functions or types discussed in this
112+
guide, see the following API Documentation:
113+
114+
- `Find() <{+api+}/mongo#Collection.Find>`__
115+
- `FindOptions.SetSkip() <{+api+}/mongo/options#FindOptions.SetSkip>`__
116+
- `Aggregate() <{+api+}/mongo#Collection.Aggregate>`__
117+
- `CountDocuments() <{+api+}/mongo#Collection.CountDocuments>`__
118+
- `gridfs.Bucket.Find() <{+api+}/mongo/gridfs#Bucket.Find>`__

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

Lines changed: 5 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -29,27 +29,16 @@ snippet:
2929
:start-after: begin insertDocs
3030
:end-before: end insertDocs
3131

32-
.. tip:: Non-existent Database and Collections
33-
34-
The driver automatically creates the necessary database and/or collection
35-
when you perform a write operation against them if they don't already exist.
36-
37-
Each document contains a rating for a type of tea, which corresponds to
38-
the ``type`` and ``rating`` fields.
39-
40-
.. note::
41-
42-
Each example truncates the ``ObjectID`` value since the driver
43-
generates them uniquely.
32+
.. include:: /includes/fundamentals/tea-sample-data-ending.rst
4433

4534
Sort Direction
4635
--------------
4736

4837
To specify the order of your results, pass an interface specifying the
4938
sort fields and directions to the ``SetSort()`` function of a read
50-
operations' options.
39+
operation's options.
5140

52-
The options you specify are the last parameter to the following read
41+
Specify the options as the last parameter to the following read
5342
operation functions:
5443

5544
- ``Find()``
@@ -181,8 +170,8 @@ After running the preceding example, the output resembles the following:
181170

182171
.. tip:: Using Aggregation
183172

184-
You can also specify a sort in an aggregation pipeline by including
185-
the :manual:`$sort </reference/operator/aggregation/sort/>` stage.
173+
You can also include the :manual:`$sort </reference/operator/aggregation/sort/>`
174+
stage to specify a sort in an aggregation pipeline.
186175

187176
The following example specifies the same sort from the preceding
188177
example in an aggregation pipeline:

‎source/fundamentals/crud/write-operations/delete.txt

Lines changed: 1 addition & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -31,11 +31,7 @@ snippet:
3131
:start-after: begin insertDocs
3232
:end-before: end insertDocs
3333

34-
.. tip:: Non-existent Database and Collections
35-
36-
The driver automatically creates the necessary database and/or collection
37-
when you perform a write operation against them if they don't already
38-
exist.
34+
.. include:: /includes/fundamentals/automatic-db-coll-creation.rst
3935

4036
Each document contains a rating for a type of tea, which corresponds to
4137
the ``type`` and ``rating`` fields.

‎source/includes/fundamentals/automatic-db-coll-creation.rst

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
.. tip:: Non-existent Databases and Collections
2+
3+
The server automatically creates the necessary database and
4+
collection when you perform a write operation against them if they
5+
don't already exist.
6+

‎source/includes/fundamentals/code-snippets/CRUD/skip.go

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
package main
2+
3+
import (
4+
"context"
5+
"fmt"
6+
"log"
7+
"os"
8+
9+
"go.mongodb.org/mongo-driver/bson"
10+
"go.mongodb.org/mongo-driver/mongo"
11+
"go.mongodb.org/mongo-driver/mongo/options"
12+
)
13+
14+
func main() {
15+
var uri string
16+
if uri = os.Getenv("MONGODB_URI"); uri == "" {
17+
log.Fatal("You must set your 'MONGODB_URI' environmental variable. See\n\t https://docs.mongodb.com/drivers/go/current/usage-examples/")
18+
}
19+
20+
client, err := mongo.Connect(context.TODO(), options.Client().ApplyURI(uri))
21+
22+
if err != nil {
23+
panic(err)
24+
}
25+
defer func() {
26+
if err = client.Disconnect(context.TODO()); err != nil {
27+
panic(err)
28+
}
29+
}()
30+
31+
client.Database("tea").Collection("ratings").Drop(context.TODO())
32+
33+
// begin insertDocs
34+
coll := client.Database("tea").Collection("ratings")
35+
docs := []interface{}{
36+
bson.D{{"type", "Masala"}, {"rating", 10}},
37+
bson.D{{"type", "Assam"}, {"rating", 5}},
38+
bson.D{{"type", "Oolong"}, {"rating", 7}},
39+
bson.D{{"type", "Earl Grey"}, {"rating", 8}},
40+
bson.D{{"type", "English Breakfast"}, {"rating", 5}},
41+
}
42+
43+
result, insertErr := coll.InsertMany(context.TODO(), docs)
44+
if insertErr != nil {
45+
panic(insertErr)
46+
}
47+
fmt.Printf("Number of documents inserted: %d\n", len(result.InsertedIDs))
48+
//end insertDocs
49+
50+
fmt.Println("Skip:")
51+
//begin skip
52+
skipFilter := bson.D{}
53+
skipOptions := options.Find().SetSort(bson.D{{"rating", 1}}).SetSkip(2)
54+
55+
skipCursor, skipErr := coll.Find(context.TODO(), skipFilter, skipOptions)
56+
57+
var skipResults []bson.D
58+
if skipErr = skipCursor.All(context.TODO(), &skipResults); skipErr != nil {
59+
panic(skipErr)
60+
}
61+
for _, result := range skipResults {
62+
fmt.Println(result)
63+
}
64+
//end skip
65+
66+
fmt.Println("Aggegation Skip:")
67+
// begin aggregate skip
68+
sortStage := bson.D{{"$sort", bson.D{{"rating", 1}}}}
69+
skipStage := bson.D{{"$skip", 2}}
70+
71+
aggCursor, aggErr := coll.Aggregate(context.TODO(), mongo.Pipeline{sortStage, skipStage})
72+
if aggErr != nil {
73+
panic(aggErr)
74+
}
75+
76+
var aggResults []bson.D
77+
if aggErr = aggCursor.All(context.TODO(), &aggResults); aggErr != nil {
78+
panic(aggErr)
79+
}
80+
for _, result := range aggResults {
81+
fmt.Println(result)
82+
}
83+
// end aggregate skip
84+
}

‎source/includes/fundamentals/tea-sample-data-ending.rst

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
.. include:: /includes/fundamentals/automatic-db-coll-creation.rst
2+
3+
Each document contains a rating for a type of tea that corresponds to
4+
the ``type`` and ``rating`` fields.
5+
6+
.. note::
7+
8+
Each example truncates the ``ObjectID`` value because the driver
9+
generates them uniquely.
10+

‎source/usage-examples/insertMany.txt

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -14,10 +14,7 @@ Example
1414

1515
The following example inserts two documents in the ``haikus`` collection:
1616

17-
.. note:: Non-existent Database and Collections
18-
19-
The driver automatically creates the necessary database and/or collection
20-
when you perform a write operation against them if they don't already exist.
17+
.. include:: /includes/fundamentals/automatic-db-coll-creation.rst
2118

2219
.. literalinclude:: /includes/usage-examples/code-snippets/insertMany.go
2320
:start-after: begin insertMany

‎source/usage-examples/insertOne.txt

Lines changed: 1 addition & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -14,10 +14,7 @@ Example
1414

1515
The following example inserts a document in the ``haikus`` collection:
1616

17-
.. note:: Non-existent Database and Collections
18-
19-
The driver automatically creates the necessary database and/or collection
20-
when you perform a write operation against them if they don't already exist.
17+
.. include:: /includes/fundamentals/automatic-db-coll-creation.rst
2118

2219
.. literalinclude:: /includes/usage-examples/code-snippets/insertOne.go
2320
:start-after: begin insertOne

0 commit comments

Comments
 (0)