AWS documentdb documentation change

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

File: documentdb/latest/developerguide/dateDiff.md

Summary

Added comprehensive documentation for the $dateDiff aggregation operator in Amazon DocumentDB, including syntax, parameters, examples in MongoDB Shell, Node.js, and Python, with sample code and output.

Security assessment

This change is purely a feature documentation update for a new aggregation operator ($dateDiff) in DocumentDB version 5.0. The content includes standard usage examples, parameter descriptions, and code samples. There is no mention of security vulnerabilities, security fixes, or security-related configurations. 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 that were likely already present in other documentation examples.

Diff

diff --git a/documentdb/latest/developerguide/dateDiff.md b/documentdb/latest/developerguide/dateDiff.md
index 8b1378917..051194210 100644
--- a//documentdb/latest/developerguide/dateDiff.md
+++ b//documentdb/latest/developerguide/dateDiff.md
@@ -0,0 +1 @@
+[](/pdfs/documentdb/latest/developerguide/developerguide.pdf#dateDiff "Open PDF")
@@ -1,0 +3,175 @@
+[Documentation](/index.html)[Amazon DocumentDB](/documentdb/index.html)[Developer Guide](what-is.html)
+
+Example (MongoDB Shell)Code examples
+
+# $dateDiff
+
+New from version 5.0
+
+Not supported by Elastic cluster.
+
+The `$dateDiff` aggregation operator calculates the difference between two dates in specified units. It returns the number of unit boundaries crossed between the start and end dates.
+
+**Parameters**
+
+  * `startDate`: The beginning date expression.
+
+  * `endDate`: The ending date expression.
+
+  * `unit`: The time unit for the difference. Supported units are `year`, `quarter`, `month`, `week`, `day`, `hour`, `minute`, `second`, and `millisecond`.
+
+
+
+
+## Example (MongoDB Shell)
+
+The following example demonstrates how to use the `$dateDiff` operator to calculate the number of days between order placement and delivery.
+
+**Create sample documents**
+    
+    
+    db.shipments.insertMany([
+      {
+        orderId: 1001,
+        orderDate: ISODate("2025-01-10T08:00:00Z"),
+        deliveryDate: ISODate("2025-01-15T14:30:00Z")
+      },
+      {
+        orderId: 1002,
+        orderDate: ISODate("2025-02-05T10:00:00Z"),
+        deliveryDate: ISODate("2025-02-12T16:45:00Z")
+      }
+    ]);
+
+**Query example**
+    
+    
+    db.shipments.aggregate([
+      {
+        $project: {
+          orderId: 1,
+          orderDate: 1,
+          deliveryDate: 1,
+          daysToDeliver: {
+            $dateDiff: {
+              startDate: "$orderDate",
+              endDate: "$deliveryDate",
+              unit: "day"
+            }
+          }
+        }
+      }
+    ]);
+
+**Output**
+    
+    
+    [
+      {
+        _id: ObjectId('6924a5f2d66dcae121d29517'),
+        orderId: 1001,
+        orderDate: ISODate('2025-01-10T08:00:00.000Z'),
+        deliveryDate: ISODate('2025-01-15T14:30:00.000Z'),
+        daysToDeliver: 5
+      },
+      {
+        _id: ObjectId('6924a5f2d66dcae121d29518'),
+        orderId: 1002,
+        orderDate: ISODate('2025-02-05T10:00:00.000Z'),
+        deliveryDate: ISODate('2025-02-12T16:45:00.000Z'),
+        daysToDeliver: 7
+      }
+    ]
+
+## Code examples
+
+To view a code example for using the `$dateDiff` 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');
+      const db = client.db('test');
+      const shipments = db.collection('shipments');
+      
+      const result = await shipments.aggregate([
+        {
+          $project: {
+            orderId: 1,
+            orderDate: 1,
+            deliveryDate: 1,
+            daysToDeliver: {
+              $dateDiff: {
+                startDate: "$orderDate",
+                endDate: "$deliveryDate",
+                unit: "day"
+              }
+            }
+          }
+        }
+      ]).toArray();
+      
+      console.log(result);
+      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']
+        shipments = db['shipments']
+        
+        result = list(shipments.aggregate([
+            {
+                "$project": {
+                    "orderId": 1,
+                    "orderDate": 1,
+                    "deliveryDate": 1,
+                    "daysToDeliver": {
+                        "$dateDiff": {
+                            "startDate": "$orderDate",
+                            "endDate": "$deliveryDate",
+                            "unit": "day"
+                        }
+                    }
+                }
+            }
+        ]))
+        
+        print(result)
+        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)
+
+$dateAdd
+
+$dateFromString
+
+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.