@@ -13,58 +13,49 @@ Database References
13
13
:class: singlecol
14
14
15
15
For many use cases in MongoDB, the denormalized data model where
16
- related data is stored within a single :term:`document <document>` will
17
- be optimal. However, in some cases, it makes sense to store related
16
+ related data is stored within a single :term:`document <document>` is optimal.
17
+ However, in some cases, it makes sense to store related
18
18
information in separate documents, typically in different collections
19
19
or databases.
20
20
21
21
.. important::
22
22
23
- MongoDB 3.2 introduces :pipeline:`$lookup` pipeline stage to perform
23
+ You can use the :pipeline:`$lookup` pipeline stage to perform
24
24
a left outer join to an unsharded collection in the same database.
25
- For more information and examples, see :pipeline:`$lookup`.
26
25
27
- Starting in MongoDB 3.4, you can also use :pipeline:`$graphLookup`
28
- pipeline stage to join an unsharded collection to perform recursive
29
- search. For more information and examples, see
30
- :pipeline:`$graphLookup`.
26
+ You can also use the :pipeline:`$graphLookup` pipeline stage to join an
27
+ unsharded collection to perform recursive search.
31
28
32
29
This page outlines alternative procedures that predate the
33
30
:pipeline:`$lookup` and :pipeline:`$graphLookup` pipeline stages.
34
31
35
- MongoDB applications use one of two methods for relating documents:
32
+ MongoDB applications use one of two methods to relate documents:
36
33
37
- - :ref:`Manual references <document-references>` where you save the
34
+ - :ref:`Manual references <document-references>` save the
38
35
``_id`` field of one document in another document as a reference.
39
- Then your application can run a second query to return the related
36
+ Your application runs a second query to return the related
40
37
data. These references are simple and sufficient for most use
41
38
cases.
42
39
43
40
- :ref:`DBRefs <dbref-explanation>` are references from one document to another
44
41
using the value of the first document's ``_id`` field, collection name,
45
- and, optionally, its database name. By including these names, DBRefs
46
- allow documents located in multiple collections to be more easily linked
47
- with documents from a single collection.
48
-
49
- To resolve DBRefs, your application
50
- must perform additional queries to return the referenced
51
- documents. Many :driver:`Drivers </>` have helper
52
- methods that form the query for the DBRef automatically. The
53
- drivers [#official-driver]_ do not *automatically* resolve DBRefs
54
- into documents.
55
-
56
- DBRefs provide a common format and type to represent relationships among
57
- documents. The DBRef format also provides common semantics for representing
58
- links between documents if your database must interact with
59
- multiple frameworks and tools.
42
+ and, optionally, its database name, as well as any other fields. DBRefs allow
43
+ you to more easily reference documents stored in multiple collections or
44
+ databases.
45
+
46
+ To resolve DBRefs, your application must perform additional queries to return
47
+ the referenced documents. Some :driver:`MongoDB drivers </>` provide helper
48
+ methods to enable DBRefs to be resolved into documents, but it doesn't happen
49
+ automatically.
50
+
51
+ DBRefs provide a common format and type to represent relationships among
52
+ documents. The DBRef format also provides common semantics for representing
53
+ links between documents if your database must interact with
54
+ multiple frameworks and tools.
60
55
61
56
Unless you have a compelling reason to use DBRefs, use manual
62
57
references instead.
63
58
64
- .. [#official-driver] Some community supported drivers may have
65
- alternate behavior and may resolve a DBRef into a document
66
- automatically.
67
-
68
59
.. _document-references:
69
60
70
61
Manual References
@@ -73,7 +64,7 @@ Manual References
73
64
Background
74
65
~~~~~~~~~~
75
66
76
- Using manual references is the practice of including one
67
+ A manual reference is the practice of including one
77
68
:term:`document's <document>` ``_id`` field in another document. The
78
69
application can then issue a second query to resolve the referenced
79
70
fields as needed.
@@ -129,7 +120,11 @@ Background
129
120
DBRefs are a convention for representing a :term:`document`, rather
130
121
than a specific reference type. They include the name of the
131
122
collection, and in some cases the database name, in addition to the
132
- value from the ``_id`` field.
123
+ value from the ``_id`` field.
124
+
125
+ Optionally, DBRefs can include any number of other fields. Extra field names
126
+ must follow any :ref:`rules for field names <limit-restrictions-on-field-names>`
127
+ imposed by the server version.
133
128
134
129
Format
135
130
~~~~~~
@@ -153,8 +148,6 @@ DBRefs have the following fields:
153
148
Contains the name of the database where the referenced document
154
149
resides.
155
150
156
- Only some drivers support ``$db`` references.
157
-
158
151
.. example::
159
152
160
153
DBRef documents resemble the following document:
@@ -174,13 +167,15 @@ DBRefs have the following fields:
174
167
"creator" : {
175
168
"$ref" : "creators",
176
169
"$id" : ObjectId("5126bc054aed4daf9e2ab772"),
177
- "$db" : "users"
170
+ "$db" : "users",
171
+ "extraField" : "anything"
178
172
}
179
173
}
180
174
181
175
The DBRef in this example points to a document in the ``creators``
182
176
collection of the ``users`` database that has
183
- ``ObjectId("5126bc054aed4daf9e2ab772")`` in its ``_id`` field.
177
+ ``ObjectId("5126bc054aed4daf9e2ab772")`` in its ``_id`` field. It also contains
178
+ an optional field.
184
179
185
180
.. note::
186
181
0 commit comments