# Dashboard Field Contract

Use this reference when selecting or interpreting Wetech Slow Query or TopSQL
evidence.

## Slow Query

The Provider Executor always requests a safe core projection and adds up to 12
ordered fields selected by the Evidence Agent for the current diagnostic
question. The following groups are selectable; they are not all required for
every request.

The exhaustive machine-readable selection contract is
`slow-query-handoff-fields.json` in this directory. Read that file before
emitting `handoffFields`; this prose groups the fields by diagnostic use but is
not a second field list.

| Evidence group | Selectable fields |
|---|---|
| Identity | `digest`, `connection_id`, `timestamp`, `query`, `instance`, `db` |
| Total latency | `query_time`, `parse_time`, `compile_time`, `rewrite_time`, `optimize_time` |
| Execution and wait | `cop_time`, `process_time`, `wait_time`, `backoff_time`, `backoff_types`, `lock_keys_time`, `exec_retry_time`, `write_sql_response_total` |
| Resource | `memory_max`, `disk_max`, `ru`, `time_queued_by_rc`, `resource_group` |
| Access and stats | `index_names`, `stats`, `warnings` |
| Scan and MVCC | `request_count`, `process_keys`, `total_keys`, RocksDB skipped/read counters |
| Cop detail | Cop process/wait average, P90, max, and addresses |
| Write/transaction | `write_keys`, `write_size`, `txn_retry`, resolve/local-latch time |

The command queries `/api/slow_query/available_fields` first. It requests only
the intersection with the current cluster schema and records unsupported fields
in `request.field_selection`.

At the batch boundary, an explicit projection is additive rather than
destructive: the Provider Executor retains identity, `query_time`,
`memory_max`, `disk_max`, execution/wait, scan, resource-control, and the active
order field. `memory-oom` defaults to `memory_max DESC`; other scenarios default
to `query_time DESC`. An explicit load-bearing order still wins.

`handoffFields` controls both additive provider selection and compact-row
priority. Always-preserved identity/time facts need not be repeated. Select
only fields that can prove or reject the current mechanism or its strongest
alternative; keep `cop_proc_max` with `cop_proc_addr` and `cop_wait_max` with
`cop_wait_addr` when localizing TiKV work.

The compact row reserves its fixed field budget for safe workload identity,
the derived execution interval and overlap, plan availability, and then the
ordered `handoffFields`. Generic core fields that were not selected remain in
the raw provider artifact but must not displace the current scenario's selected
facts from the compact handoff.

`timestamp` is the Slow Query log print/finish time. The Provider Executor
queries a bounded 15-minute finish-time lookahead, derives
`start_time=finish_time-query_time`, and filters the enlarged candidate set by
execution-interval overlap with the original incident window before applying
the requested result limit. Interpret `overlaps_incident_window=true` as time
alignment, not causality. When `execution_interval_status=unavailable`, keep the
row as unclassified timing evidence rather than inventing an onset.

Do not select `plan` by default: it is deprecated and may not contain a usable
plan. Do not select `binary_plan` for a broad list because it can be large. For
a narrow digest/time request, explicitly request `binary_plan` or fetch the
exact Dashboard Slow Query detail identified by digest, timestamp, and
connection ID.

Do not interpret zero values in the raw Go response for fields outside
`request.field_selection.requested_fields`. The compact preview removes those
unrequested defaults.

## TopSQL

Dashboard TopSQL summary has no `fields` parameter. Its response contract is
fixed by the installed Dashboard version and normally contains:

- SQL digest and normalized SQL text;
- total CPU, execution rate, and duration per execution;
- record/index scan rates;
- per-plan digest, plan text, timestamp series, and CPU series;
- network and logical-IO fields only when supported by that Dashboard version.

The command records the returned and missing recommended fields under
`request.field_selection`. Missing fields are unavailable, not zero.

TopSQL answers which SQL is hot and how CPU/scan rate is distributed. It does
not expose per-execution `process_keys` and `total_keys`, so use Slow Query for
MVCC scan amplification and exact latency decomposition.