# Collection (Input Stage)

## Description

Returns all documents from a given collection. The collection can be nested.

## Examples

### Web

```javascript
const results = await execute(db.pipeline()
  .collection("users/bob/games")
  .sort(field("name").ascending())
  );
```

##### Swift

```swift
let results = try await db.pipeline()
  .collection("users/bob/games")
  .sort([Field("name").ascending()])
  .execute()
```

##### Kotlin
Android

```kotlin
val results = db.pipeline()
    .collection("users/bob/games")
    .sort(field("name").ascending())
    .execute()
```

##### Java
Android

```java
Task<Pipeline.Snapshot> results = db.pipeline()
    .collection("users/bob/games")
    .sort(field("name").ascending())
    .execute();
```

##### Python

```python
from google.cloud.firestore_v1.pipeline_expressions import Field

results = (
    client.pipeline()
    .collection("users/bob/games")
    .sort(Field.of("name").ascending())
    .execute()
)
```

##### Java

```java
Pipeline.Snapshot results =
    firestore
        .pipeline()
        .collection("users/bob/games")
        .sort(ascending(field("name")))
        .execute()
        .get();
```

##### Go

```go
snapshot := client.Pipeline().
	Collection("users/bob/games").
	Sort(firestore.Orders(firestore.Ascending(firestore.FieldOf("name")))).
	Execute(ctx)
```

## Behavior

In order to use the `collection(...)` stage, it must appear as the first stage
in the pipeline (or sub-pipeline).

The order of documents returned from the `collection(...)` stage is unstable and
cannot be relied upon. Firestore will attempt to execute the
query in the most efficient way possible, which can change the order depending
on the schema or index configuration. A subsequent
[`sort(...)`](https://docs.cloud.google.com/firestore/native/docs/pipeline/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"});
await db.collection("states").doc("CA").set({name: "California"});
```

The `collection` stage can be used to retrieve all cities in the
`cities` collection and then sort them in ascending order of name.

### Node.js

```javascript
const results = await db.pipeline()
  .collection("/cities")
  .sort(field("name").ascending())
  .execute();
```

This query produces the following documents:

```javascript
  { name: "Chicago", state: "Illinois" }
  { name: "New York City", state: "New York" }
  { name: "San Francisco", state: "California" }
```

### Subcollections

The `collection(...)` stage can also be used to target collections under a
specific parent by providing the full path to the stage.

For example, for the following documents:

### Node.js

```javascript
await db.collection("cities/SF/departments").doc("building").set({name: "SF Building Deparment", employees: 750});
await db.collection("cities/NY/departments").doc("building").set({name: "NY Building Deparment", employees: 1000});
await db.collection("cities/CHI/departments").doc("building").set({name: "CHI Building Deparment", employees: 900});
await db.collection("cities/NY/departments").doc("finance").set({name: "NY Finance Deparment", employees: 1200});
```

For this example, we only want the departments of New York city.

### Node.js

```javascript
const results = await db.pipeline()
  .collection("/cities/NY/departments")
  .sort(field("employees").ascending())
  .execute();
```

This will return all departments under the full path `cities/NY/departments`.

```javascript
  { name: "NY Building Deparment", employees: 1000 }
  { name: "NY Finance Deparment", employees: 1200 }
```