AWS documentdb: Add $topN window operator usage examples for DocumentDB
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)