SQL Execution Tool

SQL Execution Tool

This tool runs a SQL query against the database behind a data product and returns the result as a table. It is the workhorse behind agents like Query, Data Product Query, and Analytics Agent.

Queries are read-only. Mutating statements (UPDATE, DELETE, INSERT, and so on) are not allowed. The data product must be backed by a SQL-compatible data source.

When to use it

Add this tool to any agent that needs to answer questions from data by running queries. Pair it with Get Data Schema so the agent can learn the available tables and columns first.

Parameters

Parameter	Required	Type	Suggested scope	What it does
data_product_id	Yes	string	User input	The data product to query against.
sql	Yes	string	Agent determined	The query to run.
result_table_name	Yes	string	Agent determined	A short, descriptive name for the result table.
data_product_version	No	string	Fixed or User input	A specific version of the data product.
pre_exec_sql	No	string	Fixed	SQL to run before the main query, e.g. to set session context.
auth_id	No	string	Fixed or User input	The authentication credentials to use for the query.

Note

data_product_id is a good fit for User input so callers choose what to query, while sql and result_table_name are normally Agent determined — the agent writes the query from the question. See Configuring tool parameters.

Example usage

{
  "data_product_id": "my-data-product",
  "sql": "SELECT region, SUM(amount) FROM sales GROUP BY region;",
  "result_table_name": "sales_by_region"
}

Output

The query result as a table. Very large results may have rows or columns trimmed.

See also

• Get Data Schema Tool
• Query agent