Skip to content

Commit f57bf00

Browse files
kyuan-mongodbkyuan-mongodb
authored
DOCSP-18241 crud distinct page (#74)
* added CRUD Distinct page
1 parent 6233f4d commit f57bf00

File tree

5 files changed

+185
-4
lines changed

5 files changed

+185
-4
lines changed

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

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

77
- :doc:`/fundamentals/crud/read-operations/count`
88
- :doc:`/fundamentals/crud/read-operations/retrieve`
9+
- :doc:`/fundamentals/crud/read-operations/distinct`
910
- :doc:`/fundamentals/crud/read-operations/sort`
1011
- :doc:`/fundamentals/crud/read-operations/skip`
1112
- :doc:`/fundamentals/crud/read-operations/limit`
@@ -21,6 +22,7 @@ Read Operations
2122

2223
/fundamentals/crud/read-operations/count
2324
/fundamentals/crud/read-operations/retrieve
25+
/fundamentals/crud/read-operations/distinct
2426
/fundamentals/crud/read-operations/sort
2527
/fundamentals/crud/read-operations/skip
2628
/fundamentals/crud/read-operations/limit

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

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
========================
2+
Retrieve Distinct Values
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 retrieve distinct values for a
17+
specified field across a single collection.
18+
19+
Sample Data
20+
~~~~~~~~~~~
21+
22+
To run the examples in this guide, load the sample data into the
23+
``ratings`` collection of the ``tea`` database with the following
24+
snippet:
25+
26+
.. literalinclude:: /includes/fundamentals/code-snippets/CRUD/distinctValues.go
27+
:language: go
28+
:dedent:
29+
:start-after: begin insert docs
30+
:end-before: end insert docs
31+
32+
.. include:: /includes/fundamentals/automatic-db-coll-creation.rst
33+
34+
Each document contains a rating for a type of tea that corresponds to
35+
the ``type`` and ``rating`` fields.
36+
37+
Distinct
38+
--------
39+
40+
To retrieve distinct values for a specified field across a single
41+
collection, pass the following parameters to the ``Distinct()``
42+
function:
43+
44+
- The field name you want distinct values for
45+
- A ``non-nil`` query filter specifying which documents to match
46+
47+
.. tip::
48+
49+
If you specify an empty query filter, the function matches all the
50+
documents in a collection.
51+
52+
Modify Behavior
53+
~~~~~~~~~~~~~~~
54+
55+
You can modify the behavior of the ``Distinct()`` function by
56+
passing in a ``DistinctOptions``. If you don't specify a
57+
``DistinctOptions``, the driver uses the default values for each
58+
option.
59+
60+
The ``DistinctOptions`` type allows you to configure options
61+
with the following functions:
62+
63+
.. list-table::
64+
:widths: 30 70
65+
:header-rows: 1
66+
67+
* - Function
68+
- Description
69+
70+
* - ``SetCollation()``
71+
- | The type of language collation to use when sorting results.
72+
| Default: ``nil``
73+
74+
* - ``SetMaxTime()``
75+
- | The maximum amount of time that the query can run on the server.
76+
| Default: ``nil``
77+
78+
Example
79+
```````
80+
81+
The following example matches all documents and prints the distinct values
82+
of the ``type`` field using the ``Distinct()`` function:
83+
84+
.. literalinclude:: /includes/fundamentals/code-snippets/CRUD/distinctValues.go
85+
:language: go
86+
:dedent:
87+
:start-after: begin distinct
88+
:end-before: end distinct
89+
90+
After running this example, the output resembles the following:
91+
92+
.. code-block:: none
93+
:copyable: false
94+
95+
Earl Grey
96+
Masala
97+
Matcha
98+
Oolong
99+
100+
Additional Information
101+
----------------------
102+
103+
For a runnable example of retrieving distinct values, see the
104+
:doc:`Retrieve Distinct Values of a Field </usage-examples/distinct>`
105+
usage example.
106+
107+
For information about construting a query filter, see the
108+
:doc:`Specify a Query </fundamentals/crud/query-document>` guide.
109+
110+
API Documentation
111+
~~~~~~~~~~~~~~~~~
112+
113+
For more information on any of the functions or types discussed in this
114+
guide, see the following API Documentation:
115+
116+
- `Distinct() <{+api+}/mongo#Collection.Distinct>`__
117+
- `DistinctOptions <{+api+}/mongo/options#DistinctOptions>`__

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -212,7 +212,7 @@ following functions:
212212
| Default: ``nil``
213213

214214
* - ``SetMaxTime()``
215-
- | The maximum amount of time to allow the query to run.
215+
- | The maximum amount of time that the query can run on the server.
216216
| Default: ``nil``
217217

218218
* - ``SetMaxAwaitTime()``

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

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
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("DRIVER_REF_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+
if err != nil {
22+
panic(err)
23+
}
24+
defer func() {
25+
if err = client.Disconnect(context.TODO()); err != nil {
26+
panic(err)
27+
}
28+
}()
29+
30+
client.Database("tea").Collection("ratings").Drop(context.TODO())
31+
32+
// begin insert docs
33+
coll := client.Database("tea").Collection("ratings")
34+
docs := []interface{}{
35+
bson.D{{"type", "Masala"}, {"rating", 10}},
36+
bson.D{{"type", "Matcha"}, {"rating", 7}},
37+
bson.D{{"type", "Masala"}, {"rating", 4}},
38+
bson.D{{"type", "Oolong"}, {"rating", 9}},
39+
bson.D{{"type", "Matcha"}, {"rating", 5}},
40+
bson.D{{"type", "Earl Grey"}, {"rating", 8}},
41+
bson.D{{"type", "Oolong"}, {"rating", 3}},
42+
bson.D{{"type", "Matcha"}, {"rating", 6}},
43+
bson.D{{"type", "Earl Grey"}, {"rating", 4}},
44+
}
45+
46+
result, err := coll.InsertMany(context.TODO(), docs)
47+
if err != nil {
48+
panic(err)
49+
}
50+
fmt.Printf("Number of documents inserted: %d\n", len(result.InsertedIDs))
51+
//end insert docs
52+
53+
// begin distinct
54+
results, err := coll.Distinct(context.TODO(), "type", bson.D{})
55+
if err != nil {
56+
panic(err)
57+
}
58+
59+
for _, result := range results {
60+
fmt.Println(result)
61+
}
62+
// end distinct
63+
}

‎source/usage-examples/distinct.txt

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -42,9 +42,8 @@ After you run the full example, it returns an empty slice of an
4242
Additional Information
4343
----------------------
4444

45-
..
46-
For more information on retrieving distinct values, see our guide on
47-
<TODO: Distinct Fundamentals>.
45+
For more information on retrieving distinct values, see our guide on
46+
:doc:`retrieving distinct values </fundamentals/crud/read-operations/distinct>`.
4847

4948
API Documentation
5049
~~~~~~~~~~~~~~~~~

0 commit comments

Comments
 (0)