Query Explain
See the query plan before execution — which index will be used, or whether a full scan will happen.
What you'll learn
- ✓type: explain with filter — no records returned, just the plan
- ✓strategy: index_scan vs full_scan
- ✓Explains which index name will be used
- ✓Use before building indexes to identify which queries need them
- ✓Use after building to confirm strategy changed
Run explain on 5 different filter combos. Identify which need indexing. Build those indexes. Re-run explain.
Interactive Walkthrough
What you'll learn
Use explain to see the query plan before execution — which index will be used, or whether a full scan will happen.
Explain query shape
{
"type": "explain",
"filter": { ... }
}Example — check if an index will be used
curl -s -X POST http://localhost:7475/v1/agents/users/query \
-H "Content-Type: application/json" \
-H "Authorization: Bearer spx_root_YOUR_ROOT_KEY" \
-d '{
"type": "explain",
"filter": {"field": "plan", "op": "eq", "value": "pro"}
}' | python3 -m json.toolResponse with index:
`json
{
"explain": {
"strategy": "index_scan",
"index": "idx_plan",
"hint": "Single-field index on 'plan' — expected O(k) where k = matching records"
}
}
`
Response without index (full scan):
`json
{
"explain": {
"strategy": "full_scan",
"index": null,
"hint": "No index found for field 'plan' — full strand scan"
}
}
`
Use explain before building an index
Before creating an index, run explain on your most common queries. If they all show full_scan, build an index for the most selective filter field.
Challenge
Run explain on 5 different filter combinations against your users agent. Identify which ones benefit from indexing. Create those indexes and re-run explain to confirm the strategy changes.
---