# Clinic Default TopSQL Query

<!-- auto-oncall-optimization-record
{
  "schemaVersion": "auto-oncall-optimization-record-v1",
  "optimizationId": "clinic-default-topsql-query-2026-08-06",
  "problems": [
    {
      "problemId": "clinic-topsql-http-400-hides-query-and-capability-boundary",
      "summary": "The Clinic evidence child had to author every TopSQL SQL statement, while the helper collapsed both invalid SQL and an unconfigured TopSQL data source into clinic_http_400, causing ineffective rewritten queries instead of either a canonical default or an exact capability gap.",
      "status": "optimized_verified",
      "issueKeys": ["TCID-12965", "TCID-12983"],
      "sourceRefs": [
        "https://tidb.atlassian.net/browse/TCID-12965#problem:clinic-topsql-default-query-http-400",
        "https://tidb.atlassian.net/browse/TCID-12983#problem:clinic-topsql-default-query-http-400"
      ],
      "signalTextIncludesAny": [
        "clinic topsql returned clinic_http_400",
        "default topsql query used digest or cpu_ms instead of canonical columns",
        "topsql workload evidence was unavailable because the generated sql was rejected",
        "topsql data source not configured was retried as rewritten sql"
      ],
      "observedThrough": "2026-08-06",
      "effectiveAt": "2026-08-06T14:00:22Z",
      "verifiedAt": "2026-08-06T14:14:09Z",
      "attemptedAction": "Allow a TopSQL plan item to omit custom SQL and have the deterministic Clinic batch helper generate a canonical incident-window CPU aggregate, while mapping the provider's unconfigured-data-source response to clinic_topsql_datasource_not_configured so the scenario stops rewriting SQL for a non-repairable capability gap.",
      "evidenceUrl": "https://tidb.atlassian.net/browse/TCID-12983"
    }
  ]
}
-->

- Optimization ID: `clinic-default-topsql-query-2026-08-06`
- Owner: auto-oncall-services
- Source cases: `TCID-12965`, `TCID-12983`
- Implementation status: deployed to staging in image
  `cbd86cbad4cba3b1cc2bc43dd207b88178c68a8c`
- Effective status: `optimized_verified`

## Bounded problem

The Clinic evidence plan represented TopSQL as generic SQL and required the
evidence child to write the full statement. Both source-case replays preserved
other Clinic evidence but their selected TopSQL query returned only
`clinic_http_400`. A direct read-only probe using canonical columns and the
exact `TCID-12983` window passed partition validation, then established the
actual provider response: its Essential cluster has no configured TopSQL data
source. Rewriting SQL cannot make that source available.

## Implementation

- Keep generic SQL available for a custom load-bearing TopSQL dimension.
- When `queryId=topsql`, `kind=sql`, and `sql` is omitted, generate the default
  TopSQL CPU aggregate inside the deterministic helper.
- Bind the generated query to every intersecting `YYYY-MM-DD` partition and the
  exact canonical timestamp window, group by SQL digest, and default to Top 10.
- Translate the exact provider response to
  `clinic_topsql_datasource_not_configured`; direct the scenario not to retry
  that capability limitation with another SQL spelling.

## Verification status

Local typecheck, focused Clinic/diagnostic/optimization tests, and the full
suite passed; the full result was 679 tests with zero failures. A pre-deployment
read-only probe against the exact `TCID-12983` target and historical window
proved the canonical default passes SQL/partition validation and reaches the
provider, which reports that this cluster has no configured TopSQL data source.

Post-deployment write replay `28d93f40-89bf-4528-93f6-23e93c22d904` / DB run
`120050` used the default helper query in both memory and query-execution
scenarios. Each returned `clinic_topsql_datasource_not_configured` once. No
later TopSQL artifact exists, proving the parent did not rewrite and retry SQL
for the exact capability limitation. Existing Jira internal comment `23342385`
was updated in place and read back with `public=false`.

## Unresolved gaps

- `TCID-12983` cannot return TopSQL rows until the upstream data source is
  configured; this change reports that boundary instead of inventing a fallback.
- A successful empty TopSQL response may reflect retention or disabled export
  and must not be treated as proof that no workload existed.

## Next validation action

Monitor a future cluster with configured TopSQL export to verify positive rows
through the same default path. Treat recurrence of generic `clinic_http_400` or
a rewritten retry after `clinic_topsql_datasource_not_configured` as regression.