firestore-add-documents - Genai Toolbox

About

The firestore-add-documents tool allows you to add new documents to a Firestore collection. It supports all Firestore data types using Firestore's native JSON format. The tool automatically generates a unique document ID for each new document.

Compatible Sources

Parameters

Parameter	Type	Required	Description
`collectionPath`	string	Yes	The path of the collection where the document will be added
`documentData`	map	Yes	The data to be added as a document to the given collection. Must use Firestore's native JSON format with typed values
`returnData`	boolean	No	If set to true, the output will include the data of the created document. Defaults to false to help avoid overloading the context

Data Type Format

The tool requires Firestore's native JSON format for document data. Each field must be wrapped with its type indicator:

Basic Types

String: {"stringValue": "your string"}
Integer: {"integerValue": "123"} or {"integerValue": 123}
Double: {"doubleValue": 123.45}
Boolean: {"booleanValue": true}
Null: {"nullValue": null}
Bytes: {"bytesValue": "base64EncodedString"}
Timestamp: {"timestampValue": "2025-01-07T10:00:00Z"} (RFC3339 format)

Complex Types

GeoPoint: {"geoPointValue": {"latitude": 34.052235, "longitude": -118.243683}}
Array: {"arrayValue": {"values": [{"stringValue": "item1"}, {"integerValue": "2"}]}}
Map: {"mapValue": {"fields": {"key1": {"stringValue": "value1"}, "key2": {"booleanValue": true}}}}
Reference: {"referenceValue": "collection/document"}

Example

Basic Document Creation

yaml

kind: tool
name: add-company-doc
type: firestore-add-documents
source: my-firestore
description: Add a new company document

Usage:

json

{
  "collectionPath": "companies",
  "documentData": {
    "name": {
      "stringValue": "Acme Corporation"
    },
    "establishmentDate": {
      "timestampValue": "2000-01-15T10:30:00Z"
    },
    "location": {
      "geoPointValue": {
        "latitude": 34.052235,
        "longitude": -118.243683
      }
    },
    "active": {
      "booleanValue": true
    },
    "employeeCount": {
      "integerValue": "1500"
    },
    "annualRevenue": {
      "doubleValue": 1234567.89
    }
  }
}

With Nested Maps and Arrays

json

{
  "collectionPath": "companies",
  "documentData": {
    "name": {
      "stringValue": "Tech Innovations Inc"
    },
    "contactInfo": {
      "mapValue": {
        "fields": {
          "email": {
            "stringValue": "[email protected]"
          },
          "phone": {
            "stringValue": "+1-555-123-4567"
          },
          "address": {
            "mapValue": {
              "fields": {
                "street": {
                  "stringValue": "123 Innovation Drive"
                },
                "city": {
                  "stringValue": "San Francisco"
                },
                "state": {
                  "stringValue": "CA"
                },
                "zipCode": {
                  "stringValue": "94105"
                }
              }
            }
          }
        }
      }
    },
    "products": {
      "arrayValue": {
        "values": [
          {
            "stringValue": "Product A"
          },
          {
            "stringValue": "Product B"
          },
          {
            "mapValue": {
              "fields": {
                "productName": {
                  "stringValue": "Product C Premium"
                },
                "version": {
                  "integerValue": "3"
                },
                "features": {
                  "arrayValue": {
                    "values": [
                      {
                        "stringValue": "Advanced Analytics"
                      },
                      {
                        "stringValue": "Real-time Sync"
                      }
                    ]
                  }
                }
              }
            }
          }
        ]
      }
    }
  },
  "returnData": true
}

Complete Example with All Data Types

json

{
  "collectionPath": "test-documents",
  "documentData": {
    "stringField": {
      "stringValue": "Hello World"
    },
    "integerField": {
      "integerValue": "42"
    },
    "doubleField": {
      "doubleValue": 3.14159
    },
    "booleanField": {
      "booleanValue": true
    },
    "nullField": {
      "nullValue": null
    },
    "timestampField": {
      "timestampValue": "2025-01-07T15:30:00Z"
    },
    "geoPointField": {
      "geoPointValue": {
        "latitude": 37.7749,
        "longitude": -122.4194
      }
    },
    "bytesField": {
      "bytesValue": "SGVsbG8gV29ybGQh"
    },
    "arrayField": {
      "arrayValue": {
        "values": [
          {
            "stringValue": "item1"
          },
          {
            "integerValue": "2"
          },
          {
            "booleanValue": false
          }
        ]
      }
    },
    "mapField": {
      "mapValue": {
        "fields": {
          "nestedString": {
            "stringValue": "nested value"
          },
          "nestedNumber": {
            "doubleValue": 99.99
          }
        }
      }
    }
  }
}

Output Format

The tool returns a map containing:

Field	Type	Description
`documentPath`	string	The full resource name of the created document (e.g., `projects/{projectId}/databases/{databaseId}/documents/{document_path}`)
`createTime`	string	The timestamp when the document was created
`documentData`	map	The data that was added (only included when `returnData` is true)

Advanced Usage

Authentication

The tool can be configured to require authentication:

yaml

kind: tool
name: secure-add-docs
type: firestore-add-documents
source: prod-firestore
description: Add documents with authentication required
authRequired:
  - google-oauth
  - api-key

Best Practices

Always use typed values: Every field must be wrapped with its appropriate type indicator (e.g., {"stringValue": "text"})
Integer values can be strings: The tool accepts integer values as strings (e.g., {"integerValue": "1500"})
Use returnData sparingly: Only set to true when you need to verify the exact data that was written
Validate data before sending: Ensure your data matches Firestore's native JSON format
Handle timestamps properly: Use RFC3339 format for timestamp strings
Base64 encode binary data: Binary data must be base64 encoded in the bytesValue field
Consider security rules: Ensure your Firestore security rules allow document creation in the target collection

Troubleshooting

Common errors include:

Invalid collection path
Missing or invalid document data
Permission denied (if Firestore security rules block the operation)
Invalid data type conversions

Additional Resources

firestore-get-documents - Retrieve documents by their paths
firestore-query-collection - Query documents in a collection
firestore-delete-documents - Delete documents from Firestore