firestore-data

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Usage

使用说明

All scripts can be executed using Node.js. Replace

<param_name>

and

<param_value>

with actual values.

Bash:

node <skill_dir>/scripts/<script_name>.js '{"<param_name>": "<param_value>"}'

PowerShell:

node <skill_dir>/scripts/<script_name>.js '{\"<param_name>\": \"<param_value>\"}'

Note: The scripts automatically load the environment variables from various .env files. Do not ask the user to set vars unless skill executions fails due to env var absence.

所有脚本均可通过Node.js执行。将

<param_name>

和

<param_value>

替换为实际值。

Bash：

node <skill_dir>/scripts/<script_name>.js '{"<param_name>": "<param_value>"}'

PowerShell：

node <skill_dir>/scripts/<script_name>.js '{\"<param_name>\": \"<param_value>\"}'

注意：脚本会自动从多个.env文件加载环境变量。除非因缺少环境变量导致技能执行失败，否则不要要求用户设置变量。

Scripts

脚本

add_documents

添加文档

Adds a new document to a Firestore collection. Please follow the best practices :

Always use typed values in the documentData: Every field must be wrapped with its appropriate type indicator (e.g., {"stringValue": "text"})
Integer values can be strings in the documentData: 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

向Firestore集合中添加新文档。请遵循以下最佳实践：

始终在documentData中使用类型化值：每个字段必须用相应的类型指示器包裹（例如：{"stringValue": "text"}）
整数值可在documentData中以字符串形式传入：工具接受字符串形式的整数值（例如：{"integerValue": "1500"}）
谨慎使用returnData：仅当需要验证写入的精确数据时，才将其设置为true
发送前验证数据：确保数据符合Firestore的原生JSON格式
正确处理时间戳：时间戳字符串使用RFC3339格式
Base64编码二进制数据：二进制数据必须在bytesValue字段中进行Base64编码
考虑安全规则：确保Firestore安全规则允许在目标集合中创建文档

Parameters

参数

Name	Type	Description	Required	Default
collectionPath	string	The relative path of the collection where the document will be added to (e.g., 'users' or 'users/userId/posts'). Note: This is a relative path, NOT an absolute path like 'projects/{project_id}/databases/{database_id}/documents/...'	Yes
documentData	object	The document data in Firestore's native JSON format. Each field must be wrapped with a type indicator:

Strings: {"stringValue": "text"}
Integers: {"integerValue": "123"} or {"integerValue": 123}
Doubles: {"doubleValue": 123.45}
Booleans: {"booleanValue": true}
Timestamps: {"timestampValue": "2025-01-07T10:00:00Z"}
GeoPoints: {"geoPointValue": {"latitude": 34.05, "longitude": -118.24}}
Arrays: {"arrayValue": {"values": [{"stringValue": "item1"}, {"integerValue": "2"}]}}
Maps: {"mapValue": {"fields": {"key1": {"stringValue": "value1"}, "key2": {"booleanValue": true}}}}
Null: {"nullValue": null}
Bytes: {"bytesValue": "base64EncodedString"}
References: {"referenceValue": "collection/document"} | Yes | | | returnData | boolean | If set to true the output will have the data of the created document. This flag if set to false will help avoid overloading the context of the agent. | No |
```
false
```
|

名称	类型	描述	是否必填	默认值
collectionPath	string	要添加文档的集合的相对路径（例如：'users'或'users/userId/posts'）。注意：这是相对路径，而非类似'projects/{project_id}/databases/{database_id}/documents/...'的绝对路径	是
documentData	object	Firestore原生JSON格式的文档数据。每个字段必须用类型指示器包裹：

字符串：{"stringValue": "text"}
整数：{"integerValue": "123"}或{"integerValue": 123}
浮点数：{"doubleValue": 123.45}
布尔值：{"booleanValue": true}
时间戳：{"timestampValue": "2025-01-07T10:00:00Z"}
地理点：{"geoPointValue": {"latitude": 34.05, "longitude": -118.24}}
数组：{"arrayValue": {"values": [{"stringValue": "item1"}, {"integerValue": "2"}]}}
映射：{"mapValue": {"fields": {"key1": {"stringValue": "value1"}, "key2": {"booleanValue": true}}}}
空值：{"nullValue": null}
字节：{"bytesValue": "base64EncodedString"}
引用：{"referenceValue": "collection/document"} | 是 | | | returnData | boolean | 如果设置为true，输出将包含创建的文档数据。设置为false有助于避免Agent的上下文过载。 | 否 |
```
false
```
|

delete_documents

删除文档

Delete multiple documents from Firestore

从Firestore中删除多个文档

Parameters

参数

Name	Type	Description	Required	Default
documentPaths	array	Array of relative document paths to delete from Firestore (e.g., 'users/userId' or 'users/userId/posts/postId'). Note: These are relative paths, NOT absolute paths like 'projects/{project_id}/databases/{database_id}/documents/...'	Yes

名称	类型	描述	是否必填	默认值
documentPaths	array	要从Firestore删除的文档相对路径数组（例如：'users/userId'或'users/userId/posts/postId'）。注意：这些是相对路径，而非类似'projects/{project_id}/databases/{database_id}/documents/...'的绝对路径	是

get_documents

获取文档

Gets multiple documents from Firestore by their paths

通过路径从Firestore获取多个文档

Parameters

参数

Name	Type	Description	Required	Default
documentPaths	array	Array of relative document paths to retrieve from Firestore (e.g., 'users/userId' or 'users/userId/posts/postId'). Note: These are relative paths, NOT absolute paths like 'projects/{project_id}/databases/{database_id}/documents/...'	Yes

名称	类型	描述	是否必填	默认值
documentPaths	array	要从Firestore检索的文档相对路径数组（例如：'users/userId'或'users/userId/posts/postId'）。注意：这些是相对路径，而非类似'projects/{project_id}/databases/{database_id}/documents/...'的绝对路径	是

list_collections

列出集合

List Firestore collections for a given parent path

列出指定父路径下的Firestore集合

Parameters

参数

Name	Type	Description	Required	Default
parentPath	string	Relative parent document path to list subcollections from (e.g., 'users/userId'). If not provided, lists root collections. Note: This is a relative path, NOT an absolute path like 'projects/{project_id}/databases/{database_id}/documents/...'	No

名称	类型	描述	是否必填	默认值
parentPath	string	要列出子集合的父文档相对路径（例如：'users/userId'）。如果未提供，则列出根集合。注意：这是相对路径，而非类似'projects/{project_id}/databases/{database_id}/documents/...'的绝对路径	否

query_collection

查询集合

Retrieves one or more Firestore documents from a collection in a database in the current project by a collection with a full document path. Use this if you know the exact path of a collection and the filtering clause you would like for the document.

通过完整文档路径从当前项目数据库的集合中检索一个或多个Firestore文档。当你知道集合的精确路径以及要应用于文档的过滤条件时使用此脚本。

Parameters

参数

Name	Type	Description	Required	Default
collectionPath	string	The relative path to the Firestore collection to query (e.g., 'users' or 'users/userId/posts'). Note: This is a relative path, NOT an absolute path like 'projects/{project_id}/databases/{database_id}/documents/...'	Yes
filters	array	Array of filter objects to apply to the query. Each filter is a JSON string with:

field: The field name to filter on
op: The operator to use ("<", "<=", ">", ">=", "==", "!=", "array-contains", "array-contains-any", "in", "not-in")
value: The value to compare against (can be string, number, boolean, or array) Example: {"field": "age", "op": ">", "value": 18} | Yes | | | orderBy | string | JSON string specifying the field and direction to order by (e.g., {"field": "name", "direction": "ASCENDING"}). Leave empty if not specified | Yes | | | limit | integer | The maximum number of documents to return | No |
```
100
```
| | analyzeQuery | boolean | If true, returns query explain metrics including execution statistics | No |
```
false
```
|

名称	类型	描述	是否必填	默认值
collectionPath	string	要查询的Firestore集合的相对路径（例如：'users'或'users/userId/posts'）。注意：这是相对路径，而非类似'projects/{project_id}/databases/{database_id}/documents/...'的绝对路径	是
filters	array	要应用于查询的过滤器对象数组。每个过滤器是一个JSON字符串，包含：

field：要过滤的字段名称
op：使用的操作符（"<", "<=", ">", ">=", "==", "!=", "array-contains", "array-contains-any", "in", "not-in")
value：要比较的值（可以是字符串、数字、布尔值或数组）示例：{"field": "age", "op": ">", "value": 18} | 是 | | | orderBy | string | 指定排序字段和方向的JSON字符串（例如：{"field": "name", "direction": "ASCENDING"}）。如果不需要排序则留空 | 是 | | | limit | integer | 返回的最大文档数量 | 否 |
```
100
```
| | analyzeQuery | boolean | 如果为true，返回包含执行统计信息的查询解释指标 | 否 |
```
false
```
|

update_document

更新文档

Updates an existing document in Firestore. Supports both full document updates and selective field updates using an update mask. Please follow the best practices:

Use update masks for precision: When you only need to update specific fields, use the updateMask parameter to avoid unintended changes
Always use typed values in the documentData: Every field must be wrapped with its appropriate type indicator (e.g., {"stringValue": "text"})
Delete fields using update mask: To delete fields, include them in the updateMask but omit them from documentData
Integer values can be strings: The skill accepts integer values as strings (e.g., {"integerValue": "1500"})
Use returnData sparingly: Only set to true when you need to verify the exact data after the update
Handle timestamps properly: Use RFC3339 format for timestamp strings
Consider security rules: Ensure your Firestore security rules allow document updates

更新Firestore中的现有文档。支持使用更新掩码进行全文档更新和选择性字段更新。请遵循以下最佳实践：

使用更新掩码提高精度：仅需更新特定字段时，使用updateMask参数避免意外更改
始终在documentData中使用类型化值：每个字段必须用相应的类型指示器包裹（例如：{"stringValue": "text"}）
使用更新掩码删除字段：要删除字段，将其包含在updateMask中但在documentData中省略
整数值可采用字符串形式：技能接受字符串形式的整数值（例如：{"integerValue": "1500"}）
谨慎使用returnData：仅当需要验证更新后的精确数据时，才将其设置为true
正确处理时间戳：时间戳字符串使用RFC3339格式
考虑安全规则：确保Firestore安全规则允许文档更新

Parameters

参数

Name	Type	Description	Required	Default
documentPath	string	The relative path of the document which needs to be updated (e.g., 'users/userId' or 'users/userId/posts/postId'). Note: This is a relative path, NOT an absolute path like 'projects/{project_id}/databases/{database_id}/documents/...'	Yes
documentData	object	The document data in Firestore's native JSON format. Each field must be wrapped with a type indicator:

Strings: {"stringValue": "text"}
Integers: {"integerValue": "123"} or {"integerValue": 123}
Doubles: {"doubleValue": 123.45}
Booleans: {"booleanValue": true}
Timestamps: {"timestampValue": "2025-01-07T10:00:00Z"}
GeoPoints: {"geoPointValue": {"latitude": 34.05, "longitude": -118.24}}
Arrays: {"arrayValue": {"values": [{"stringValue": "item1"}, {"integerValue": "2"}]}}
Maps: {"mapValue": {"fields": {"key1": {"stringValue": "value1"}, "key2": {"booleanValue": true}}}}
Null: {"nullValue": null}
Bytes: {"bytesValue": "base64EncodedString"}
References: {"referenceValue": "collection/document"} | Yes | | | updateMask | array | The selective fields to update. If not provided, all fields in documentData will be updated. When provided, only the specified fields will be updated. Fields referenced in the mask but not present in documentData will be deleted from the document | No | | | returnData | boolean | If set to true the output will have the data of the updated document. This flag if set to false will help avoid overloading the context of the agent. | No |
```
false
```
|

名称	类型	描述	是否必填	默认值
documentPath	string	需要更新的文档的相对路径（例如：'users/userId'或'users/userId/posts/postId'）。注意：这是相对路径，而非类似'projects/{project_id}/databases/{database_id}/documents/...'的绝对路径	是
documentData	object	Firestore原生JSON格式的文档数据。每个字段必须用类型指示器包裹：

字符串：{"stringValue": "text"}
整数：{"integerValue": "123"}或{"integerValue": 123}
浮点数：{"doubleValue": 123.45}
布尔值：{"booleanValue": true}
时间戳：{"timestampValue": "2025-01-07T10:00:00Z"}
地理点：{"geoPointValue": {"latitude": 34.05, "longitude": -118.24}}
数组：{"arrayValue": {"values": [{"stringValue": "item1"}, {"integerValue": "2"}]}}
映射：{"mapValue": {"fields": {"key1": {"stringValue": "value1"}, "key2": {"booleanValue": true}}}}
空值：{"nullValue": null}
字节：{"bytesValue": "base64EncodedString"}
引用：{"referenceValue": "collection/document"} | 是 | | | updateMask | array | 要更新的选择性字段。如果未提供，将更新documentData中的所有字段。提供后，仅更新指定字段。掩码中引用但未在documentData中出现的字段将从文档中删除 | 否 | | | returnData | boolean | 如果设置为true，输出将包含更新后的文档数据。设置为false有助于避免Agent的上下文过载。 | 否 |
```
false
```
|