firestore-update-document

Description

The firestore-update-document tool allows you to update existing documents in Firestore. It supports all Firestore data types using Firestore’s native JSON format. The tool can perform both full document updates (replacing all fields) or selective field updates using an update mask. When using an update mask, fields referenced in the mask but not present in the document data will be deleted from the document, following Firestore’s native behavior.

Parameters

Output

The tool returns a map containing:

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"}

Update Modes

Full Document Update (Merge All)

When updateMask is not provided, the tool performs a merge operation that updates all fields specified in documentData while preserving other existing fields in the document.

Selective Field Update

When updateMask is provided, only the fields listed in the mask are updated. This allows for precise control over which fields are modified, added, or deleted. To delete a field, include it in the updateMask but omit it from documentData.

Reference

Examples

Basic Document Update (Full Merge)

tools:
  update-user-doc:
    kind: firestore-update-document
    source: my-firestore
    description: Update a user document

Usage:

{
  "documentPath": "users/user123",
  "documentData": {
    "name": {
      "stringValue": "Jane Doe"
    },
    "lastUpdated": {
      "timestampValue": "2025-01-15T10:30:00Z"
    },
    "status": {
      "stringValue": "active"
    },
    "score": {
      "integerValue": "150"
    }
  }
}

Selective Field Update with Update Mask

{
  "documentPath": "users/user123",
  "documentData": {
    "email": {
      "stringValue": "newemail@example.com"
    },
    "profile": {
      "mapValue": {
        "fields": {
          "bio": {
            "stringValue": "Updated bio text"
          },
          "avatar": {
            "stringValue": "https://example.com/new-avatar.jpg"
          }
        }
      }
    }
  },
  "updateMask": ["email", "profile.bio", "profile.avatar"]
}

Update with Field Deletion

To delete fields, include them in the updateMask but omit them from documentData:

{
  "documentPath": "users/user123",
  "documentData": {
    "name": {
      "stringValue": "John Smith"
    }
  },
  "updateMask": ["name", "temporaryField", "obsoleteData"],
  "returnData": true
}

In this example:

• name will be updated to “John Smith”
• temporaryField and obsoleteData will be deleted from the document (they are in the mask but not in the data)

Complex Update with Nested Data

{
  "documentPath": "companies/company456",
  "documentData": {
    "metadata": {
      "mapValue": {
        "fields": {
          "lastModified": {
            "timestampValue": "2025-01-15T14:30:00Z"
          },
          "modifiedBy": {
            "stringValue": "admin@company.com"
          }
        }
      }
    },
    "locations": {
      "arrayValue": {
        "values": [
          {
            "mapValue": {
              "fields": {
                "city": {
                  "stringValue": "San Francisco"
                },
                "coordinates": {
                  "geoPointValue": {
                    "latitude": 37.7749,
                    "longitude": -122.4194
                  }
                }
              }
            }
          },
          {
            "mapValue": {
              "fields": {
                "city": {
                  "stringValue": "New York"
                },
                "coordinates": {
                  "geoPointValue": {
                    "latitude": 40.7128,
                    "longitude": -74.0060
                  }
                }
              }
            }
          }
        ]
      }
    },
    "revenue": {
      "doubleValue": 5678901.23
    }
  },
  "updateMask": ["metadata", "locations", "revenue"]
}

Update with All Data Types

{
  "documentPath": "test-documents/doc789",
  "documentData": {
    "stringField": {
      "stringValue": "Updated string"
    },
    "integerField": {
      "integerValue": "999"
    },
    "doubleField": {
      "doubleValue": 2.71828
    },
    "booleanField": {
      "booleanValue": false
    },
    "nullField": {
      "nullValue": null
    },
    "timestampField": {
      "timestampValue": "2025-01-15T16:45:00Z"
    },
    "geoPointField": {
      "geoPointValue": {
        "latitude": 51.5074,
        "longitude": -0.1278
      }
    },
    "bytesField": {
      "bytesValue": "VXBkYXRlZCBkYXRh"
    },
    "arrayField": {
      "arrayValue": {
        "values": [
          {
            "stringValue": "updated1"
          },
          {
            "integerValue": "200"
          },
          {
            "booleanValue": true
          }
        ]
      }
    },
    "mapField": {
      "mapValue": {
        "fields": {
          "nestedString": {
            "stringValue": "updated nested value"
          },
          "nestedNumber": {
            "doubleValue": 88.88
          }
        }
      }
    },
    "referenceField": {
      "referenceValue": "users/updatedUser"
    }
  },
  "returnData": true
}

Authentication

The tool can be configured to require authentication:

tools:
  secure-update-doc:
    kind: firestore-update-document
    source: prod-firestore
    description: Update documents with authentication required
    authRequired:
      - google-oauth
      - api-key

Error Handling

Common errors include:

• Document not found (when using update with a non-existent document)
• Invalid document path
• Missing or invalid document data
• Permission denied (if Firestore security rules block the operation)
• Invalid data type conversions

Best Practices

1. Use update masks for precision: When you only need to update specific fields, use the updateMask parameter to avoid unintended changes
2. Always use typed values: Every field must be wrapped with its appropriate type indicator (e.g., {"stringValue": "text"})
3. Integer values can be strings: The tool accepts integer values as strings (e.g., {"integerValue": "1500"})
4. Use returnData sparingly: Only set to true when you need to verify the exact data after the update
5. Validate data before sending: Ensure your data matches Firestore’s native JSON format
6. Handle timestamps properly: Use RFC3339 format for timestamp strings
7. Base64 encode binary data: Binary data must be base64 encoded in the bytesValue field
8. Consider security rules: Ensure your Firestore security rules allow document updates
9. Delete fields using update mask: To delete fields, include them in the updateMask but omit them from documentData
10. Test with non-production data first: Always test your updates on non-critical documents first

Differences from Add Documents

• Purpose: Updates existing documents vs. creating new ones
• Document must exist: For standard updates (though not using updateMask will create if missing with given document id)
• Update mask support: Allows selective field updates
• Field deletion: Supports removing specific fields by including them in the mask but not in the data
• Returns updateTime: Instead of createTime

Related Tools

• firestore-add-documents - Add new documents to Firestore
• firestore-get-documents - Retrieve documents by their paths
• firestore-query-collection - Query documents in a collection
• firestore-delete-documents - Delete documents from Firestore