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.

Supported databases

Agent Studio recognizes the data source’s SQL dialect and parses, validates, and normalizes every query to it — a query written in generic SQL is rewritten into syntax the target database accepts. Supported dialects are:

• Amazon Redshift
• Databricks
• Google BigQuery
• IBM DB2
• Microsoft SQL Server
• Oracle
• PostgreSQL
• SAP HANA
• Snowflake
• Teradata
• Trino (formerly PrestoSQL)

Note

Dialect handling is automatic. Agent Studio derives the dialect from the data product’s data source, so pointing a data product at one of these databases is all that is needed — there is nothing to configure.

If you need a dialect that is not listed, contact Alation to inquire about support.

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.
auth_mode	No	string	Fixed	Set to datasource_service_account to let the query use an admin-configured shared service account when the user has no credentials of their own. Requires the service account feature.
allow_fallback_auth	No	boolean	Fixed	When true, falls back to the data source’s default credentials if the user has none.

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.

Tip

To let end users query without each authenticating to the data source, use a shared service account (auth_mode) or fallback auth (allow_fallback_auth), depending on whether your instance has the service account feature. See Credentials for data product queries.

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

• Credentials for data product queries
• Get Data Schema Tool
• Query agent