> For the complete documentation index, see [llms.txt](https://docs.amigo.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.amigo.ai/developer-guide/platform-api/functions/workspace-data-queries.md). # Workspace Data Queries Workspace data queries let you register parameterized SQL templates that the agent can invoke as tools during conversations. Unlike platform functions (which execute against an external data warehouse), data queries run directly against the custom tables you have provisioned in your workspace. The agent runtime registers each query as a tool named `wsq_`, so the agent can call it mid-conversation to fetch data from your workspace's custom tables. ## Prerequisites Your workspace must have at least one custom table provisioned through [Workspace Tables](/developer-guide/platform-api/data-world-model/workspace-tables.md) before you can deploy a data query. `query_id` (a UUID returned by create) is the immutable route handle. `name` is a mutable, workspace-unique label that registers the agent tool `wsq_`. ## Permissions * **List / Get / Invoke**: Requires `Workspace.view` permission. * **Create / Update / Delete**: Requires `Workspace.update` permission. ## Create a Data Query {% openapi src="" path="/v1/{workspace\_id}/data\_queries" method="post" %} {% endopenapi %} Creates a new data query and returns it with a server-generated `query_id` (`201 Created`). Creating a query whose `name` already exists in the workspace returns `409 Conflict`. To change an existing query, use `PATCH` on its `query_id` (see [Update a Data Query](#update-a-data-query)). ### Deploy-Time Validation The platform validates the query before storing it: * SQL must parse as a single valid statement. * Multi-statement SQL is rejected. * Session-state commands are rejected. * Every `:name` placeholder in the SQL must have a matching entry in `parameters`, and every declared parameter must appear as a placeholder in the SQL. * Default values must match their declared type. ### Example Request ```json { "name": "active_patients_by_location", "description": "Returns active patients at a given location, optionally filtered by status.", "sql_template": "SELECT patient_id, name, status FROM custom.patients WHERE location_id = :location_id AND (:status IS NULL OR status = :status) LIMIT :max_rows", "parameters": [ { "name": "location_id", "type": "string", "description": "UUID of the location to filter by." }, { "name": "status", "type": "string", "description": "Optional patient status filter.", "default": null }, { "name": "max_rows", "type": "integer", "description": "Maximum number of rows to return.", "default": 50 } ], "timeout_ms": 5000 } ``` ### Example Response ```json { "id": "9f8e7d6c-5b4a-3210-fedc-ba9876543210", "name": "active_patients_by_location", "description": "Returns active patients at a given location, optionally filtered by status.", "sql_template": "SELECT patient_id, name, status FROM custom.patients WHERE location_id = :location_id AND (:status IS NULL OR status = :status) LIMIT :max_rows", "parameters": [ { "name": "location_id", "type": "string", "description": "UUID of the location to filter by." }, { "name": "status", "type": "string", "description": "Optional patient status filter.", "default": null }, { "name": "max_rows", "type": "integer", "description": "Maximum number of rows to return.", "default": 50 } ], "timeout_ms": 5000, "last_invoked_at": null, "deployed_at": "2026-07-15T10:30:00+00:00", "deployed_by": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } ``` ## Update a Data Query {% openapi src="" path="/v1/{workspace\_id}/data\_queries/{query\_id}" method="patch" %} {% endopenapi %} Partially updates an existing data query, addressed by its immutable `query_id`. Any subset of `name`, `description`, `sql_template`, `parameters`, and `timeout_ms` may be supplied; omitted fields are left unchanged. The `name` is mutable but must remain unique within the workspace. The same deploy-time validation applies to any updated SQL. ## List Data Queries {% openapi src="" path="/v1/{workspace\_id}/data\_queries" method="get" %} {% endopenapi %} Returns the workspace's registered data queries, ordered newest first. Results are paginated: when `has_more` is `true`, pass the returned `continuation_token` on the next request to fetch the following page. ### Example Response ```json { "items": [ { "id": "9f8e7d6c-5b4a-3210-fedc-ba9876543210", "name": "active_patients_by_location", "description": "Returns active patients at a given location.", "sql_template": "SELECT patient_id, name FROM custom.patients WHERE location_id = :location_id", "parameter_count": 1, "timeout_ms": 5000, "last_invoked_at": null, "deployed_at": "2026-07-15T10:30:00+00:00", "deployed_by": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } ], "has_more": false, "continuation_token": null } ``` List items carry a `parameter_count` instead of the full `parameters` array. Fetch a single query by ID to get its parameter definitions. ## Get a Data Query {% openapi src="" path="/v1/{workspace\_id}/data\_queries/{query\_id}" method="get" %} {% endopenapi %} Returns a single data query by its `query_id`. ## Delete a Data Query {% openapi src="" path="/v1/{workspace\_id}/data\_queries/{query\_id}" method="delete" %} {% endopenapi %} Removes a registered data query, addressed by its `query_id`. Deleting a query cascades to its parameter rows automatically. Returns `204 No Content` on success. ## Invoke a Data Query {% openapi src="" path="/v1/{workspace\_id}/data\_queries/{query\_id}/invoke" method="post" %} {% endopenapi %} Executes a registered data query, addressed by its `query_id`, with the provided arguments. ### Example Request ```json { "input": { "location_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "max_rows": 10 } } ``` ### Example Response ```json { "result": [ { "patient_id": "abc-123", "name": "Jane Doe", "status": "active" } ], "duration_ms": 42.5, "row_count": 1 } ``` ## Agent Tool Registration When a conversation session starts, the platform loads all data queries for the workspace and registers each one as a tool available to the agent. The tool name follows the pattern `wsq_` (for example, a query named `active_patients_by_location` becomes the tool `wsq_active_patients_by_location`). The agent sees the query's description and input schema, and can call it like any other tool. Data query tools are constrained to tables provisioned for the workspace. This is distinct from platform function tools (prefixed `fn_`), which use their configured external data source. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.amigo.ai/developer-guide/platform-api/functions/workspace-data-queries.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.