model-embedded-one-to-one-relationships-between-documents.txt

.. _data-modeling-example-one-to-one:

======================================================
Model One-to-One Relationships with Embedded Documents
======================================================

.. default-domain:: mongodb

.. facet::
   :name: programming_language
   :values: shell

.. meta::
   :description: Learn how to model one-to-one relationships between MongoDB documents using embedded documents. Embedding connected data in a single document can reduce the number of read operations required to obtain data.

.. contents:: On this page
   :local:
   :backlinks: none
   :depth: 2
   :class: singlecol

Create a data model that uses :ref:`embedded
<data-modeling-embedding>` documents to describe a one-to-one
relationship between connected data. Embedding connected data
in a single document can reduce the number of read operations required
to obtain data. In general, structure your schema so your application receives 
all of its required information in a single read operation. For example, you 
can use the the embedded one-to-one model to describe the following relationships:

- Country to capital city
- User account to email address
- Building to address 

Example
-------

The example schema contains two entities, a ``patron`` and an ``address``:

.. code-block:: javascript

   // patron document
   {
      _id: "joe",
      name: "Joe Bookreader"
   }
   // address document
   {
      street: "123 Fake Street",
      city: "Faketon",
      state: "MA",
      zip: "12345"
   }

.. _one-to-one-embedded-document-pattern:

Embedded Document Pattern
~~~~~~~~~~~~~~~~~~~~~~~~~

The ``address`` data is frequently retrieved with the ``patron`` information. To allow 
your application to retreive all necessary information with a single query, embed the 
``address`` information inside of the ``patron`` document: 

.. code-block:: javascript

   {
      _id: "joe",
      name: "Joe Bookreader", 
      address: {
                 street: "123 Fake Street",
                 city: "Faketon",
                 state: "MA",
                 zip: "12345"
               }
   }

Learn More
----------

- :ref:`data-modeling-example-one-to-many`

- :ref:`data-modeling-publisher-and-books`