Work with recommendations

Ask your agent what to fix first, read a recommendation, record what you decided, and check whether it saved money.

Questions you can ask your agent:

  • "What are the top Single Origin recommendations right now?"
  • "Walk me through recommendation 9c2b1f7e. Is it worth doing?"
  • "We shipped the orders_fact fix on May 1. Did it save anything?"

Single Origin analyses your query history every day and stores what it finds as recommendations: query rewrites, cluster keys, materialized views, resource tuning and more. The tools below list them, read one in full, record a person's decision, and read the measured saving.

All sample responses use synthetic data and are shortened.

Statuses

StatusMeaning
ACTIVEOpen: nobody has picked it up.
IN_REVIEWSomeone is looking at it.
APPLIEDShipped as proposed.
APPLIED_VARIANTShipped as a different change that serves the same end.
PARTIALLY_APPLIEDPart of it shipped.
APPLIED_UNCONFIRMEDSingle Origin saw the change and the cost fell, and is waiting for a person to confirm it was this recommendation. Set by Single Origin, not by you.
IGNOREDSet aside by a person.
INVALIDATEDFound not to apply.
PENDING_REFRESHWaiting to be re-analysed.
STALENobody moved it for a month. Hidden from the default list but recoverable. Set by Single Origin.
ARCHIVEDStale for another month. Set by Single Origin.

Types

SINGLE_QUERY (one query or job to fix), SIMILAR_QUERY_GROUP (a group of queries with the same shape, fixed together), CLUSTER_KEY_RECOMMENDATION, MV_REWRITE_RECOMMENDATION and RESOURCE_TUNING.

list_recommendations

Lists recommendations, highest estimated daily savings first, 10 per page.

When to use: "What should we work on?", a weekly review, or any time you need recommendation ids.

Parameters
ParameterTypeRequiredDefaultMeaning
pageintegerNo0Zero-based page number.
statuseslist of stringsNo["ACTIVE", "IN_REVIEW", "APPLIED_UNCONFIRMED"]Statuses to include, case-insensitive. Any status from the table above. An unknown name or an empty list is an error.
typeslist of stringsNoall typesRecommendation types to include.

Returns each recommendation's id, title, type, status, processing_time, estimated_daily_savings and query_signatures, at its latest version. Deleted recommendations are left out. STALE and ARCHIVED are returned only when you name them.

APPLIED_UNCONFIRMED sorts first: it is a question for a person, not work to do. Ask whether the change was theirs, then set APPLIED (or APPLIED_VARIANT / PARTIALLY_APPLIED) or INVALIDATED with update_recommendation.

Results are valid for one hour. After that, call the tool again rather than reusing an old list.

Example

"Show me the top open recommendations."

[
  {
    "id": "9c2b1f7e-4a3d-4e10-9f02-1ab2c3d4e5f6",
    "title": "Read only the last 3 days of analytics.orders_fact",
    "type": "SINGLE_QUERY",
    "status": "ACTIVE",
    "processing_time": "2026-05-08T00:00:00Z",
    "estimated_daily_savings": 48.2,
    "query_signatures": "[\"nightly_revenue &&& load_orders\"]"
  }
]

get_recommendation

Returns one recommendation in full.

When to use: before acting on a recommendation, or to read what was measured for an APPLIED_UNCONFIRMED one.

Parameters
ParameterTypeRequiredDefaultMeaning
recommendation_idstring (UUID)YesThe recommendation's id.

Returns processing_time, type, id, title, background, status, status_change_reason, is_dismissed, target_inefficiency, target_inefficiency_query_snippet, recommendation, recommendation_query_snippet, estimated_savings_summary, estimated_daily_savings and query_signatures. A deleted recommendation returns an error.

For an APPLIED_UNCONFIRMED recommendation it also returns realized_daily_saving (on the same scale as the estimate) and saving_measured_on. Both are null for other statuses. page is the recommendation's web page, when the server knows the web address.

Example

"Walk me through recommendation 9c2b1f7e."

{
  "id": "9c2b1f7e-4a3d-4e10-9f02-1ab2c3d4e5f6",
  "type": "SINGLE_QUERY",
  "status": "ACTIVE",
  "title": "Read only the last 3 days of analytics.orders_fact",
  "target_inefficiency": "Each run rebuilds the table from all of orders_fact ...",
  "recommendation": "Delete and reinsert only the last 3 days ...",
  "estimated_daily_savings": 48.2,
  "realized_daily_saving": null
}

update_recommendation

Sets a recommendation's status and the reason for it. Write tool.

When to use: after a person decides what to do with a recommendation: picked up, shipped, rejected or set aside.

Parameters
ParameterTypeRequiredDefaultMeaning
recommendation_idstring (UUID)YesThe recommendation's id.
processing_timestring (ISO-8601)YesMust match the recommendation's current processing_time. Get it from get_recommendation.
statusstringNo, but a call without it is an errornoneOne of ACTIVE, PENDING_REFRESH, INVALIDATED, IGNORED, IN_REVIEW, APPLIED, APPLIED_VARIANT, PARTIALLY_APPLIED.
status_change_reasonstringRequired for INVALIDATED and IGNOREDnoneWhy it moved, in the person's own words. Needs status.

Only the status and reason change. A recommendation's content and savings can't be changed. APPLIED_UNCONFIRMED, STALE and ARCHIVED are set by Single Origin and can't be set here.

The reason travels with the recommendation: when the workload is analysed again, the reason a person gave for turning down the last proposal is carried into the next one. A status set without a reason records no reason; it doesn't keep the previous one.

APPLIED_VARIANT and PARTIALLY_APPLIED count as applied: the recommendation is closed, and a new proposal for the workload gets a new id. Setting any status also shows a recommendation the pipeline had dismissed (is_dismissed: true). Marking a recommendation applied is refused when it has nothing to apply; the error says why.

Example

"Ignore 9c2b1f7e. The table is being retired next month."

{"updated": true, "recommendation_id": "9c2b1f7e-4a3d-4e10-9f02-1ab2c3d4e5f6"}

recommendation_outcome

Returns the stored measurement of an applied recommendation: the same one the web app's Did this work? tab shows.

When to use: "Did recommendation X work?" Read this before judging a saving yourself.

Parameters
ParameterTypeRequiredDefaultMeaning
recommendation_idstring (UUID)YesThe recommendation's id.

Returns:

  • recommendation: id, title, status, claimed_daily_savings.
  • measurement: the latest one, or null when none is stored yet. It has verdict and its meaning (SEEN, NONE, WORSE, WAITING, FELL_BEFORE, STOPPED, STOPPED_OTHER, RESHAPED, NO_COST_DATA, UNMEASURABLE, CONFOUNDED); change_date and change_source (DETECTED, MARKED, CONFIRMED or SEEN); method (JOB_COST or TABLE_READS); before, after, expected_after, saving and saving_margin, all per day; the control; days used on each side; caveats; and unmeasured_reason / unmeasured_note when nothing is measured yet.
  • checkpoints: the measurements frozen at 7, 30 and 90 days, those reached so far.
  • stop_cause, when a person said why the covered jobs stopped.
  • no_estimate, when there is no estimated saving.
  • disagreement, when a person reported a saving that is 2 times or more away from the estimate, with the checks that may explain the gap.
  • page: the recommendation's web page, when the server knows the web address.
  • ask_user and end_state: questions to put to the person (with our_reading as the suggested answer), and where the session can stop (fixed_and_verified, cant_tell_yet with known_on, or nothing_to_fix).

Say a saving with its margin ("saved 45.10 ± 4.30 a day"). WAITING and CONFOUNDED are not savings yet. With no measurement, call job_run_comparison with this recommendation_id to compare the job's runs instead. A person confirms what shipped on the web app's Did this work? tab; see Did this work?.

Example

"Did recommendation 9c2b1f7e save anything?"

{
  "recommendation": {"id": "9c2b1f7e-...", "status": "APPLIED", "claimed_daily_savings": 48.2},
  "measurement": {
    "verdict": "SEEN",
    "change_date": "2026-05-01",
    "change_source": "CONFIRMED",
    "method": "JOB_COST",
    "before": 61.0,
    "after": 14.2,
    "saving": 45.1,
    "saving_margin": 4.3
  },
  "checkpoints": [{"checkpoint_days": 7, "verdict": "SEEN"}],
  "end_state": {"state": "fixed_and_verified"}
}

Related


Did this page help you?