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 /singleorigin:similar_query_search prompt (see Built-in Prompts), which handles the right input format — the underlying tool wants one indented operator-tree fragment as sql_text, not raw SQL, and raw SQL chunks score worse. Optional start_time / end_time (ISO-8601) bound the search by processing time, and exclude_job_ids drops specific jobs. Returns an empty list when no stored fragment clears the calibrated noise floor.

Note: search_similar_queries is only present when the deployment has embedding search enabled (controlled by the MCP_EMBEDDING_MODEL_URI setting). If /mcp doesn't list this tool, your deployment doesn't have it turned on. The fragment index is built from query-plan subtree text, so pass a single operator-tree fragment per call.

Sample call

"Find historical queries similar to 01HXY8F3A4B5." (typically issued via the /singleorigin: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"
  }
]