> ## Documentation Index > Fetch the complete documentation index at: https://docs.pinkfish.ai/llms.txt > Use this file to discover all available pages before exploring further. # datastore-unstructured > Unstructured key-value storage — flexible JSON documents with no schema **Server path:** `/datastore-unstructured` | **Type:** Embedded | **PCID required:** No ## Tools | Tool | Description | | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [`datastore-unstructured_batch_create_items`](#datastore-unstructured_batch_create_items) | Create multiple items at once (max 500). More efficient than calling create\_item repeatedly. Each item can have any content type. Returns \{ created, failed } with counts. | | [`datastore-unstructured_create_collection`](#datastore-unstructured_create_collection) | Create a new unstructured datastore collection (flexible key-value storage with no schema). Content can be any type. Returns \{ id, isStructured: false } - use the "id" field as collectionId for subsequent operations. For structured datastores with schemas, use the datastore-structured server. | | [`datastore-unstructured_delete_collection`](#datastore-unstructured_delete_collection) | Delete an unstructured datastore collection and all its data. Returns \{ message } on success. WARNING: This is a destructive operation that cannot be undone. | | [`datastore-unstructured_create_item`](#datastore-unstructured_create_item) | Create a new item in an unstructured datastore (or update if key exists). Content can be ANY type - string, number, object, array. No schema validation. Returns \{ id, key } - use "id" as itemId for get/update/delete operations. | | [`datastore-unstructured_delete_item`](#datastore-unstructured_delete_item) | Delete an item by itemId (recommended) or by key. Returns \{ message } on success. Using key without sortField deletes ALL items with that key. Prefer itemId for precision. | | [`datastore-unstructured_get_collection`](#datastore-unstructured_get_collection) | Get collection details for an unstructured datastore. Returns \{ id, name, description, type, isStructured: false }. Use this to verify a collection is unstructured before performing operations. | | [`datastore-unstructured_get_item`](#datastore-unstructured_get_item) | Get a single item by its itemId. Returns \{ id, key, content, metadata, createdAt, updatedAt }. Use when you have the specific item ID from a previous create/list operation. | | [`datastore-unstructured_get_item_by_key`](#datastore-unstructured_get_item_by_key) | Get item(s) by their key. Returns an array of all items with matching key (may be multiple). Use when you know the item key but not the itemId. | | [`datastore-unstructured_list_collections`](#datastore-unstructured_list_collections) | List all available unstructured datastore collections (flexible key-value storage). Returns an array of collections, each with \{ id, name, type, isStructured: false }. Use the "id" field as collectionId for subsequent operations. For structured datastores with schemas, use the datastore-structured server. | | [`datastore-unstructured_list_items`](#datastore-unstructured_list_items) | List/browse items with pagination and sorting. Returns items with pagination metadata (totalCount, hasNextPage, hasPrevPage). Use format="full" to include content, or "light" for metadata only. Supports sorting by createdAt, updatedAt, key, or sortField. | | [`datastore-unstructured_search`](#datastore-unstructured_search) | Search items by text query with fuzzy/exact/prefix matching. Returns an array of matching items with relevance scores. Use when you need to find items containing specific text but don't know their key or ID. | | [`datastore-unstructured_update_item`](#datastore-unstructured_update_item) | Update an existing item by itemId. Returns \{ id, key } on success. Only provided fields are changed - others remain unchanged. Requires itemId from create/list/get operations. | | [`datastore-unstructured_analytics_query`](#datastore-unstructured_analytics_query) | Run analytics on collection data using natural language. Translates questions into BigQuery aggregations (COUNT, SUM, AVG, MIN, MAX), groupings, computed columns, and filtered summaries. Returns dynamic columns and rows — not full datastore items. Use this for questions like "how many items per key prefix?", "average content length", "count items by metadata category", "items created per month". For filtering/returning full items, use datastore-unstructured\_natural\_query instead. | | [`datastore-unstructured_natural_query`](#datastore-unstructured_natural_query) | Query data using natural language. Two modes:
• "natural-search" — filters and returns matching items (e.g. "find items with key containing test").
• "natural-answer" — generates an AI analysis with calculations (e.g. "how many items have metadata category=work?").
PAGINATION (natural-search only):
The first call translates your query into SQL via an LLM. The response includes a `translation` object and `pagination` metadata.
To fetch the next page, pass the SAME `translation` back (this skips the LLM) and increment `offset` by your `limit`.
Example — page through 100 items at a time:
Page 1: \{ query: "recent items", mode: "natural-search", limit: 100 }
Page 2: \{ query: "recent items", mode: "natural-search", limit: 100, offset: 100, translation: \ }
Page 3: \{ query: "recent items", mode: "natural-search", limit: 100, offset: 200, translation: \ }
Stop when pagination.hasNextPage is false.
RETURN ALL (natural-search only):
Set returnAll: true to fetch every matching item in one call (up to 50,000 rows).
WARNING: The response payload is limited to \~6 MB (AWS Lambda). Wide rows or large text fields may hit this before 50,000. If you get a payload error, switch to paginated mode with a smaller limit.
CHOOSING A LIMIT:
You control the page size via `limit`. Pick a value that balances throughput vs. payload size. Common choices: 100-500 for interactive use, 1000-5000 for batch processing, returnAll for workflows needing the full dataset. | *** ## datastore-unstructured\_batch\_create\_items Create multiple items at once (max 500). More efficient than calling create\_item repeatedly. Each item can have any content type. Returns \{ created, failed } with counts. **Parameters:** | Parameter | Type | Required | Default | Description | | ---------------- | ------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | `collectionId` | string | Yes | — | Collection ID (not name) to add the items to - e.g. "KCny7nGXpBzWNYpJzC0b". Use datastore-unstructured\_list\_collections tool to get collection ID. | | `items` | any | Yes | — | Array of items to create, each with key, content (any type), optional metadata object, and optional sortField | | `triggerChanges` | boolean | No | `true` | Whether to trigger webhooks on change | | `proxyId` | string | No | — | Proxy ID to access a shared datastore collection. Requires X-API-Key header. | ```json theme={null} { "type": "object", "properties": { "collectionId": { "type": "string", "description": "Collection ID (not name) to add the items to - e.g. \"KCny7nGXpBzWNYpJzC0b\". Use datastore-unstructured_list_collections tool to get collection ID." }, "items": { "type": "effects", "description": "Array of items to create, each with key, content (any type), optional metadata object, and optional sortField" }, "triggerChanges": { "type": "boolean", "default": true, "description": "Whether to trigger webhooks on change" }, "proxyId": { "type": "string", "description": "Proxy ID to access a shared datastore collection. Requires X-API-Key header." } }, "required": [ "collectionId", "items" ] } ``` *** ## datastore-unstructured\_create\_collection Create a new unstructured datastore collection (flexible key-value storage with no schema). Content can be any type. Returns \{ id, isStructured: false } - use the "id" field as collectionId for subsequent operations. For structured datastores with schemas, use the datastore-structured server. **Parameters:** | Parameter | Type | Required | Default | Description | | --------------- | ------ | -------- | ------- | --------------------------------------------------------------------------------- | | `name` | string | Yes | — | Display name for the collection | | `description` | string | No | — | Optional description of the collection purpose | | `createdBy` | string | Yes | — | User ID creating the collection - use the current user ID or a service identifier | | `createdByName` | string | Yes | — | Display name shown as creator - use the current user name or service name | ```json theme={null} { "type": "object", "properties": { "name": { "type": "string", "description": "Display name for the collection" }, "description": { "type": "string", "description": "Optional description of the collection purpose" }, "createdBy": { "type": "string", "description": "User ID creating the collection - use the current user ID or a service identifier" }, "createdByName": { "type": "string", "description": "Display name shown as creator - use the current user name or service name" } }, "required": [ "name", "createdBy", "createdByName" ] } ``` *** ## datastore-unstructured\_delete\_collection Delete an unstructured datastore collection and all its data. Returns \{ message } on success. WARNING: This is a destructive operation that cannot be undone. **Parameters:** | Parameter | Type | Required | Default | Description | | -------------- | ------ | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------- | | `collectionId` | string | Yes | — | Collection ID to delete - e.g. "KCny7nGXpBzWNYpJzC0b". Use datastore-unstructured\_list\_collections tool to get collection ID. | ```json theme={null} { "type": "object", "properties": { "collectionId": { "type": "string", "description": "Collection ID to delete - e.g. \"KCny7nGXpBzWNYpJzC0b\". Use datastore-unstructured_list_collections tool to get collection ID." } }, "required": [ "collectionId" ] } ``` *** ## datastore-unstructured\_create\_item Create a new item in an unstructured datastore (or update if key exists). Content can be ANY type - string, number, object, array. No schema validation. Returns \{ id, key } - use "id" as itemId for get/update/delete operations. **Parameters:** | Parameter | Type | Required | Default | Description | | ---------------- | ------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | `collectionId` | string | Yes | — | Collection ID (not name) to add the item to - e.g. "KCny7nGXpBzWNYpJzC0b". Use datastore-unstructured\_list\_collections tool to get collection ID. | | `key` | string | Yes | — | Unique identifier key for the item within the collection (required) | | `content` | string | Yes | — | Content to store (required). Can be any type - string, number, boolean, object, or array. No schema validation. | | `sortField` | string | No | — | Optional sort field for organizing items with the same key | | `metadata` | object | No | — | Optional metadata object for categorization (e.g. \{"category": "work", "priority": "high"}) | | `triggerChanges` | boolean | No | `true` | Whether to trigger webhooks on change | | `proxyId` | string | No | — | Proxy ID to access a shared datastore collection. Requires X-API-Key header. | ```json theme={null} { "type": "object", "properties": { "collectionId": { "type": "string", "description": "Collection ID (not name) to add the item to - e.g. \"KCny7nGXpBzWNYpJzC0b\". Use datastore-unstructured_list_collections tool to get collection ID." }, "key": { "type": "string", "description": "Unique identifier key for the item within the collection (required)" }, "content": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "object", "additionalProperties": true }, { "type": "array", "items": { "type": "unknown" } } ], "description": "Content to store (required). Can be any type - string, number, boolean, object, or array. No schema validation." }, "sortField": { "type": "string", "description": "Optional sort field for organizing items with the same key" }, "metadata": { "type": "object", "additionalProperties": true, "description": "Optional metadata object for categorization (e.g. {\"category\": \"work\", \"priority\": \"high\"})" }, "triggerChanges": { "type": "boolean", "default": true, "description": "Whether to trigger webhooks on change" }, "proxyId": { "type": "string", "description": "Proxy ID to access a shared datastore collection. Requires X-API-Key header." } }, "required": [ "collectionId", "key", "content" ] } ``` *** ## datastore-unstructured\_delete\_item Delete an item by itemId (recommended) or by key. Returns \{ message } on success. Using key without sortField deletes ALL items with that key. Prefer itemId for precision. **Parameters:** | Parameter | Type | Required | Default | Description | | -------------- | ------ | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | `collectionId` | string | Yes | — | Collection ID (not name) that the item belongs to - e.g. "KCny7nGXpBzWNYpJzC0b". Use datastore-unstructured\_list\_collections tool to get collection ID. | | `itemId` | string | No | — | Item ID to delete (recommended method - use either itemId or key, not both) | | `key` | string | No | — | Item key to delete (alternative method - use either itemId or key, not both). WARNING: Deletes ALL items with this key if sortField not provided. | | `sortField` | string | No | — | Sort field to delete a specific key+sortField combination (only used with key parameter) | | `proxyId` | string | No | — | Proxy ID to access a shared datastore collection. Requires X-API-Key header. | ```json theme={null} { "type": "object", "properties": { "collectionId": { "type": "string", "description": "Collection ID (not name) that the item belongs to - e.g. \"KCny7nGXpBzWNYpJzC0b\". Use datastore-unstructured_list_collections tool to get collection ID." }, "itemId": { "type": "string", "description": "Item ID to delete (recommended method - use either itemId or key, not both)" }, "key": { "type": "string", "description": "Item key to delete (alternative method - use either itemId or key, not both). WARNING: Deletes ALL items with this key if sortField not provided." }, "sortField": { "type": "string", "description": "Sort field to delete a specific key+sortField combination (only used with key parameter)" }, "proxyId": { "type": "string", "description": "Proxy ID to access a shared datastore collection. Requires X-API-Key header." } }, "required": [ "collectionId" ] } ``` *** ## datastore-unstructured\_get\_collection Get collection details for an unstructured datastore. Returns \{ id, name, description, type, isStructured: false }. Use this to verify a collection is unstructured before performing operations. **Parameters:** | Parameter | Type | Required | Default | Description | | -------------- | ------ | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `collectionId` | string | Yes | — | Collection ID to get details for - e.g. "KCny7nGXpBzWNYpJzC0b". Use datastore-unstructured\_list\_collections to find the collection ID. | ```json theme={null} { "type": "object", "properties": { "collectionId": { "type": "string", "description": "Collection ID to get details for - e.g. \"KCny7nGXpBzWNYpJzC0b\". Use datastore-unstructured_list_collections to find the collection ID." } }, "required": [ "collectionId" ] } ``` *** ## datastore-unstructured\_get\_item Get a single item by its itemId. Returns \{ id, key, content, metadata, createdAt, updatedAt }. Use when you have the specific item ID from a previous create/list operation. **Parameters:** | Parameter | Type | Required | Default | Description | | -------------- | ------ | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | `collectionId` | string | Yes | — | Collection ID (not name) that the item belongs to - e.g. "KCny7nGXpBzWNYpJzC0b". Use datastore-unstructured\_list\_collections tool to get collection ID. | | `itemId` | string | Yes | — | Unique datastore item ID to retrieve (itemId, not key) | | `proxyId` | string | No | — | Proxy ID to access a shared datastore collection. Requires X-API-Key header. | ```json theme={null} { "type": "object", "properties": { "collectionId": { "type": "string", "description": "Collection ID (not name) that the item belongs to - e.g. \"KCny7nGXpBzWNYpJzC0b\". Use datastore-unstructured_list_collections tool to get collection ID." }, "itemId": { "type": "string", "description": "Unique datastore item ID to retrieve (itemId, not key)" }, "proxyId": { "type": "string", "description": "Proxy ID to access a shared datastore collection. Requires X-API-Key header." } }, "required": [ "collectionId", "itemId" ] } ``` *** ## datastore-unstructured\_get\_item\_by\_key Get item(s) by their key. Returns an array of all items with matching key (may be multiple). Use when you know the item key but not the itemId. **Parameters:** | Parameter | Type | Required | Default | Description | | -------------- | ------ | -------- | ------- | --------------------------------------------------------------------------------------- | | `collectionId` | string | Yes | — | Collection ID (not name) that the item belongs to - e.g. "KCny7nGXpBzWNYpJzC0b" | | `key` | string | Yes | — | Unique key identifier for the item within the collection | | `sortField` | string | No | — | Optional sort field to uniquely identify the item when multiple items have the same key | | `proxyId` | string | No | — | Proxy ID to access a shared datastore collection. Requires X-API-Key header. | ```json theme={null} { "type": "object", "properties": { "collectionId": { "type": "string", "description": "Collection ID (not name) that the item belongs to - e.g. \"KCny7nGXpBzWNYpJzC0b\"" }, "key": { "type": "string", "description": "Unique key identifier for the item within the collection" }, "sortField": { "type": "string", "description": "Optional sort field to uniquely identify the item when multiple items have the same key" }, "proxyId": { "type": "string", "description": "Proxy ID to access a shared datastore collection. Requires X-API-Key header." } }, "required": [ "collectionId", "key" ] } ``` *** ## datastore-unstructured\_list\_collections List all available unstructured datastore collections (flexible key-value storage). Returns an array of collections, each with \{ id, name, type, isStructured: false }. Use the "id" field as collectionId for subsequent operations. For structured datastores with schemas, use the datastore-structured server. **Parameters:** None ```json theme={null} { "type": "object", "properties": {} } ``` *** ## datastore-unstructured\_list\_items List/browse items with pagination and sorting. Returns items with pagination metadata (totalCount, hasNextPage, hasPrevPage). Use format="full" to include content, or "light" for metadata only. Supports sorting by createdAt, updatedAt, key, or sortField. **Parameters:** | Parameter | Type | Required | Default | Description | | -------------- | ------ | -------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------- | | `collectionId` | string | Yes | — | Collection ID (not name) - e.g. "KCny7nGXpBzWNYpJzC0b". Use datastore-unstructured\_list\_collections tool to get collection ID. | | `limit` | number | No | `50` | Maximum number of items to return (default: 50, max: 1000) | | `offset` | number | No | — | Offset for pagination (default: 0). Use with limit to page through results. Example: limit=50\&offset=50 for page 2. | | `orderedBy` | string | No | `"createdAt:desc"` | Sorting field and direction - format: "\:\" | | `format` | string | No | `"light"` | Response format: "light" for metadata only (id, key, createdAt, updatedAt), "full" to include content | | `proxyId` | string | No | — | Proxy ID to access a shared datastore collection. Requires X-API-Key header. | ```json theme={null} { "type": "object", "properties": { "collectionId": { "type": "string", "description": "Collection ID (not name) - e.g. \"KCny7nGXpBzWNYpJzC0b\". Use datastore-unstructured_list_collections tool to get collection ID." }, "limit": { "type": "number", "default": 50, "description": "Maximum number of items to return (default: 50, max: 1000)" }, "offset": { "type": "number", "description": "Offset for pagination (default: 0). Use with limit to page through results. Example: limit=50&offset=50 for page 2." }, "orderedBy": { "type": "string", "enum": [ "createdAt:desc", "createdAt:asc", "updatedAt:desc", "updatedAt:asc", "key:asc", "key:desc", "sortField:asc", "sortField:desc" ], "default": "createdAt:desc", "description": "Sorting field and direction - format: \":\"" }, "format": { "type": "string", "enum": [ "light", "full" ], "default": "light", "description": "Response format: \"light\" for metadata only (id, key, createdAt, updatedAt), \"full\" to include content" }, "proxyId": { "type": "string", "description": "Proxy ID to access a shared datastore collection. Requires X-API-Key header." } }, "required": [ "collectionId" ] } ``` *** ## datastore-unstructured\_search Search items by text query with fuzzy/exact/prefix matching. Returns an array of matching items with relevance scores. Use when you need to find items containing specific text but don't know their key or ID. **Parameters:** | Parameter | Type | Required | Default | Description | | -------------- | ------- | -------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `collectionId` | string | Yes | — | Collection ID (not name) to search in - e.g. "KCny7nGXpBzWNYpJzC0b". Use datastore-unstructured\_list\_collections tool to get collection ID. | | `q` | string | Yes | — | Search query string to find in documents (required). For multi-word queries, words must be adjacent in the source text (phrase-based search). Example: "quick brown" matches "The quick brown fox" but "quick fox" won't match if words are separated. | | `field` | string | No | `"all"` | Field to search: "all" for comprehensive search, "content" for main item content, "key" for primary identifier, "sortField" for secondary identifier. | | `type` | string | No | `"fuzzy"` | Search type: "fuzzy" (default - handles typos), "exact" (precise matches), "prefix" (starts with) | | `threshold` | number | No | `0.3` | Fuzzy matching sensitivity from 0.0 (strict) to 1.0 (lenient), default: 0.3 | | `limit` | number | No | `50` | Maximum number of results to return (default: 50, max: 1000) | | `compiled` | boolean | No | `false` | Output format: false (default - JSON with snippets & scores), true (plain text with full content, RAG-like) | | `queryParams` | object | No | `{}` | Pre-filter by document fields using "content.*" or "metadata.*" keys (e.g. \{"metadata.category": "work"}) | | `proxyId` | string | No | — | Proxy ID to access a shared datastore collection. Requires X-API-Key header. | ```json theme={null} { "type": "object", "properties": { "collectionId": { "type": "string", "description": "Collection ID (not name) to search in - e.g. \"KCny7nGXpBzWNYpJzC0b\". Use datastore-unstructured_list_collections tool to get collection ID." }, "q": { "type": "string", "description": "Search query string to find in documents (required). For multi-word queries, words must be adjacent in the source text (phrase-based search). Example: \"quick brown\" matches \"The quick brown fox\" but \"quick fox\" won't match if words are separated." }, "field": { "type": "string", "enum": [ "all", "content", "sortField", "key" ], "default": "all", "description": "Field to search: \"all\" for comprehensive search, \"content\" for main item content, \"key\" for primary identifier, \"sortField\" for secondary identifier." }, "type": { "type": "string", "enum": [ "fuzzy", "exact", "prefix" ], "default": "fuzzy", "description": "Search type: \"fuzzy\" (default - handles typos), \"exact\" (precise matches), \"prefix\" (starts with)" }, "threshold": { "type": "number", "default": 0.3, "description": "Fuzzy matching sensitivity from 0.0 (strict) to 1.0 (lenient), default: 0.3" }, "limit": { "type": "number", "default": 50, "description": "Maximum number of results to return (default: 50, max: 1000)" }, "compiled": { "type": "boolean", "default": false, "description": "Output format: false (default - JSON with snippets & scores), true (plain text with full content, RAG-like)" }, "queryParams": { "type": "object", "additionalProperties": true, "default": {}, "description": "Pre-filter by document fields using \"content.*\" or \"metadata.*\" keys (e.g. {\"metadata.category\": \"work\"})" }, "proxyId": { "type": "string", "description": "Proxy ID to access a shared datastore collection. Requires X-API-Key header." } }, "required": [ "collectionId", "q" ] } ``` *** ## datastore-unstructured\_update\_item Update an existing item by itemId. Returns \{ id, key } on success. Only provided fields are changed - others remain unchanged. Requires itemId from create/list/get operations. **Parameters:** | Parameter | Type | Required | Default | Description | | ---------------- | ------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | `collectionId` | string | Yes | — | Collection ID (not name) that the item belongs to - e.g. "KCny7nGXpBzWNYpJzC0b". Use datastore-unstructured\_list\_collections tool to get collection ID. | | `itemId` | string | Yes | — | Item ID to update (itemId not the key). Can be obtained when creating the item or by listing/getting/searching items. Required for updates. | | `content` | string | Yes | — | Updated content - can be any type. Only provided fields are updated; others remain unchanged. | | `metadata` | object | No | — | Optional updated metadata object with key-value pairs. Only provided metadata fields are updated; original key and sortField are preserved. | | `triggerChanges` | boolean | No | `true` | Whether to trigger webhooks on change | | `proxyId` | string | No | — | Proxy ID to access a shared datastore collection. Requires X-API-Key header. | ```json theme={null} { "type": "object", "properties": { "collectionId": { "type": "string", "description": "Collection ID (not name) that the item belongs to - e.g. \"KCny7nGXpBzWNYpJzC0b\". Use datastore-unstructured_list_collections tool to get collection ID." }, "itemId": { "type": "string", "description": "Item ID to update (itemId not the key). Can be obtained when creating the item or by listing/getting/searching items. Required for updates." }, "content": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "object", "additionalProperties": true }, { "type": "array", "items": { "type": "unknown" } } ], "description": "Updated content - can be any type. Only provided fields are updated; others remain unchanged." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Optional updated metadata object with key-value pairs. Only provided metadata fields are updated; original key and sortField are preserved." }, "triggerChanges": { "type": "boolean", "default": true, "description": "Whether to trigger webhooks on change" }, "proxyId": { "type": "string", "description": "Proxy ID to access a shared datastore collection. Requires X-API-Key header." } }, "required": [ "collectionId", "itemId", "content" ] } ``` *** ## datastore-unstructured\_analytics\_query Run analytics on collection data using natural language. Translates questions into BigQuery aggregations (COUNT, SUM, AVG, MIN, MAX), groupings, computed columns, and filtered summaries. Returns dynamic columns and rows — not full datastore items. Use this for questions like "how many items per key prefix?", "average content length", "count items by metadata category", "items created per month". For filtering/returning full items, use datastore-unstructured\_natural\_query instead. **Parameters:** | Parameter | Type | Required | Default | Description | | -------------- | ------ | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `collectionId` | string | Yes | — | Collection ID of an unstructured datastore - e.g. "KCny7nGXpBzWNYpJzC0b" | | `query` | string | Yes | — | Natural language analytics question - e.g. "how many items per key prefix?", "average content length", "count by metadata category", "items created per day this week" | | `limit` | number | No | `10000` | Maximum number of result rows to return (default 10000, max 50000). For aggregations this is usually small. | | `proxyId` | string | No | — | Proxy ID to access a shared datastore collection. Requires X-API-Key header. | ```json theme={null} { "type": "object", "properties": { "collectionId": { "type": "string", "description": "Collection ID of an unstructured datastore - e.g. \"KCny7nGXpBzWNYpJzC0b\"" }, "query": { "type": "string", "description": "Natural language analytics question - e.g. \"how many items per key prefix?\", \"average content length\", \"count by metadata category\", \"items created per day this week\"" }, "limit": { "type": "number", "default": 10000, "description": "Maximum number of result rows to return (default 10000, max 50000). For aggregations this is usually small." }, "proxyId": { "type": "string", "description": "Proxy ID to access a shared datastore collection. Requires X-API-Key header." } }, "required": [ "collectionId", "query" ] } ``` *** ## datastore-unstructured\_natural\_query Query data using natural language. Two modes: • "natural-search" — filters and returns matching items (e.g. "find items with key containing test"). • "natural-answer" — generates an AI analysis with calculations (e.g. "how many items have metadata category=work?"). PAGINATION (natural-search only): The first call translates your query into SQL via an LLM. The response includes a `translation` object and `pagination` metadata. To fetch the next page, pass the SAME `translation` back (this skips the LLM) and increment `offset` by your `limit`. Example — page through 100 items at a time: Page 1: \{ query: "recent items", mode: "natural-search", limit: 100 } Page 2: \{ query: "recent items", mode: "natural-search", limit: 100, offset: 100, translation: \ } Page 3: \{ query: "recent items", mode: "natural-search", limit: 100, offset: 200, translation: \ } Stop when pagination.hasNextPage is false. RETURN ALL (natural-search only): Set returnAll: true to fetch every matching item in one call (up to 50,000 rows). WARNING: The response payload is limited to \~6 MB (AWS Lambda). Wide rows or large text fields may hit this before 50,000. If you get a payload error, switch to paginated mode with a smaller limit. CHOOSING A LIMIT: You control the page size via `limit`. Pick a value that balances throughput vs. payload size. Common choices: 100-500 for interactive use, 1000-5000 for batch processing, returnAll for workflows needing the full dataset. **Parameters:** | Parameter | Type | Required | Default | Description | | -------------- | ------- | -------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `collectionId` | string | Yes | — | Collection ID of a datastore - e.g. "KCny7nGXpBzWNYpJzC0b" | | `query` | string | Yes | — | Natural language query or question (e.g. "find recent items", "how many items have metadata category=work?") | | `mode` | string | No | `"natural-search"` | "natural-search" returns filtered items, "natural-answer" generates AI analysis with calculations | | `limit` | number | No | — | Page size — number of items to return per request (default: 1000, max: 50000). Only applies to natural-search mode. Choose based on your use case: 100-500 for interactive browsing, 1000-5000 for batch processing. The response payload is capped at \~6 MB, so very wide rows may require a smaller limit. | | `offset` | number | No | — | Number of items to skip (default: 0). Only applies to natural-search mode. To page through results: set offset = 0 for page 1, offset = limit for page 2, offset = limit \* 2 for page 3, etc. Always pass the `translation` from the first response when using offset > 0 to avoid redundant LLM calls. | | `returnAll` | boolean | No | — | When true, fetches ALL matching items in a single call (up to 50,000 rows). Only applies to natural-search mode. Use in workflows when you need the complete result set. WARNING: Response payload is limited to \~6 MB. If rows are wide (many columns, large text), you may hit the payload limit before 50,000 rows. In that case, use paginated mode instead. | | `translation` | any | No | — | Cached SQL translation from a previous response. IMPORTANT: When provided, the LLM call is skipped entirely and the query goes straight to BigQuery — this is faster and cheaper. Always pass this on page 2+ to avoid re-translating the same query. Copy the entire `translation` object from the first page response and send it unchanged. | | `proxyId` | string | No | — | Proxy ID to access a shared datastore collection. Requires X-API-Key header. | ```json theme={null} { "type": "object", "properties": { "collectionId": { "type": "string", "description": "Collection ID of a datastore - e.g. \"KCny7nGXpBzWNYpJzC0b\"" }, "query": { "type": "string", "description": "Natural language query or question (e.g. \"find recent items\", \"how many items have metadata category=work?\")" }, "mode": { "type": "string", "enum": [ "natural-search", "natural-answer" ], "default": "natural-search", "description": "\"natural-search\" returns filtered items, \"natural-answer\" generates AI analysis with calculations" }, "limit": { "type": "number", "description": "Page size — number of items to return per request (default: 1000, max: 50000). Only applies to natural-search mode. Choose based on your use case: 100-500 for interactive browsing, 1000-5000 for batch processing. The response payload is capped at ~6 MB, so very wide rows may require a smaller limit." }, "offset": { "type": "number", "description": "Number of items to skip (default: 0). Only applies to natural-search mode. To page through results: set offset = 0 for page 1, offset = limit for page 2, offset = limit * 2 for page 3, etc. Always pass the `translation` from the first response when using offset > 0 to avoid redundant LLM calls." }, "returnAll": { "type": "boolean", "description": "When true, fetches ALL matching items in a single call (up to 50,000 rows). Only applies to natural-search mode. Use in workflows when you need the complete result set. WARNING: Response payload is limited to ~6 MB. If rows are wide (many columns, large text), you may hit the payload limit before 50,000 rows. In that case, use paginated mode instead." }, "translation": { "type": "effects", "description": "Cached SQL translation from a previous response. IMPORTANT: When provided, the LLM call is skipped entirely and the query goes straight to BigQuery — this is faster and cheaper. Always pass this on page 2+ to avoid re-translating the same query. Copy the entire `translation` object from the first page response and send it unchanged." }, "proxyId": { "type": "string", "description": "Proxy ID to access a shared datastore collection. Requires X-API-Key header." } }, "required": [ "collectionId", "query" ] } ```