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_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 | 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_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_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_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 | 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 | 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 | 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 | 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 | 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_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: <translation from page 1> }
Page 3: { query: “recent items”, mode: “natural-search”, limit: 100, offset: 200, translation: <translation from page 1> }
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_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 | 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. |
