Query inspection tools

Six tools for investigating any single query or job/run: raw SQL, a compact execution profile, parsed query fragments, and per-job aggregates. Your agent typically chains them: fetch the query → look at the profile → find the fragments → search for similar queries.

All sample responses below use synthetic data.

query_detail

Returns the SQL, cost, signature, and default database for a query ID.

Sample call

"What does query 01HXY8F3A4B5 look like?"

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"
}

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. Same format used to generate similarity-search embeddings.

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 the per-job-tag breakdown for a job. A job_tag is the job's job_id joined with the leading SQL keyword (e.g. SELECT, INSERT), separated by &&&. Each row has the count and total cost for that tag plus a sample query.

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"
  }
]