AWS documentdb documentation change

Service: documentdb · 2026-03-31 · Documentation low

File: documentdb/latest/developerguide/lookup.md

Summary

Added comprehensive documentation for the $lookup aggregation stage in Amazon DocumentDB, including parameters, MongoDB Shell example with sample data, and code examples in Node.js and Python

Security assessment

This change adds general documentation for a database feature ($lookup aggregation stage) without any mention of security vulnerabilities, patches, or security incidents. The code examples include standard TLS connection parameters (tls=true, tlsCAFile) which are routine security best practices for database connections, but these are not new security features being documented - they're standard connection parameters shown in examples. The change appears to be routine feature documentation addition.

Diff

diff --git a/documentdb/latest/developerguide/lookup.md b/documentdb/latest/developerguide/lookup.md
index 8b1378917..799c7548e 100644
--- a//documentdb/latest/developerguide/lookup.md
+++ b//documentdb/latest/developerguide/lookup.md
@@ -0,0 +1 @@
+[](/pdfs/documentdb/latest/developerguide/developerguide.pdf#lookup "Open PDF")
@@ -1,0 +3,162 @@
+[Documentation](/index.html)[Amazon DocumentDB](/documentdb/index.html)[Developer Guide](what-is.html)
+
+Example (MongoDB Shell)Code examples
+
+# $lookup
+
+The `$lookup` aggregation stage in Amazon DocumentDB allows you to perform a left outer join between two collections. This operation lets you combine data from multiple collections based on matching field values. It is particularly useful when you need to incorporate data from related collections into your query results.
+
+**Parameters**
+
+  * `from`: The name of the collection to perform the join with.
+
+  * `localField`: The field from the input documents to match against the `foreignField`.
+
+  * `foreignField`: The field from the documents in the `from` collection to match against the `localField`.
+
+  * `as`: The name of the new field to add to the output documents containing the matching documents from the `from` collection.
+
+
+
+
+## Example (MongoDB Shell)
+
+The following example demonstrates a simple `$lookup` operation that joins data from the `orders` collection into the `customers` collection.
+
+**Create sample documents**
+    
+    
+    db.customers.insertMany([
+      { _id: 1, name: "Alice" },
+      { _id: 2, name: "Bob" },
+      { _id: 3, name: "Charlie" }
+    ]);
+    
+    db.orders.insertMany([
+      { _id: 1, customer_id: 1, total: 50 },
+      { _id: 2, customer_id: 1, total: 100 },
+      { _id: 3, customer_id: 2, total: 75 }
+    ]);
+
+**Query example**
+    
+    
+    db.customers.aggregate([
+      {
+        $lookup: {
+          from: "orders",           
+          localField: "_id",        
+          foreignField: "customer_id", 
+          as: "orders" 
+        }
+      }
+    ]);
+
+**Output**
+    
+    
+    [
+      {
+        _id: 1,
+        name: 'Alice',
+        orders: [
+          { _id: 2, customer_id: 1, total: 100 },
+          { _id: 1, customer_id: 1, total: 50 }
+        ]
+      },
+      { _id: 3, name: 'Charlie', orders: [] },
+      {
+        _id: 2,
+        name: 'Bob',
+        orders: [ { _id: 3, customer_id: 2, total: 75 } ]
+      }
+    ]
+
+## Code examples
+
+To view a code example for using the `$lookup` command, choose the tab for the language that you want to use:
+
+Node.js
+    
+    
+    
+    const { MongoClient } = require('mongodb');
+    
+    async function example() {
+      const client = await MongoClient.connect('mongodb://<username>:<password>@<cluster-endpoint>:27017/?tls=true&tlsCAFile=global-bundle.pem&replicaSet=rs0&readPreference=secondaryPreferred&retryWrites=false');
+    
+      await client.connect();
+    
+      const db = client.db('test');
+    
+      const result = await db.collection('customers').aggregate([
+        {
+          $lookup: {
+            from: 'orders',
+            localField: '_id',
+            foreignField: 'customer_id',
+            as: 'orders'
+          }
+        }
+      ]).toArray();
+    
+      console.log(JSON.stringify(result, null, 2));
+      await client.close();
+    }
+    
+    example();
+
+Python
+    
+    
+    
+    from pymongo import MongoClient
+    
+    def example():
+        client = MongoClient('mongodb://<username>:<password>@<cluster-endpoint>:27017/?tls=true&tlsCAFile=global-bundle.pem&replicaSet=rs0&readPreference=secondaryPreferred&retryWrites=false')
+    
+        db = client.test
+        
+        collection = db.customers
+    
+        pipeline = [
+            {
+                "$lookup": {
+                    "from": "orders",
+                    "localField": "_id",
+                    "foreignField": "customer_id",
+                    "as": "orders"
+                }
+            }
+        ]
+    
+        result = collection.aggregate(pipeline)
+    
+        for doc in result:
+            print(doc)
+    
+        client.close()
+    
+    example()
+
+![Warning](https://d1ge0kk1l5kms0.cloudfront.net/images/G/01/webservices/console/warning.png) **Javascript is disabled or is unavailable in your browser.**
+
+To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.
+
+[Document Conventions](/general/latest/gr/docconventions.html)
+
+$lte
+
+$ltrim
+
+Did this page help you? - Yes
+
+Thanks for letting us know we're doing a good job!
+
+If you've got a moment, please tell us what we did right so we can do more of it.
+
+Did this page help you? - No
+
+Thanks for letting us know this page needs work. We're sorry we let you down.
+
+If you've got a moment, please tell us how we can make the documentation better.