firestore-add-documents Tool
A “firestore-add-documents” tool adds document to a given collection path.
4 minute read
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
This tool can be used with the following database sources:
| Source Name |
|---|
| Firestore Source |
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
kind: tools
name: add-company-doc
type: firestore-add-documents
source: my-firestore
description: Add a new company document
Usage:
{
"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
{
"collectionPath": "companies",
"documentData": {
"name": {
"stringValue": "Tech Innovations Inc"
},
"contactInfo": {
"mapValue": {
"fields": {
"email": {
"stringValue": "info@techinnovations.com"
},
"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
{
"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:
kind: tools
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
bytesValuefield - 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 pathsfirestore-query-collection- Query documents in a collectionfirestore-delete-documents- Delete documents from Firestore
Feedback
Was this page helpful?
Glad to hear it! Please tell us how we can improve.
Sorry to hear that. Please tell us how we can improve.