AWS Security ChangesHomeSearch

AWS documentdb: Add $topN window operator usage examples for DocumentDB

Service: documentdb · 2026-09-29 · Documentation low

File: documentdb/latest/devguide/topN.md

Summary

Adds documentation and code examples (MongoDB Shell, Node.js, Python) for using the $topN operator as a window operator in $setWindowFields, including a 100 MB intermediate data limit note and sample queries/outputs.

Security assessment

The change is purely functional documentation for an aggregation operator ($topN) with example queries and outputs. It contains no security features, best practices, vulnerability fixes, or credential/authz content.

Evidence

+The `$topN` operator can also be used as a window operator in the `$setWindowFields` stage. In this context, it returns an array of the `output` from the top N documents (according to the operator's own `sortBy`) among the documents in each window. You specify the operator under the `output` field, and optionally define the window boundaries with a `window` document.

Diff

diff --git a/documentdb/latest/devguide/topN.md b/documentdb/latest/devguide/topN.md
index 9507a9472..4c7f3258f 100644
--- a//documentdb/latest/devguide/topN.md
+++ b//documentdb/latest/devguide/topN.md
@@ -7 +7 @@
-Example (MongoDB Shell)Code examples
+Example (MongoDB Shell)Window operator usage example (MongoDB Shell)Code examples
@@ -56,0 +57,54 @@ The following example shows how to use the `$topN` accumulator to find the top 2
+## Window operator usage example (MongoDB Shell)
+
+New from version 8.0.2.
+
+The `$topN` operator can also be used as a window operator in the `$setWindowFields` stage. In this context, it returns an array of the `output` from the top N documents (according to the operator's own `sortBy`) among the documents in each window. You specify the operator under the `output` field, and optionally define the window boundaries with a `window` document.
+
+###### Note
+
+When used as a window operator in `$setWindowFields`, `$topN` is limited to 100 MB of intermediate data. An operation that exceeds this limit returns an error.
+
+**Create sample documents**
+    
+    
+    db.matchScores.insertMany([
+      { _id: 1, player: "Alice", round: 1, score: 20 },
+      { _id: 2, player: "Alice", round: 2, score: 35 },
+      { _id: 3, player: "Alice", round: 3, score: 28 },
+      { _id: 4, player: "Bob", round: 1, score: 15 },
+      { _id: 5, player: "Bob", round: 2, score: 40 }
+    ]);
+
+**Query example**
+
+The following example partitions the documents by `player`, sorts each partition by `round`, and returns the two highest-scoring rounds seen from the start of the partition through the current document.
+    
+    
+    db.matchScores.aggregate([
+      {
+        $setWindowFields: {
+          partitionBy: "$player",
+          sortBy: { round: 1 },
+          output: {
+            topTwoRoundsSoFar: {
+              $topN: { n: 2, sortBy: { score: -1 }, output: { round: "$round", score: "$score" } },
+              window: { documents: ["unbounded", "current"] }
+            }
+          }
+        }
+      }
+    ]);
+
+**Output**
+    
+    
+    [
+      { "_id": 1, "player": "Alice", "round": 1, "score": 20, "topTwoRoundsSoFar": [{ "round": 1, "score": 20 }] },
+      { "_id": 2, "player": "Alice", "round": 2, "score": 35, "topTwoRoundsSoFar": [{ "round": 2, "score": 35 }, { "round": 1, "score": 20 }] },
+      { "_id": 3, "player": "Alice", "round": 3, "score": 28, "topTwoRoundsSoFar": [{ "round": 2, "score": 35 }, { "round": 3, "score": 28 }] },
+      { "_id": 4, "player": "Bob", "round": 1, "score": 15, "topTwoRoundsSoFar": [{ "round": 1, "score": 15 }] },
+      { "_id": 5, "player": "Bob", "round": 2, "score": 40, "topTwoRoundsSoFar": [{ "round": 2, "score": 40 }, { "round": 1, "score": 15 }] }
+    ]
+
+Each document is augmented with `topTwoRoundsSoFar`, the two highest-scoring rounds within its partition up to and including the current document. If the window contains fewer than two documents, all of them are returned.
+
@@ -59 +113 @@ The following example shows how to use the `$topN` accumulator to find the top 2
-To view a code example for using the `$topN` operator, choose the tab for the language that you want to use:
+To view a code example for using the `$topN` operator, choose the tab for the language that you want to use. The following examples show both accumulator usage (in `$group`) and window operator usage (in `$setWindowFields`):
@@ -75 +128,0 @@ Node.js
-        const collection = db.collection('sales');
@@ -77 +130,11 @@ Node.js
-        const result = await collection.aggregate([
+        // Accumulator usage: top N documents per group
+        const sales = db.collection('sales');
+        await sales.insertMany([
+          { item: "abc", quantity: 10, price: 5 },
+          { item: "abc", quantity: 7, price: 8 },
+          { item: "abc", quantity: 5, price: 10 },
+          { item: "xyz", quantity: 15, price: 3 },
+          { item: "xyz", quantity: 9, price: 6 },
+          { item: "xyz", quantity: 3, price: 12 }
+        ]);
+        const accumulatorResult = await sales.aggregate([
@@ -80,2 +143,26 @@ Node.js
-    
-        console.log(result);
+        console.log('Accumulator result:', accumulatorResult);
+    
+        // Window operator usage: top two rounds so far within each partition
+        const matchScores = db.collection('matchScores');
+        await matchScores.insertMany([
+          { _id: 1, player: "Alice", round: 1, score: 20 },
+          { _id: 2, player: "Alice", round: 2, score: 35 },
+          { _id: 3, player: "Alice", round: 3, score: 28 },
+          { _id: 4, player: "Bob", round: 1, score: 15 },
+          { _id: 5, player: "Bob", round: 2, score: 40 }
+        ]);
+        const windowResult = await matchScores.aggregate([
+          {
+            $setWindowFields: {
+              partitionBy: "$player",
+              sortBy: { round: 1 },
+              output: {
+                topTwoRoundsSoFar: {
+                  $topN: { n: 2, sortBy: { score: -1 }, output: { round: "$round", score: "$score" } },
+                  window: { documents: ["unbounded", "current"] }
+                }
+              }
+            }
+          }
+        ]).toArray();
+        console.log('Window result:', windowResult);
@@ -105 +191,0 @@ Python
-            collection = db['sales']
@@ -107 +193,11 @@ Python
-            result = list(collection.aggregate([
+            # Accumulator usage: top N documents per group
+            sales = db['sales']
+            sales.insert_many([
+                { 'item': 'abc', 'quantity': 10, 'price': 5 },
+                { 'item': 'abc', 'quantity': 7, 'price': 8 },
+                { 'item': 'abc', 'quantity': 5, 'price': 10 },
+                { 'item': 'xyz', 'quantity': 15, 'price': 3 },
+                { 'item': 'xyz', 'quantity': 9, 'price': 6 },
+                { 'item': 'xyz', 'quantity': 3, 'price': 12 }
+            ])
+            accumulator_result = list(sales.aggregate([
@@ -110,2 +206,26 @@ Python
-    
-            pprint(result)
+            pprint(accumulator_result)
+    
+            # Window operator usage: top two rounds so far within each partition
+            match_scores = db['matchScores']
+            match_scores.insert_many([
+                { '_id': 1, 'player': 'Alice', 'round': 1, 'score': 20 },
+                { '_id': 2, 'player': 'Alice', 'round': 2, 'score': 35 },
+                { '_id': 3, 'player': 'Alice', 'round': 3, 'score': 28 },
+                { '_id': 4, 'player': 'Bob', 'round': 1, 'score': 15 },
+                { '_id': 5, 'player': 'Bob', 'round': 2, 'score': 40 }
+            ])
+            window_result = list(match_scores.aggregate([
+                {
+                    '$setWindowFields': {
+                        'partitionBy': '$player',
+                        'sortBy': { 'round': 1 },
+                        'output': {
+                            'topTwoRoundsSoFar': {
+                                '$topN': { 'n': 2, 'sortBy': { 'score': -1 }, 'output': { 'round': '$round', 'score': '$score' } },
+                                'window': { 'documents': ['unbounded', 'current'] }
+                            }
+                        }
+                    }
+                }
+            ]))
+            pprint(window_result)