Skip to content

Commit eb85a8c

Browse files
authored
DOCS-5135 Add information about extra DBRef fields (#921) (#933)
* Add note about extra DBRef fields * Incorporating external review comments
1 parent 9270cee commit eb85a8c

File tree

1 file changed

+31
-36
lines changed

1 file changed

+31
-36
lines changed

source/reference/database-references.txt

Lines changed: 31 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -13,58 +13,49 @@ Database References
1313
:class: singlecol
1414

1515
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
1818
information in separate documents, typically in different collections
1919
or databases.
2020

2121
.. important::
2222

23-
MongoDB 3.2 introduces :pipeline:`$lookup` pipeline stage to perform
23+
You can use the :pipeline:`$lookup` pipeline stage to perform
2424
a left outer join to an unsharded collection in the same database.
25-
For more information and examples, see :pipeline:`$lookup`.
2625

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.
3128

3229
This page outlines alternative procedures that predate the
3330
:pipeline:`$lookup` and :pipeline:`$graphLookup` pipeline stages.
3431

35-
MongoDB applications use one of two methods for relating documents:
32+
MongoDB applications use one of two methods to relate documents:
3633

37-
- :ref:`Manual references <document-references>` where you save the
34+
- :ref:`Manual references <document-references>` save the
3835
``_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
4037
data. These references are simple and sufficient for most use
4138
cases.
4239

4340
- :ref:`DBRefs <dbref-explanation>` are references from one document to another
4441
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.
6055

6156
Unless you have a compelling reason to use DBRefs, use manual
6257
references instead.
6358

64-
.. [#official-driver] Some community supported drivers may have
65-
alternate behavior and may resolve a DBRef into a document
66-
automatically.
67-
6859
.. _document-references:
6960

7061
Manual References
@@ -73,7 +64,7 @@ Manual References
7364
Background
7465
~~~~~~~~~~
7566

76-
Using manual references is the practice of including one
67+
A manual reference is the practice of including one
7768
:term:`document's <document>` ``_id`` field in another document. The
7869
application can then issue a second query to resolve the referenced
7970
fields as needed.
@@ -129,7 +120,11 @@ Background
129120
DBRefs are a convention for representing a :term:`document`, rather
130121
than a specific reference type. They include the name of the
131122
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.
133128

134129
Format
135130
~~~~~~
@@ -153,8 +148,6 @@ DBRefs have the following fields:
153148
Contains the name of the database where the referenced document
154149
resides.
155150

156-
Only some drivers support ``$db`` references.
157-
158151
.. example::
159152

160153
DBRef documents resemble the following document:
@@ -174,13 +167,15 @@ DBRefs have the following fields:
174167
"creator" : {
175168
"$ref" : "creators",
176169
"$id" : ObjectId("5126bc054aed4daf9e2ab772"),
177-
"$db" : "users"
170+
"$db" : "users",
171+
"extraField" : "anything"
178172
}
179173
}
180174

181175
The DBRef in this example points to a document in the ``creators``
182176
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.
184179

185180
.. note::
186181

0 commit comments

Comments
 (0)