# Querying Treasure Data CDP

Ask a question in plain language and Studio turns it into SQL, runs it against your Treasure Data CDP, and answers in the conversation. The SQL is never hidden: the agent runs it through `tdx query` in its sandbox, and the tool call in the chat shows the exact statement that produced the numbers you are reading. That visibility is the point — the agent drafts the query, and you decide whether to trust it.

**This page is about your Treasure Data CDP.** Studio can also query a connected Snowflake or Databricks warehouse, and that path is a different one — see [Querying a Connected Warehouse](#querying-a-connected-warehouse).

Turn on the SQL skills first
The default plugin set does not include the SQL skills, so a new account writes SQL without any Treasure AI-specific guidance. Enabling them makes a large difference to query quality — see [Turn On the SQL Skills](#turn-on-the-sql-skills) below.

## Prerequisites

- Signed in to Treasure AI Studio ([Getting Started](/products/ai-studio/getting-started))
- At least one database accessible in your Treasure AI account
- The **Download** database permission in your policy — without it a query runs but its result never reaches the chat, see [Fetching Results Requires the CDP Download Permission](#fetching-results-requires-the-cdp-download-permission)


## Fetching Results Requires the CDP Download Permission

Running a query from Treasure AI Studio takes two Treasure Data CDP permissions, not one: permission to **query** the database, and the **Download** database permission that allows the result to leave it. With query permission alone the statement executes and the retrieval fails — the tool call returns an error instead of rows, and there is no partial result to fall back on.

Treasure AI Studio is designed as a service independent of Treasure Data CDP: the query runs as a job inside the CDP, but the rows it produces are delivered to the agent's execution environment outside it. Reading a result in the chat therefore takes data out of the CDP rather than viewing it in place, and the CDP's permission model governs that as a download — the same control that applies to downloading a result from the Treasure AI console. The 50-record preview the console falls back to without the permission is a console feature; Studio has no equivalent.

Grant it in the CDP, not in Studio: **Control Panel** → **Policies** → **Permissions** → **Database Workbench**, where **Full Access** already includes download and **Limited Access** exposes a **Download Database** toggle. See [Setting Policy Based Database Permissions in Treasure Console](/products/control-panel/security/policies/setting-policy-based-database-permissions-in-td-console) and the [policy-based database permissions matrix](/products/control-panel/security/policies/policy-based-database-permissions-matrix).

To check what you have, ask the agent to run `tdx policy` and read the `Databases` line under **Effective Permissions** — it has to list `download`, or `manage`, which includes it. See [`tdx policy`](/treasure-code/commands/policy).

The requirement applies to every route a query result takes into the chat: `tdx query --output` writing it to a file, and the `tdx job result` step of the [Hive job path](#trino-runs-in-the-chat-hive-runs-as-a-job).

## Turn On the SQL Skills

Skills are what teach the agent how Treasure AI's SQL actually works — `td_interval` for time filtering, partition pruning, when a query Trino cannot hold belongs on Hive. Without them, the agent writes generic SQL from whatever it can infer about your schema. **If the SQL it writes looks wrong, suspect this before anything else:** it is a common explanation, and a quick one to rule out.

The **sql-skills** plugin lives in the pre-installed **td-skills** marketplace but is **not enabled by default**. To turn it on, open **Settings → Marketplace**, expand **td-skills**, and set **sql-skills** to **On** (see [Plugin Marketplace](/products/ai-studio/skills/marketplace) for how the Default / On / Off control works).

| Skill | What it teaches the agent |
|  --- | --- |
| `trino` | Treasure AI's Trino dialect and its TD-specific functions (`td_interval`, `td_time_range`, `td_time_string`) |
| `time-filtering` | `td_interval` patterns and partition pruning, so a time-bounded query scans a fraction of the table |
| `trino-optimizer` | Performance work: CTAS, UDP bucketing, magic comments, approximate aggregates |
| `hive` | Hive SQL and its Hive-only features, for workloads Trino cannot hold. Running it takes the job path below, not `tdx query` |
| `trino-to-hive-migration` | Rewriting a Trino query as Hive when it fails on memory |


Once enabled, skills apply on their own whenever a request falls in their domain — there is nothing to invoke per question. See [Skills & Marketplace](/products/ai-studio/skills/skills).

## Asking for Data

Describe the result you want, not the SQL:

- "Show me the top 10 customers by revenue in the last 30 days"
- "How many rows are in the `pageviews` table?"
- "What columns does `mydb.users` have?"


The agent explores the schema when it needs to (`tdx databases`, `tdx tables`, `tdx describe`), writes the SQL, runs it with `tdx query`, and reads the output back before answering you. Each of those steps is a tool call you can expand.

Naming the specifics is what makes the answer reproducible. A request that fixes the table, the time range, and the grain — "daily signups from `marketing.signups` for the last 30 days, excluding test accounts" — leaves the agent far less to guess at than "how are signups doing".

When the same specifics apply every time, stop repeating them: term definitions, the tables a project uses, and standing filters belong in the work folder's instructions or your organization's custom instruction, and a query that is hard to get right belongs in a skill. See [Where Your Business Knowledge Belongs](/products/ai-studio/concepts/reliable-answers#where-your-business-knowledge-belongs).

## Watching the Query Run

A query appears in the chat as a tool call, and the row tells you where it is:

- **Running** — a spinner, with the command preview in monospace
- **Finished** — a checkmark, plus a duration badge when the call took a second or longer
- **Failed** — a warning icon and an **Exit** badge carrying the command's exit code


Expand the row to see the full command and its raw output. Output longer than 12 lines is cut with a **Show N more lines** toggle, and the **Copy** button on the row copies the command so you can re-run it yourself.

Note
The result of a query is text inside that tool call — Studio does not render it as a sortable table. The tidy table you usually see is the agent restating the numbers in its reply. See [Reading Query Results](/products/ai-studio/query/query-results).

## Reviewing the SQL Before You Trust It

Expand the tool call and read the statement itself. Three things are worth a glance every time:

- **The table it chose.** The agent picks from what it discovered; a similarly named table is an easy mistake to miss in prose but obvious in the `FROM` clause.
- **The time bound.** A missing or wrong interval is a common reason a number comes back off by an order of magnitude.
- **The filters you assumed.** Test accounts, cancelled orders, and soft-deleted rows are excluded only if someone said so.


If something is wrong, say what is wrong rather than asking again from scratch — "exclude rows where `status = 'test'` and re-run" keeps the rest of the query intact.

## Keeping Results a Usable Size

`tdx query` caps output at 40 rows only when it is attached to an interactive terminal. Inside the sandbox it is not, so **a `SELECT *` returns every row**. That floods the tool output, and it leaves the AI less room for the rest of the conversation — the session starts summarizing and losing earlier detail sooner than it otherwise would.

Two habits avoid it:

- Ask for an explicit limit, or an aggregate rather than rows: "count them by day" instead of "show me the rows".
- For a result set you actually need in full, ask the agent to write it to a file — `tdx query --output results.csv "..."` — and open it in the [spreadsheet viewer](/products/ai-studio/files/file-viewers#spreadsheet-viewer), which renders it read-only. Download it to sort or filter in Excel. Files in a work folder outlive the chat.


## Querying a Connected Warehouse

A connected Snowflake or Databricks warehouse is not reached through tdx. Studio exposes the connector to the agent as its own set of tools, and the agent uses those instead — so most of this page does not carry across:

| What differs  | Treasure Data CDP  | Connected warehouse  |
|  --- | --- | --- |
| **How the agent runs SQL** | `tdx query` in the sandbox | The connector's own tools |
| **SQL dialect** | Trino, or Hive for heavy workloads | The warehouse's own dialect |
| **The SQL skills** | Apply — they teach Treasure AI's dialect and its functions | Do not apply. `td_interval` and the other TD functions do not exist there |
| **Permissions** | Your own Treasure AI account permissions | The role the connection was authorized with — for Snowflake, the fixed `PUBLIC` role |
| **Output options** | `--json`, `--output`, and the rest of the tdx flags | Whatever the connector returns |


What does carry across is everything about *reading* an answer: the SQL still appears in a tool call for you to review, the reply is still the model's restatement of the output, and the layers in [Answer Quality](/products/ai-studio/query/answer-quality) still apply. See [Connections](/products/ai-studio/connections) for setting a warehouse up, and its connector page for what the agent may reach.

## Trino Runs in the Chat; Hive Runs as a Job

`tdx query` is Trino only — it has no engine option, so a chat that "runs a query" is always running Trino, streaming the result straight back into the tool call.

Hive is reached a different way: the query is submitted as a job and its result fetched afterwards.

```bash
tdx job submit --job-type hive -f query.sql --database mydb
tdx job result <job-id>
```

Ask the agent for those two steps rather than expecting `tdx query` to switch engines. Because submission and results are separate calls, a Hive run does not stream — the agent submits, then comes back for the output. You can also run the query in the Treasure AI console, which is often simpler for a one-off.

This is why the `hive` and `trino-to-hive-migration` skills are about **writing** correct Hive SQL: the execution path is yours to ask for.

## Stopping a Query

Clicking **Stop** ends the agent's turn. It does not necessarily cancel the statement already running on the query engine — that job may run to completion server-side. To stop the job itself, cancel it in the Treasure AI console, or ask the agent to list recent jobs with `tdx jobs` to find it.

## Running tdx Yourself

You can name the exact command instead of describing a result — "run `tdx describe mydb.users`" — and the agent runs it verbatim. Three things differ from tdx on your own machine:

- It runs against a **managed tdx installation inside the sandbox**, not a copy on your computer, so there is nothing to install and no local side effects
- **The chat is the only entry point.** There is no keyboard command palette
- **You cannot add your own MCP servers.** To give the agent another data source, use a [connection](/products/ai-studio/connections)


The command syntax is identical to running tdx locally. For the full CLI reference — every command, option, and output format — see [Treasure Code Commands](/treasure-code/commands/), and [`tdx query`](/treasure-code/commands/query) for query-specific options.

## Troubleshooting

| Issue | Solution |
|  --- | --- |
| The SQL ignores Treasure AI's own functions, or scans the whole table | The SQL skills are probably off. Enable **sql-skills** in **Settings → Marketplace** and ask again — see [Turn On the SQL Skills](#turn-on-the-sql-skills) |
| Query fails with "access denied" | Your account may not have access to that database. Ask the agent to run `tdx databases` to see what it can reach, and check with your administrator |
| The query runs, but reading its result is denied | Your policy is probably missing the **Download** database permission, which authorizes a result to leave the CDP. Ask the agent to run `tdx policy` and check the `Databases` line — see [Fetching Results Requires the CDP Download Permission](#fetching-results-requires-the-cdp-download-permission) |
| The query is slow, or fails on memory | Start by narrowing the time range — that alone often fixes it. Then ask for the `trino-optimizer` skill; if it still cannot run on Trino, have the agent rewrite it for Hive and submit it as a job ([Trino Runs in the Chat; Hive Runs as a Job](#trino-runs-in-the-chat-hive-runs-as-a-job)) |
| The answer looks wrong | Work through [When a Query Answer Looks Wrong](/products/ai-studio/query/answer-quality), which separates a bad prompt from a bad query from a bad interpretation |


## Next Steps

- [Reading Query Results](/products/ai-studio/query/query-results) — What the output actually looks like, and how to get results out
- [When a Query Answer Looks Wrong](/products/ai-studio/query/answer-quality) — What to check when a number or an insight looks wrong
- [Skills & Marketplace](/products/ai-studio/skills/skills) — Enabling the plugins that shape how the agent works
- [Charting a Result](/products/ai-studio/query/query-results#charting-a-result) — Turning a result into a chart