# Clinic Slow Query Total Keys Ordering

<!-- auto-oncall-optimization-record
{
  "schemaVersion": "auto-oncall-optimization-record-v1",
  "optimizationId": "clinic-slow-query-total-keys-2026-08-06",
  "problems": [
    {
      "problemId": "clinic-slow-query-total-keys-order-crashes-helper",
      "summary": "A Clinic Slow Query refinement ordered by total_keys, but the deterministic helper omitted that supported mapping and threw while reading undefined.ngm before issuing the NGM request.",
      "status": "optimized_verified",
      "issueKeys": ["TCID-12983"],
      "sourceRefs": [
        "https://tidb.atlassian.net/browse/TCID-12983#problem:clinic-slow-query-total-keys-helper-crash"
      ],
      "signalTextIncludesAny": [
        "cannot read properties of undefined reading ngm",
        "slow query total_keys refinement failed before provider execution",
        "clinic slow query ordering mapping omitted total_keys"
      ],
      "observedThrough": "2026-08-06",
      "effectiveAt": "2026-08-06T14:00:22Z",
      "verifiedAt": "2026-08-06T14:14:09Z",
      "attemptedAction": "Add total_keys to the typed Slow Query order contract for both NGM and Data Proxy and reject any unsupported order during plan parsing before provider execution.",
      "evidenceUrl": "https://tidb.atlassian.net/browse/TCID-12983"
    }
  ]
}
-->

- Optimization ID: `clinic-slow-query-total-keys-2026-08-06`
- Owner: auto-oncall-services
- Source case: `TCID-12983`, replay
  `731252a1-3ce0-49b7-91bb-b1fc79cbf53e`
- Implementation status: deployed to staging in image
  `cbd86cbad4cba3b1cc2bc43dd207b88178c68a8c`
- Effective status: `optimized_verified`

## Bounded problem

The adaptive query-execution scenario used the valid workload-refinement goal
of ordering Slow Query rows by processed keys. It selected `total_keys`, but
the helper's order map contained only time, memory, process, wait, and backoff
fields. The helper evaluated `.ngm` on an undefined map entry and never sent the
NGM request.

## Implementation

- Admit `total_keys` in the typed Slow Query plan contract.
- Map it to `total_keys` for both NGM and Data Proxy SQL.
- Validate every supplied Slow Query ordering while parsing the plan so an
  unknown field returns `clinic_slow_query_order_invalid` before any provider
  call instead of a JavaScript property error.

## Verification status

Local contract tests proved that `orderBy=total_keys` reaches NGM and that an
unknown ordering makes zero provider calls. The full suite passed 679/679.

Post-deployment write replay `28d93f40-89bf-4528-93f6-23e93c22d904` / DB run
`120050` completed its selected Slow Query operations with 20 rows in each
scenario and did not reproduce `undefined.ngm`. Because that stochastic replay
did not naturally select a `total_keys` refinement, a case-specific runtime
probe then invoked the deployed deterministic helper with the exact
`TCID-12983` target and historical window. `orderBy=total_keys` reached NGM and
completed in 5.601 seconds with 10 returned rows. Existing Jira internal
comment `23342385` was read back with `public=false`.

## Unresolved gaps

This change does not guarantee matching historical Slow Query rows and does not
establish workload identity or causality by itself.

## Next validation action

Monitor later adaptive Clinic cases for recurrence of `undefined.ngm` or an
unsupported ordering that is not rejected as `clinic_slow_query_order_invalid`.