datastore-structured_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 rows by status?”, “average salary by department”, “top 10 products by revenue”, “count of items created per month”. For filtering/returning full rows, use datastore-structured_natural_query instead. |
datastore-structured_batch_create_items | Create multiple rows at once (max 500). More efficient than calling datastore-structured_create_item repeatedly. Call datastore-structured_get_collection first to discover column labels and select options. For “select” type fields, values MUST be one of the allowed options from the schema. |
datastore-structured_create_collection | Create a new datastore collection (table with defined columns/schema). For unstructured storage, use the datastore-unstructured server. Returns { id, isStructured, schema } - use the “id” field as collectionId for subsequent operations. |
datastore-structured_create_collection_from_csv | Create a new datastore from a CSV file. Auto-generates schema from CSV headers. Just provide a file URL and collection name - schema is inferred automatically. Returns { collectionId, imported, total, schema } - use the “collectionId” field for subsequent operations. |
datastore-structured_create_collection_with_template | Create a new datastore with a pre-built template. Templates include schema and sample data to get started quickly. Use datastore-structured_list_templates first to see available options. Returns { id, isStructured, schema } - use the “id” field as collectionId for subsequent operations. |
datastore-structured_create_item | Create a new row (or update if key exists). Call datastore-structured_get_collection first to discover column labels and select options. For “select” type fields, values MUST be one of the allowed options from the schema. Returns { id, key } - use “id” as itemId for get/update/delete operations. |
datastore-structured_delete_collection | Delete a datastore collection and all its data. Returns { message } on success. WARNING: This is a destructive operation that cannot be undone. |
datastore-structured_delete_item | Delete a single row by itemId (recommended) or by key. Using key without sortField deletes ALL items with that key. Prefer itemId for precision. |
datastore-structured_get_collection | REQUIRED: Get collection schema before any write operations. Returns column labels, field types, and allowed options for select fields. Always call this first to understand the table structure. |
datastore-structured_get_item | Get a single item (row) by its itemId. Use when you have the specific item ID from a previous operation. Returns full item data (content with field values, metadata, timestamps). For encrypted content, set decryptSecrets=true. |
datastore-structured_get_item_by_key | Get item(s) by their key. Use when you know the item key but not the itemId. Returns array of all items with matching key, or single item if sortField also provided. |
datastore-structured_import_data | Import data from a CSV file into an existing datastore. CSV column headers must match schema field labels. Returns { imported, total, failed } with counts. |
datastore-structured_list_collections | List all available structured datastore collections (tables with schemas). Returns an array of collections, each with { id, name, type, schema }. Use the “id” field as collectionId for subsequent operations. For unstructured data, use the datastore-unstructured server. |
datastore-structured_list_items | List/browse items (rows) with pagination and sorting. Returns items with pagination metadata (totalCount, hasNextPage, hasPrevPage). Use format=“full” to include item content, or “light” for metadata only. Supports sorting by any column name (e.g. “Amount:desc”) or system fields (createdAt, updatedAt, key, sortField). |
datastore-structured_list_templates | List available templates for creating datastores. Returns an array of templates, each with { id, name, description, category, schema }. Use the template “id” when calling datastore-structured_create_collection_with_template. |
datastore-structured_migrate_sortfield | Change default sort order and regenerate sortField for all items. Long-running (30-60s for large collections). Use when you need to change how items are ordered by default. |
datastore-structured_natural_query | Query data using natural language. Two modes:
• “natural-search” — filters and returns matching rows (e.g. “active users from last week”).
• “natural-answer” — generates an AI analysis with calculations (e.g. “what is average age?”).
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: “active users”, mode: “natural-search”, limit: 100 }
Page 2: { query: “active users”, mode: “natural-search”, limit: 100, offset: 100, translation: <translation from page 1> }
Page 3: { query: “active users”, 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 row 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-structured_search | Search rows by text query with fuzzy/exact/prefix matching. Use when you need to find items containing specific text but don’t know their key or ID. Supports field-specific search (content, key, sortField). For structured queries, prefer datastore-structured_natural_query. |
datastore-structured_update_item | Update an existing row by itemId (partial update). Provide only the fields you want to change - other fields remain unchanged. For “select” type fields, values MUST match one of the allowed options from the schema. Requires itemId (from create/list/get operations). |
datastore-structured_update_schema | Modify a structured datastore schema (add / remove / rename columns). WARNING: this is a full replace — any existing field NOT included in fields is deleted. Field ids (f_1, f_2, …) MUST remain stable: a field that still exists must keep its existing id. Only assign a new f_N id to brand-new fields. Renaming means changing the label, never the id. |
