Skip to content

Commit fe99bd7

Browse files
author
Sam Kleinman
committed
database references style corrections and clarification
1 parent 861c8b2 commit fe99bd7

File tree

1 file changed

+19
-10
lines changed

1 file changed

+19
-10
lines changed

source/applications/database-references.txt

Lines changed: 19 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -24,19 +24,28 @@ MongoDB applications use one of two methods for relating documents:
2424
cases.
2525

2626
#. :ref:`DBRefs <dbref>` are references from one document to another
27-
using its _id field value, and collection, and (possibly) a database name, for the target
28-
document. Resolving DBRefs requires queries from your
29-
application; however, many :doc:`drivers </applications/drivers>`
30-
have helper methods to resolve DBRefs without having to form the query manually.
31-
No official driver automatically resolves DBRefs to documents for you; some frameworks and toolkits
32-
provide automatically linking and (link) resolution if you wish to use these features.
33-
DBRefs are useful when you need to embed documents from multiple collections in documents from one
34-
collection. They also provide a common format and type for tools which can represent the link semantics provided
35-
in your documents, or for interactions between frameworks which store linked documents.
27+
using the value of the first documents ``_id`` field collection,
28+
and optionally database name. To resolve DBRefs, your application
29+
must perform additional queries to return the referenced
30+
documents. Many :doc:`drivers </applications/drivers>` have helper
31+
methods that form the query for the DBRef automatically. The
32+
drivers [#offical-driver]_ do not *automatically* resolve DBRefs
33+
into documents.
34+
35+
Use DBRefs when you need to embed documents from multiple
36+
collections in documents from one collection. DBRefs also provide a
37+
common format and type to represent these relationships between
38+
documents. DBRefs provide common semantics for representing these
39+
links between documents if your database must interact with
40+
multiple frameworks and tools.
3641

3742
Unless you have a compelling reason for using DBrefs, use manual
3843
references.
3944

45+
.. [#offical-driver] Some community supported drivers may have
46+
alternate behavior and may resolve DBRefs into documents
47+
already.
48+
4049
.. _document-references:
4150

4251
Manual References
@@ -101,7 +110,7 @@ Background
101110
DBRefs are a convention for representing a :term:`document`, rather
102111
than a specific reference "type." They include the name of the
103112
collection, and in some cases the database, in addition to the
104-
value from the _id field.
113+
value from the ``_id`` field.
105114

106115
Format
107116
~~~~~~

0 commit comments

Comments
 (0)