# Queries

This is part of the root `AGENTS.md`, loaded when work reaches `crates/knotless-serve/`.

A query of the index (`crates/knotless-serve/src/index.rs`) is planned
as the tests run it, against tables said to be prod's size
(`crates/knotless-serve/src/plans.rs`), and `test` fails on any that
scans a table that grows with the network: `forge`, `check_run`,
`comment` and the rest of `GROWING`, or sorts many of its rows (a range
leading its index, or what a search finds for each row of a scan, as a
repository's pushes for every repository). Tests on empty tables pass a query
that takes seconds on prod, so this is what holds them. Its log names
the query and its plan. Give it an index, or a query that uses the one
there: an expression index needs the expression as written, and a
column compared to it marked `+` (`json_extract(c.value, '$.pull') =
+p.uri`), as the column's affinity otherwise keeps the index unused.
A scan meant to be, of a few rows an operator reads now and then, says
so in its SQL with why, `-- scans: forge, as only the operator asks`,
where review sees it; a sort meant to be, `-- sorts: forge, …`. On prod,
a statement slower than 100 ms logs `sql`, with the request's trace. To see the plans while fixing one, run its tests
with `KNOTLESS_PLANS=<dir>` and `node harness/plans.mjs <dir>`.