<!-- BusyBot node reference — https://busybot.net/tools/google-cloud-firestore/ -->

> Node: Google Cloud Firestore (`google_cloud_firestore`) · Action · v1
> Category: Data & Storage · Credentials: Google Firebase Cloud Firestore OAuth2 (`googleFirebaseCloudFirestoreOAuth2Api`), Google API (Service Account) (`googleApi`)
> Updated: 2026-08-16

# Google Cloud Firestore

> Create, read, update, delete, and query documents and collections in Google Cloud Firestore.

## Overview

Integrates with the Firestore REST API v1 to manage documents and collections. It supports creating a document (with an optional document ID), batch get, listing a collection with pagination, delete, batch upsert with field masks, structured queries, and listing root collection IDs. Data is encoded and decoded using Firestore's typed value format, so the values you send and read back are ordinary JSON. Authentication is available via OAuth2 or a service account. Simplify mode returns each document with underscore-prefixed metadata merged alongside its decoded fields.

**Category:** Data & Storage  
**Tool Name:** `google_cloud_firestore`  
**Version:** 1

**Appearance:** Icon: `lucide-Database` | Color: `#FFA000`

## Node Type

**Action** — processes input items and produces output

## Input / Output

| Direction | Port(s) |
|-----------|--------|
| Input | `main` |
| Output | `main`, `error` |

## Credentials

This tool requires **Google Firebase Cloud Firestore OAuth2**, **Google API (Service Account)** credentials.
See the [Credentials Guide](https://busybot.net/credentials/) for setup instructions.

Configure the one that matches the Authentication parameter — OAuth2 or service account, not both.

### Resources

| Resource | Value |
|----------|-------|
| Document | `document` |
| Collection | `collection` |

### Operations

| Operation | Value | Description |
|-----------|-------|-------------|
| Create | `create` | Create a new document in a collection. |
| Delete | `delete` | Delete a document. |
| Get | `get` | Get one or more documents by ID (batch). |
| Get Many | `getAll` | Get all documents in a collection or list all root collection IDs. |
| Query | `query` | Run a structured query against a collection. |
| Upsert | `upsert` | Create or update documents (batch write). |

Every operation applies to the **Document** resource. The **Collection** resource offers `getAll` only.

### Parameters

#### Document: Create

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Collection | `string` | Yes | — | The collection ID or path (e.g. "users" or "users/userId/orders"). Supports expressions. |
| Document ID | `string` | No | — | Optional document ID. If omitted, Firestore auto-generates one. |
| Columns | `string` | No | — | Comma-separated list of item fields to write as document fields. Leave empty to write all fields from the item JSON. |
| Simplify | `boolean` | No | `true` | Return simplified output with underscore-prefixed metadata merged with document fields. |

#### Document: Delete

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Collection | `string` | Yes | — | The collection ID or path (e.g. "users" or "users/userId/orders"). Supports expressions. |
| Document ID | `string` | Yes | — | The document ID (last path segment). For nested collections use the full relative path (e.g. "docId/subcollection/subDocId"). |

#### Document: Get

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Collection | `string` | Yes | — | The collection ID or path (e.g. "users" or "users/userId/orders"). Supports expressions. |
| Document ID | `string` | Yes | — | The document ID (last path segment). For nested collections use the full relative path (e.g. "docId/subcollection/subDocId"). |
| Simplify | `boolean` | No | `true` | Return simplified output with underscore-prefixed metadata merged with document fields. |

#### Document: Get Many

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Collection | `string` | Yes | — | The collection ID or path (e.g. "users" or "users/userId/orders"). Supports expressions. |
| Return All | `boolean` | No | `false` | Whether to return all results or only up to a given limit. |
| Limit | `number` | No | `100` | Max number of documents to return. _(shown when Return All is `false`)_ |
| Simplify | `boolean` | No | `true` | Return simplified output with underscore-prefixed metadata merged with document fields. |

#### Document: Query

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Collection | `string` | Yes | — | The collection ID or path (e.g. "users" or "users/userId/orders"). Supports expressions. |
| Query | `string` | Yes | — | A JSON string containing a Firestore structuredQuery object. Example: {"from":[{"collectionId":"users"}],"where":{"fieldFilter":{"field":{"fieldPath":"age"},"op":"GREATER_THAN","value":{"integerValue":"18"}}}} |
| Simplify | `boolean` | No | `true` | Return simplified output with underscore-prefixed metadata merged with document fields. |

#### Document: Upsert

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Collection | `string` | Yes | — | The collection ID or path (e.g. "users" or "users/userId/orders"). Supports expressions. |
| Update Key | `string` | Yes | — | The field in the item data to use as the Firestore document ID. |
| Columns | `string` | No | — | Comma-separated list of item fields to write. Leave empty to write all fields. |

#### Collection: Get Many

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Return All | `boolean` | No | `false` | Whether to return all collection IDs or only up to a given limit. |
| Limit | `number` | No | `100` | Max number of collection IDs to return. _(shown when Return All is `false`)_ |

#### All Operations

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Authentication | `options` | No | `oAuth2` | Authentication method to use. |
| | | | | Options: `oAuth2`, `serviceAccount` |
| Google Account | `credential` | No | — | Connect or select your Google account. _(shown when Authentication is `oAuth2`)_ |
| Service Account Email | `string` | Yes | — | The email address of the Google service account. _(shown when Authentication is `serviceAccount`)_ |
| Private Key | `string` | Yes | — | The private key from the service account JSON key file. _(shown when Authentication is `serviceAccount`)_ |
| Project ID | `string` | Yes | — | The Google Cloud project ID (e.g. "my-project-123"). |
| Database | `string` | No | `(default)` | The Firestore database name. Use "(default)" for the default database. |
| Max Concurrency | `number` | No | `5` | Maximum number of items to process concurrently. |

## Output Data

The output item's JSON is the Firestore result — the incoming item's JSON does **not** pass through — while binary data on the input item is forwarded.

With **Simplify** on (the default), a document arrives with its decoded fields at the top level and its metadata under underscore-prefixed keys:

```json
{
  "_name": "projects/my-project-123/databases/(default)/documents/users/user123",
  "_id": "user123",
  "_createTime": "2024-01-15T09:30:00.123456Z",
  "_updateTime": "2024-01-15T09:30:00.123456Z",
  "name": "Ada Lovelace",
  "email": "ada@example.com",
  "age": 36
}
```

Turn Simplify off to receive the raw Firestore document instead, with `name`, `createTime`, `updateTime` and a `fields` object still in Firestore's typed value format.

| Operation | Output |
|-----------|--------|
| `document` / `create` | One item — the created document. |
| `document` / `delete` | One item carrying `success: true`. |
| `document` / `get` | One item per requested document. A document that does not exist produces an error item rather than an empty one. |
| `document` / `getAll` | **One item per document** in the collection, paginated up to Limit (or all of them with Return All on). |
| `document` / `query` | **One item per matching document.** |
| `document` / `upsert` | One item per written document, carrying the write result (`updateTime`). |
| `collection` / `getAll` | **One item per collection**, each carrying a single `collectionId` property. |

Address the result downstream with expressions such as `{{ $json._id }}` or `{{ $json.email }}`.

## Usage Examples

- Use Google Cloud Firestore in a workflow to create, read, update, delete, and query documents and collections in Google Cloud Firestore

## Example Configuration

Create a document with an explicit ID, writing only three fields from the item:

```json
{
  "type": "google_cloud_firestore",
  "parameters": {
    "authentication": "oAuth2",
    "resource": "document",
    "operation": "create",
    "projectId": "my-project-123",
    "database": "(default)",
    "collection": "users",
    "documentId": "user123",
    "columns": "name,email,age",
    "simplify": true
  }
}
```

Read a single document back:

```json
{
  "type": "google_cloud_firestore",
  "parameters": {
    "authentication": "oAuth2",
    "resource": "document",
    "operation": "get",
    "projectId": "my-project-123",
    "database": "(default)",
    "collection": "users",
    "documentId": "{{ $json.userId }}",
    "simplify": true
  }
}
```

List the first hundred documents in a collection:

```json
{
  "type": "google_cloud_firestore",
  "parameters": {
    "authentication": "oAuth2",
    "resource": "document",
    "operation": "getAll",
    "projectId": "my-project-123",
    "database": "(default)",
    "collection": "users",
    "returnAll": false,
    "limit": 100,
    "simplify": true
  }
}
```

Run a structured query:

```json
{
  "type": "google_cloud_firestore",
  "parameters": {
    "authentication": "oAuth2",
    "resource": "document",
    "operation": "query",
    "projectId": "my-project-123",
    "database": "(default)",
    "collection": "users",
    "query": "{\"from\":[{\"collectionId\":\"users\"}],\"where\":{\"fieldFilter\":{\"field\":{\"fieldPath\":\"age\"},\"op\":\"GREATER_THAN\",\"value\":{\"integerValue\":\"18\"}}}}",
    "simplify": true
  }
}
```

Create or update many documents in one batch, keyed on a field of the incoming items:

```json
{
  "type": "google_cloud_firestore",
  "parameters": {
    "authentication": "oAuth2",
    "resource": "document",
    "operation": "upsert",
    "projectId": "my-project-123",
    "database": "(default)",
    "collection": "users",
    "updateKey": "userId",
    "columns": "name,email,age"
  }
}
```

Delete a document:

```json
{
  "type": "google_cloud_firestore",
  "parameters": {
    "authentication": "oAuth2",
    "resource": "document",
    "operation": "delete",
    "projectId": "my-project-123",
    "database": "(default)",
    "collection": "users",
    "documentId": "user123"
  }
}
```

Read a document out of a nested subcollection:

```json
{
  "type": "google_cloud_firestore",
  "parameters": {
    "resource": "document",
    "operation": "get",
    "projectId": "ecommerce-project",
    "collection": "users/user123/orders",
    "documentId": "order456",
    "simplify": true
  }
}
```

List every root collection in the database:

```json
{
  "type": "google_cloud_firestore",
  "parameters": {
    "authentication": "oAuth2",
    "resource": "collection",
    "operation": "getAll",
    "projectId": "my-project-123",
    "database": "(default)",
    "returnAll": false,
    "limit": 50
  }
}
```

### Error Handling

| Mode | Behavior |
|------|----------|
| **stop** | Halts workflow on first error |
| **continue** | Skips failed items, passes successful ones through |
| **errorPort** | Routes failed items to Error output port |

## Tips

Create, read, update, delete, and query documents and collections in Google Cloud Firestore. Use when you need NoSQL document storage operations or structured queries against Firestore. Returns documents with decoded fields and metadata.

- **`Database` is almost always `(default)`.** Only change it if you created a named Firestore database in the project.
- **Nested collections use a path.** `users/user123/orders` addresses a subcollection; the Document ID for a get or delete may itself be a relative path such as `docId/subcollection/subDocId`.
- **`Columns` filters what gets written.** Leave it empty to write the whole item; name fields to keep unrelated workflow metadata out of the document.
- **Upsert needs a key that exists on every item.** Update Key names the item field whose value becomes the document ID; an item where that field is missing or empty fails rather than creating an unnamed document.
- **`Get` and `Upsert` batch across items.** All the items reaching the node in one run are grouped into a single Firestore call per project and database, so a large batch is far cheaper than one call per item.
- **Query takes a raw structuredQuery.** Supply the JSON object Firestore's `runQuery` expects, including its `from` clause; values inside `where` use Firestore's typed form such as `{"integerValue":"18"}`.
- **`Get Many` and `Query` fan out** — each document becomes its own item, so downstream nodes process documents individually.