> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

<!--
Tab options on this page. Append to the .md URL to filter:
  ?tabs=<id,...>   select specific tabs (e.g. ?tabs=nodejs,shell)
  ?allTabs=true    include every tab
  (no param)       default: one tab per tabset

Available tabs:
  drivers: shell, csharp, nodejs
-->

# $documents (aggregation stage)

## Definition

**New in version 6.0**

Returns literal documents from input values.

## Syntax

The [`$documents`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/documents.md#mongodb-pipeline-pipe.-documents) stage has the following form:

```text
{ $documents: <expression> }
```

## Limitations

- You can only use `$documents` in a database-level aggregation pipeline.

- You must use `$documents` as the first stage of an aggregation pipeline.

See below for [usage examples.](https://www.mongodb.com/docs/manual/reference/operator/aggregation/documents.md#std-label-ex-agg-documents-stage)

## Behavior

[`$documents`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/documents.md#mongodb-pipeline-pipe.-documents) accepts any valid expression that resolves to an array of objects. This includes:

- system variables, such as [`$$NOW`](https://www.mongodb.com/docs/manual/reference/aggregation-variables.md#mongodb-variable-variable.NOW) or `$$SEARCH_META`

- [`$let`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/let.md#mongodb-expression-exp.-let) expressions

- variables in scope from [`$lookup`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/lookup.md#mongodb-pipeline-pipe.-lookup) expressions

Expressions that do not resolve to a current document, like `$myField` or [`$$ROOT`](https://www.mongodb.com/docs/manual/reference/aggregation-variables.md#mongodb-variable-variable.ROOT), will result in an error.

## Examples

### MongoDB Shell

### Test a Pipeline Stage

Create testing and debugging data for a pipeline stage without creating test collections.

```javascript
db.aggregate(
   [
      { $documents: [ { x: 10 }, { x: 2 }, { x: 5 } ] },
      { $bucketAuto: { groupBy: "$x", buckets: 4 } }
   ]
)
```

The [aggregation expression](https://www.mongodb.com/docs/manual/reference/mql/expressions.md#std-label-aggregation-expressions) does not specify a collection. It uses the input data in the highlighted [`$documents`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/documents.md#mongodb-pipeline-pipe.-documents) stage as input to the [`$bucketAuto`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/bucketauto.md#mongodb-pipeline-pipe.-bucketAuto) stage.

```javascript
[
  { _id: { min: 2, max: 5 }, count: 1 },
  { _id: { min: 5, max: 10 }, count: 1 },
  { _id: { min: 10, max: 10 }, count: 1 }
]
```

### Use a `$documents` Stage in a `$lookup` Stage

Correlate documents in a collection with other data using [`$documents`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/documents.md#mongodb-pipeline-pipe.-documents) to modify [`$lookup`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/lookup.md#mongodb-pipeline-pipe.-lookup) output.

Create the `locations` collection.

```javascript
db.locations.insertMany(
   [
      { zip: 94301, name: "Palo Alto" },
      { zip: 10019, name: "New York" }
   ]
 )
```

Use [`$documents`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/documents.md#mongodb-pipeline-pipe.-documents) as a data source to transform the documents.

```javascript
db.locations.aggregate(
   [
      { $match: {} },
      { $lookup:
         {
            localField: "zip",
            foreignField: "zip_id",
            as: "city_state",
            pipeline:
              [
                 { $documents:
                    [
                       { zip_id: 94301, name: "Palo Alto, CA" },
                       { zip_id: 10019, name: "New York, NY" }
                    ]
                 }
              ]
         }
      }
   ]
 )
```

The output correlates the data in the `locations` collection with the values in the [`$documents`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/documents.md#mongodb-pipeline-pipe.-documents) pipeline stage.

```javascript
[
   {
      _id: ObjectId("618949d60f7bfd5f5689490d"),
      zip: 94301,
      name: 'Palo Alto',
      city_state: [ { zip_id: 94301, name: 'Palo Alto, CA' } ]
   },
   {
      _id: ObjectId("618949d60f7bfd5f5689490e"),
      zip: 10019,
      name: 'New York',
      city_state: [ { zip_id: 10019, name: 'New York, NY' } ]
   }
]
```

- The `zip` field corresponds to the `zip_id` field

- The `as` parameter creates a new output field

## Learn More

For details on subqueries using the [`$lookup`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/lookup.md#mongodb-pipeline-pipe.-lookup) syntax, see [Correlated Subqueries Using Concise Syntax.](https://www.mongodb.com/docs/manual/reference/operator/aggregation/lookup.md#std-label-lookup-syntax-concise-correlated-subquery)