Similar-query cluster tools

Single Origin groups query fragments by structural similarity. A group holds fragments that come from queries sharing the same shape (same tables, joins, aggregates). Fixing the shape of a group's anchor query usually improves every member. These four tools let your agent list groups, inspect members, and search for similar fragments from a new query.

All sample responses below use synthetic data.

`list_similar_query_groups`

Lists groups ordered by total fragment cost. Returns 5 per page.

Sample call

"Which similar-query groups are costing us the most?"

Sample response

[
  {
    "group_id": "a42b1c3d-4e5f-6789-abcd-1234567890ab",
    "group_rank": 1,
    "fragment_count": 37,
    "unique_signatures": 8,
    "total_fragment_cost": 5200.18,
    "distinct_signatures": [
      "analytics_daily &&& orders_rollup||a1b2",
      "adhoc &&& c3d4",
      "looker &&& e5f6"
    ]
  },
  {
    "group_id": "b91c2d3e-4f5a-6789-bcde-2345678901bc",
    "group_rank": 2,
    "fragment_count": 12,
    "unique_signatures": 3,
    "total_fragment_cost": 2100.42,
    "distinct_signatures": [
      "events_etl &&& f7e8",
      "tenant_dashboard &&& g9h0"
    ]
  }
]

`list_similar_query_group_items`

Lists every query/fragment pair in a group, ordered by fragment cost.

Sample call

"Show me every query in group a42b1c3d."

Sample response

[
  {
    "query_id": "01HXY8F3A4B5C6D7E8F9",
    "fragment_id": "f1d2c3b4-1111-2222-3333-444455556666",
    "query_signature": "analytics_daily &&& orders_rollup||a1b2",
    "fragment_cost": 18.42
  },
  {
    "query_id": "01HXYA02B1C2D3E4F5G6",
    "fragment_id": "f2e3d4c5-2222-3333-4444-555566667777",
    "query_signature": "adhoc &&& c3d4",
    "fragment_cost": 14.10
  }
]

`similar_query_group_summary`

Returns a per-signature breakdown of a group — useful for seeing which signatures contribute most cost before drilling into queries.

Sample call

"Break group a42b1c3d down by signature."

Sample response

[
  {
    "query_signature": "analytics_daily &&& orders_rollup||a1b2",
    "fragment_count": 14,
    "run_count": 14,
    "total_fragment_cost": 1840.55
  },
  {
    "query_signature": "adhoc &&& c3d4",
    "fragment_count": 9,
    "run_count": 9,
    "total_fragment_cost": 1210.30
  }
]

`search_similar_queries`

Embedding-based nearest-neighbor search over historical query fragments. Best invoked through the /similar_query_search prompt (see Built-in Prompts), which handles the right input format — the underlying tool wants an indented operator-tree text, not raw SQL, and raw SQL chunks score worse. Returns an empty list when no stored fragment clears the calibrated noise floor.

Sample call

"Find historical queries similar to 01HXY8F3A4B5." (typically issued via the /similar_query_search prompt, which fetches the fragment text first.)

Sample response

[
  {
    "query_id": "01HXYA02B1C2D3E4F5G6",
    "fragment_id": "f2e3d4c5-2222-3333-4444-555566667777",
    "query_signature": "adhoc &&& c3d4",
    "similarity_score": 0.94,
    "processing_time": "2026-05-08T00:00:00Z",
    "fragment_plan_text_preview": "Aggregate attrs={\"functions\": \"sum(amount)\"}\n  Filter attrs={\"filter_condition\": \"order_date >= ?\"}\n    TableScan attrs={\"table_name\": \"analytics.orders_fact\"}\n"
  },
  {
    "query_id": "01HXYB21F3G4H5I6J7K8",
    "fragment_id": "f3a4b5c6-3333-4444-5555-666677778888",
    "query_signature": "looker &&& e5f6",
    "similarity_score": 0.89,
    "processing_time": "2026-05-08T00:00:00Z",
    "fragment_plan_text_preview": "Aggregate attrs={\"functions\": \"sum(amount), count(*)\"}\n  TableScan attrs={\"table_name\": \"analytics.orders_fact\"}\n"
  }
]