Fetching contributors…
Cannot retrieve contributors at this time
269 lines (187 sloc) 7.62 KB
.. index:: DBRef
.. index:: database references
.. index:: references
.. _database-references:
Database References
.. default-domain:: mongodb
.. contents:: On this page
:backlinks: none
:depth: 1
:class: singlecol
In MongoDB some data is *denormalized*, or stored with related data in
:term:`documents <document>` to remove the need for joins. However, in
some cases it makes sense to store related information in separate
documents, typically in different collections or databases.
.. important::
Starting in version 3.2, you can use :pipeline:`$lookup` to perform
a left outer join to an unsharded collection in the same database.
For more information and examples, see :pipeline:`$lookup`.
This page outlines alternative procedures that predate the
:pipeline:`$lookup` pipeline stage.
MongoDB applications use one of two methods for relating documents:
- :ref:`Manual references <document-references>` where you save the
``_id`` field of one document in another document as a reference.
Then your application can run a second query to return the related
data. These references are simple and sufficient for most use
- :ref:`DBRefs <dbref-explanation>` are references from one document to another
using the value of the first document's ``_id`` field, collection name,
and, optionally, its database name. By including these names, DBRefs
allow documents located in multiple collections to be more easily linked
with documents from a single collection.
To resolve DBRefs, your application
must perform additional queries to return the referenced
documents. Many :doc:`drivers </applications/drivers>` have helper
methods that form the query for the DBRef automatically. The
drivers [#official-driver]_ do not *automatically* resolve DBRefs
into documents.
DBRefs provide a common format and type to represent relationships among
documents. The DBRef format also provides common semantics for representing
links between documents if your database must interact with
multiple frameworks and tools.
Unless you have a compelling reason to use DBRefs, use manual
references instead.
.. [#official-driver] Some community supported drivers may have
alternate behavior and may resolve a DBRef into a document
.. _document-references:
Manual References
Using manual references is the practice of including one
:term:`document's <document>` ``_id`` field in another document. The
application can then issue a second query to resolve the referenced
fields as needed.
Consider the following operation to insert two documents, using the
``_id`` field of the first document as a reference in the second
.. code-block:: javascript
original_id = ObjectId()
"_id": original_id,
"name": "Broadway Center",
"url": ""
"name": "Erin",
"places_id": original_id,
"url": ""
Then, when a query returns the document from the ``people`` collection
you can, if needed, make a second query for the document referenced by
the ``places_id`` field in the ``places`` collection.
For nearly every case where you want to store a relationship between
two documents, use :ref:`manual references <document-references>`. The
references are simple to create and your application can resolve
references as needed.
The only limitation of manual linking is that these references do not
convey the database and collection names. If you have documents in a
single collection that relate to documents in more than one
collection, you may need to consider using DBRefs.
.. _dbref-explanation:
DBRefs are a convention for representing a :term:`document`, rather
than a specific reference type. They include the name of the
collection, and in some cases the database name, in addition to the
value from the ``_id`` field.
DBRefs have the following fields:
.. describe:: $ref
The ``$ref`` field holds the name of the collection where the
referenced document resides.
.. describe:: $id
The ``$id`` field contains the value of the ``_id`` field in the
referenced document.
.. describe:: $db
Contains the name of the database where the referenced document
Only some drivers support ``$db`` references.
.. example::
DBRef documents resemble the following document:
.. code-block:: javascript
{ "$ref" : <value>, "$id" : <value>, "$db" : <value> }
Consider a document from a collection that stored a DBRef in a
``creator`` field:
.. code-block:: javascript
"_id" : ObjectId("5126bbf64aed4daf9e2ab771"),
// .. application fields
"creator" : {
"$ref" : "creators",
"$id" : ObjectId("5126bc054aed4daf9e2ab772"),
"$db" : "users"
The DBRef in this example points to a document in the ``creators``
collection of the ``users`` database that has
``ObjectId("5126bc054aed4daf9e2ab772")`` in its ``_id`` field.
.. note::
The order of fields in the DBRef matters, and you must use the above
sequence when using a DBRef.
Driver Support for DBRefs
.. list-table::
:widths: 20 80
* - **C**
- The C driver contains no support for DBRefs. You can traverse references
* - **C++**
- The C++ driver contains no support for DBRefs. You can traverse
references manually.
* - **C#**
- The C# driver supports DBRefs using the :api:`MongoDBRef
<csharp/current/html/T_MongoDB_Driver_MongoDBRef.htm>` class and
``FetchDBRef`` and ``FetchDBRefAs`` methods.
* - **Haskell**
- The Haskell driver contains no support for DBRefs. You can traverse
references manually.
* - **Java**
- The :api:`DBRef <java/current/com/mongodb/DBRef.html>` class provides
support for DBRefs from Java.
* - **JavaScript**
- The :binary:`~bin.mongo` shell's :doc:`JavaScript </reference/method>`
interface provides a DBRef.
* - **Node.js**
- The Node.js driver supports DBRefs using the `DBRef
tml>`_ class and the `dereference
erence>`_ method.
* - **Perl**
- The Perl driver supports DBRefs using the `MongoDB::DBRef
<>`_ class. You can traverse
references manually.
* - **PHP**
- The PHP driver contains no support for DBRefs. You can traverse
references manually.
* - **Python**
- The Python driver supports DBRefs using the :api:`DBRef
<python/current/api/bson/dbref.html>` class and the :api:`dereference
eren ce>` method.
* - **Ruby**
- The Ruby driver supports DBRefs using the :api:`DBRef
<ruby/current/BSON/DBRef.html>` class and the :api:`dereference
<ruby/current/Mongo/DB.html#dereference-instance_method>` method.
* - **Scala**
- The Scala driver contains no support for DBRefs. You can traverse
references manually.
In most cases you should use the :ref:`manual reference
<document-references>` method for connecting two or more related
documents. However, if you need to reference documents from multiple
collections, consider using DBRefs.