$documents (Literal Documents)
Last updated: 2026-10-09
$documents (Literal Documents)
$documents returns a given array of literal documents without reading any collection — a literal pipeline input. It must be the first stage, handy for test data or running expressions over constants. Each document passes through unchanged.
| Category | Core Stages |
|---|---|
| MongoDB Version | 5.2+ |
| Example Language | mongosh (Shell) |
📝 Syntax
{ $documents: [ { <doc1> }, { <doc2> }, ... ] }⚙️ Parameters
| documents | The list of literal documents to emit. |
|---|
Returns：Literal document stream
▶ Example
Run the commands below in your local mongosh (requires a running mongod):
// $documents: verify expressions on literal data
db.aggregate([
{ $documents: [{ x: 1 }, { x: 2 }] },
{ $addFields: { y: { $add: ['$x', 1] } } }
])Output：
{ "x": 1, "y": 2 }
{ "x": 2, "y": 3 }📌 Notes
- Must be the first stage of the pipeline
- Reads no collection data — purely literal input
- Great for testing expressions and building reference data
🏷️ Related Tags
💡 Related Cases
More hands-on cases coming soon.
📚 Related Tutorials
❓ FAQ
QCan $documents appear mid-pipeline?
ANo, it must come first; any other stages follow it.
QWhat is $documents for?
ABuilding test data and validating aggregation expressions in mongosh without a real collection.
QWhat is the difference between db.aggregate and db.coll.aggregate?
Adb.aggregate runs without a collection; its first stage must be special, like $documents or $currentOp.
