one-to-one-join.txt

.. _node-aggregation-one-to-one:

===============
One-to-One Join
===============

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

.. facet::
   :name: genre
   :values: tutorial

.. meta::
   :keywords: code example, node.js, lookup, aggregation
   :description: Learn to perform a one-to-one join using the Node.js driver to combine data from two collections in an aggregation pipeline.

Introduction
------------

In this tutorial, you can learn how to use the {+driver-short+} to
construct an aggregation pipeline, perform the
aggregation on a collection, and print the results by completing and
running a sample app.

This aggregation performs a one-to-one join. A one-to-one join occurs
when a document in one collection has a field value that matches a
single document in another collection that has the same field value. The
aggregation matches these documents on the field value and combines
information from both sources into one result.

.. tip::

   A one-to-one join does not require the documents to have a
   one-to-one relationship. To learn more about this data relationship,
   see the Wikipedia entry about :wikipedia:`One-to-one (data model)
   <w/index.php?title=One-to-one_(data_model)&oldid=1096960092>`.

Aggregation Task Summary
~~~~~~~~~~~~~~~~~~~~~~~~

This tutorial demonstrates how to combine data from a collection that
describes product information with another collection that describes
customer orders. The results show a list of all orders placed in 2020 that
includes the product details associated with each order.

This example uses two collections:

- ``orders``: contains documents describing individual orders
  for products in a shop
- ``products``: contains documents describing the products that
  a shop sells

An order can only contain one product, so the aggregation uses a
one-to-one join to match an order document to the document for the
product. The collections are joined by a field called ``product_id``
that exists in documents in both collections.

Before You Get Started
----------------------

Before you start this tutorial, complete the
:ref:`node-agg-tutorial-template-app` instructions to set up a working
Node.js application.

After you set up the app, access the ``orders`` and ``products``
collections by adding the following code to the application:

.. literalinclude:: /includes/aggregation/one-to-one-join.js
   :language: javascript
   :copyable: true
   :start-after: start-colls
   :end-before: end-colls
   :dedent:

Delete any existing data and insert sample data into
the ``orders`` collection as shown in the following code:

.. literalinclude:: /includes/aggregation/one-to-one-join.js
   :language: javascript
   :copyable: true
   :start-after: start-insert-orders
   :end-before: end-insert-orders
   :dedent:

Delete any existing data and insert sample data into
the ``products`` collection as shown in the following code:

.. literalinclude:: /includes/aggregation/one-to-one-join.js
   :language: javascript
   :copyable: true
   :start-after: start-insert-products
   :end-before: end-insert-products
   :dedent:

Tutorial
--------

.. procedure::
   :style: connected

   .. step:: Add a match stage for orders in 2020

      Add a :manual:`$match
      </reference/operator/aggregation/match>` stage that matches
      orders placed in 2020:

      .. literalinclude:: /includes/aggregation/one-to-one-join.js
         :language: javascript
         :copyable: true
         :start-after: start-match
         :end-before: end-match
         :dedent:

   .. step:: Add a lookup stage to link the collections

      Next, add a :manual:`$lookup
      </reference/operator/aggregation/lookup>` stage. The
      ``$lookup`` stage joins the ``product_id`` field in the ``orders``
      collection to the ``id`` field in the ``products`` collection:

      .. literalinclude:: /includes/aggregation/one-to-one-join.js
         :language: javascript
         :copyable: true
         :start-after: start-lookup
         :end-before: end-lookup
         :dedent:

   .. step:: Add set stages to create new document fields

      Next, add two :manual:`$set </reference/operator/aggregation/set>`
      stages to the pipeline.

      The first ``$set`` stage sets the ``product_mapping`` field
      to the first element in the ``product_mapping`` object
      created in the previous ``$lookup`` stage. 

      The second ``$set`` stage creates two new fields, ``product_name``
      and ``product_category``, from the values in the
      ``product_mapping`` object field:

      .. literalinclude:: /includes/aggregation/one-to-one-join.js
         :language: javascript
         :copyable: true
         :start-after: start-set
         :end-before: end-set
         :dedent:

      .. tip::

         Because this is a one-to-one join, the ``$lookup`` stage
         adds only one array element to the input document. The pipeline
         uses the :manual:`$first </reference/operator/aggregation/first>`
         operator to retrieve the data from this element.

   .. step:: Add an unset stage to remove unneeded fields

      Finally, add an :manual:`$unset
      </reference/operator/aggregation/unset>` stage. The
      ``$unset`` stage removes unnecessary fields from the document:
            
      .. literalinclude:: /includes/aggregation/one-to-one-join.js
         :language: javascript
         :copyable: true
         :start-after: start-unset
         :end-before: end-unset
         :dedent:

   .. step:: Run the aggregation pipeline

      Add the following code to the end of your application to perform
      the aggregation on the ``orders`` collection:

      .. literalinclude:: /includes/aggregation/one-to-one-join.js
         :language: javascript
         :copyable: true
         :start-after: start-run-agg
         :end-before: end-run-agg
         :dedent:

      Finally, run the following command in your shell to start your
      application:

      .. code-block:: bash
      
         node agg_tutorial.js

   .. step:: Interpret results

      The aggregated result contains three documents. The documents
      represent customer orders that occurred in 2020, with the
      ``product_name`` and ``product_category`` of the ordered product:

      .. code-block:: javascript
         :copyable: false
         
         {
           customer_id: 'elise_smith@myemail.com',
           orderdate: 2020-05-30T08:35:52.000Z,
           value: 431.43,
           product_name: 'Asus Laptop',
           product_category: 'ELECTRONICS'
         }
         {
           customer_id: 'oranieri@warmmail.com',
           orderdate: 2020-01-01T08:25:37.000Z,
           value: 63.13,
           product_name: 'Morphy Richardds Food Mixer',
           product_category: 'KITCHENWARE'
         }
         {
           customer_id: 'jjones@tepidmail.com',
           orderdate: 2020-12-26T08:55:46.000Z,
           value: 429.65,
           product_name: 'Asus Laptop',
           product_category: 'ELECTRONICS'
         }

      The result consists of documents that contain fields from
      documents in the ``orders`` collection and the ``products``
      collection, joined by matching the ``product_id`` field present in
      each original document.

To view the complete code for this tutorial, see the `Completed One-to-one Join App
<https://github.com/mongodb/docs-node/tree/master/source/includes/aggregation/one-to-one-join.js>`__
on GitHub.