> Documentation index: https://firebase.google.com/docs/firestore/llms.txt

## Description

Returns documents by looking up a fixed set of predefined documents.

The stage must take one or more documents as input and cannot contain documents
with duplicate paths. If a referenced document does not exist, no
results will be produced for that document path.

This stage behaves similar to Cloud Firestore's `batchGet` and allows
filtering on the results directly rather than performing post-filtering steps
after the batch operation.

## Examples

### Web

```javascript
const results = await execute(db.pipeline()
  .documents([
    doc(db, "cities", "SF"),
    doc(db, "cities", "DC"),
    doc(db, "cities", "NY")
  ])
);
```

##### Swift

```swift
let results = try await db.pipeline()
  .documents([
    db.collection("cities").document("SF"),
    db.collection("cities").document("DC"),
    db.collection("cities").document("NY")
  ]).execute()
```

### Kotlin

```kotlin
val results = db.pipeline()
    .documents(
        db.collection("cities").document("SF"),
        db.collection("cities").document("DC"),
        db.collection("cities").document("NY")
    ).execute()
```

### Java

```java
      Task<Pipeline.Snapshot> results = db.pipeline()
    .documents(
        db.collection("cities").document("SF"),
        db.collection("cities").document("DC"),
        db.collection("cities").document("NY")
    ).execute();
    
```

##### Python

```python
results = (
    client.pipeline()
    .documents(
        client.collection("cities").document("SF"),
        client.collection("cities").document("DC"),
        client.collection("cities").document("NY"),
    )
    .execute()
)
```

##### Java

```java
Pipeline.Snapshot results =
    firestore
        .pipeline()
        .documents(
            firestore.collection("cities").document("SF"),
            firestore.collection("cities").document("DC"),
            firestore.collection("cities").document("NY"))
        .execute()
        .get();
```

##### Go

```go
snapshot := client.Pipeline().
	Documents([]*firestore.DocumentRef{
		client.Collection("cities").Doc("SF"),
		client.Collection("cities").Doc("DC"),
		client.Collection("cities").Doc("NY"),
	}).
	Execute(ctx)
```

## Behavior

In order to use the `documents(...)` stage, it must appear as the first stage
in the pipeline.

The order of documents returned from the `documents(...)` stage is unstable and
cannot be relied upon. A subsequent [`sort(...)`](https://firebase.google.com/docs/firestore/pipelines/stages/transformation/sort.md.txt) stage can
be used to obtain a deterministic ordering.

For example, for the following documents:

### Node.js

```javascript
await db.collection("cities").doc("SF").set({name: "San Francsico", state: "California"});
await db.collection("cities").doc("NYC").set({name: "New York City", state: "New York"});
await db.collection("cities").doc("CHI").set({name: "Chicago", state: "Illinois"});
```

The `documents(...)` stage can be used to retrieve only the `SF` and `NYC`
documents and then sort them in ascending order of name.

### Node.js

```javascript
const results = await db.pipeline()
  .documents(
    db.collection("cities").doc("SF"),
    db.collection("cities").doc("NYC"))
  .sort(field("name").ascending())
  .execute();
```

This query produces the following documents:

```javascript
  { name: "New York City", state: "New York" }
  { name: "San Francsico", state: "California" }
```