Query inspection tools

Seven tools for investigating any single query or job/run: raw SQL plus warehouse and concurrency context, a compact execution profile, parsed query fragments, the tables a query reads and writes, and per-job aggregates. Your agent typically chains them: fetch the query → look at the profile → break it into fragments → explore the cluster it belongs to.

All sample responses below use synthetic data.

`query_detail`

Returns the SQL, cost, signature, and default database for a query ID, along with the warehouse it ran on and how busy that warehouse was while it ran.

warehouse_name / warehouse_size — the warehouse and its size.
max_concurrency — peak number of queries running in parallel on the warehouse during this query.
avg_concurrency — average parallel queries on the warehouse during this query. High concurrency points at queueing/contention rather than the query itself.

Sample call

"What does query 01HXY8F3A4B5 look like, and was the warehouse busy?"

Sample response

{
  "query": "SELECT order_date, region, SUM(amount) FROM analytics.orders_fact WHERE order_date >= CURRENT_DATE - 30 GROUP BY 1, 2",
  "cost": 18.42,
  "query_signature": "analytics_daily &&& orders_rollup||a1b2c3d4",
  "default_database": "analytics_db",
  "warehouse_name": "ANALYTICS_WH",
  "warehouse_size": "X-Large",
  "max_concurrency": 12,
  "avg_concurrency": 7.4
}

`query_table_lineage`

Returns the tables a single query reads and writes: upstream_tables (its source tables) and downstream_tables (its destination table; empty for a read-only query). FQNs are uppercase as recorded in query_history. A table the query both reads and writes can appear in both lists.

Sample call

"What tables does query 01HXY8F3A4B5 read and write?"

Sample response

{
  "query_id": "01HXY8F3A4B5C6D7E8F9",
  "upstream_tables": ["ANALYTICS_DB.ANALYTICS.ORDERS_FACT", "ANALYTICS_DB.STATIC.REGIONS"],
  "downstream_tables": ["ANALYTICS_DB.ANALYTICS.ORDERS_DAILY_AGG"]
}

`query_profile_detail`

Returns the execution profile as a compact flat-line tree string (one operator per line, depth-first). Line format:

{step}.{node}:{node_type} c={cost%} o={output_rows} p={parent_step}.{parent_node} partitions=S/T {attrs}

c — own cost as % of total (omitted if 0; tiny non-zero values display as the literal token <0.01%)
o — output rows with K/M/B suffix
p — parent reference (omitted for root)
partitions — scanned/total for TableScan operators
attrs — remaining operator attributes as space-separated key=value

Low-cost subtrees (less than 1% cumulative) collapse into a summary line [...N nodes, tables: X, Y]; descendant TableScan nodes are still emitted inline so table references are preserved.

Note: Unlike the other tools on this page, query_profile_detail returns a plain-text string, not JSON. The flat-line format is denser than a JSON tree and consumes far fewer tokens when an agent reads it.

Sample call

"Why is query 01HXY8F3A4B5 slow?"

Sample response

1.1:Result c=60% o=720
1.2:Aggregate c=40% o=720 p=1.1 functions=sum(amount)
1.3:Filter c=12% o=1.4B p=1.2 filter=order_date>=CURRENT_DATE-30
1.4:TableScan c=28% o=1.4B p=1.3 partitions=12/365 table=analytics.orders_fact columns=[order_date,region,amount]

`query_fragments_for_query`

Returns the fragments parsed from a query's profile, each with an indented operator-tree text representation — the same format the similar-query cluster tools use to group fragments by shape. Ordered by fragment cost descending.

Sample call

"Break query 01HXY8F3A4B5 into its operator fragments."

Sample response

[
  {
    "fragment_id": "f1d2c3b4-1111-2222-3333-444455556666",
    "operator_tree_text": "Aggregate attrs={\"functions\": \"sum(amount)\", \"group_by\": \"order_date, region\"}\n  Filter attrs={\"filter_condition\": \"order_date >= CURRENT_DATE - 30\"}\n    TableScan attrs={\"table_name\": \"analytics.orders_fact\", \"columns\": [\"order_date\", \"region\", \"amount\"]}\n"
  }
]

`fragment_detail`

Returns the parent query, operator-tree coordinates (step_id / node_id), and cost for a single fragment.

Sample call

"Which query does fragment f1d2c3b4 come from?"

Sample response

{
  "query_id": "01HXY8F3A4B5C6D7E8F9",
  "step_id": "1",
  "node_id": "2",
  "fragment_cost": 1.84
}

`query_list_for_job`

Returns every query a job ran on the current processing date, sorted by cost descending. first_token is the first whitespace-delimited token of the query text (useful for filtering by statement type).

Sample call

"List all the queries the analytics_daily.orders_rollup job ran today."

Sample response

[
  {"query_id": "01HXY8F3A4B5C6D7E8F9", "cost": 18.42, "first_token": "SELECT"},
  {"query_id": "01HXY8F3B7C8D9E0F1G2", "cost": 9.21, "first_token": "INSERT"},
  {"query_id": "01HXY8F3C0D1E2F3G4H5", "cost": null, "first_token": "MERGE"}
]

`query_summary_for_job`

Returns a per-job_tag breakdown for a job. A job_tag is the job's job_id joined by the &&& separator to the leading SQL keyword of each query (its first whitespace-delimited token, e.g. SELECT or INSERT), so each row rolls up the count and total cost for that statement type plus one sample query. Primary source is query_history; tags present only in related_jobs are appended.

Call once per job_id — it returns the complete result set.

Sample call

"Summarize today's runs of analytics_daily.orders_rollup."

Sample response

[
  {
    "job_tag": "analytics_daily.orders_rollup &&& SELECT",
    "day_count": 14,
    "day_cost": 142.5,
    "sample_query_id": "01HXY8F3A4B5C6D7E8F9",
    "sample_query": "SELECT order_date, region, SUM(amount) FROM analytics.orders_fact GROUP BY 1, 2",
    "default_database": "analytics_db"
  },
  {
    "job_tag": "analytics_daily.orders_rollup &&& INSERT",
    "day_count": 1,
    "day_cost": 4.20,
    "sample_query_id": "01HXY8F3D6E7F8G9H0I1",
    "sample_query": "INSERT INTO analytics.orders_daily_agg SELECT ...",
    "default_database": "analytics_db"
  }
]