| name | query-plan-snapshot-cli |
| description | Use QueryPlanSnapshotCli to capture and compare RDF4J query plans, then assess likely performance improvements/regressions from execution verification and semantic plan diffs. Trigger when users ask about optimizer impact, query-plan drift, join algorithm changes, or query performance regressions in testsuites/benchmark. |
query-plan-snapshot-cli
Use this skill to run reproducible query-plan captures and classify likely regression/improvement signals.
Fast workflow
- Capture baseline run (main/reference commit).
- Capture candidate run (changed commit) with same query selector +
--query-id.
- Produce semantic diff (
--compare-existing).
- Interpret runtime + diff together.
Commands
Use wrapper (enforces pre-install and optional logging):
- Baseline:
./.codex/skills/query-plan-snapshot-cli/scripts/run_query_plan_snapshot.sh --log /tmp/qps-baseline.log -- --store memory --theme MEDICAL_RECORDS --query-index 0 --query-id med-q0
- Candidate:
./.codex/skills/query-plan-snapshot-cli/scripts/run_query_plan_snapshot.sh --log /tmp/qps-candidate.log -- --store memory --theme MEDICAL_RECORDS --query-index 0 --query-id med-q0 --compare-latest --diff-mode structure+estimates
- Compare existing snapshots explicitly:
mvn -o -Dmaven.repo.local=.m2_repo -pl testsuites/benchmark -DskipTests exec:java@query-plan-snapshot -Dexec.args="--compare-existing --query-id med-q0 --compare-indices 1,0 --no-interactive --diff-mode structure+estimates" | tee /tmp/qps-compare.log
- Summarize improvement/regression signal:
python3 ./.codex/skills/query-plan-snapshot-cli/scripts/interpret_query_plan_regression.py --baseline-log /tmp/qps-baseline.log --candidate-log /tmp/qps-candidate.log --comparison-log /tmp/qps-compare.log
Interpretation rule-of-thumb
averageMillis down with stable resultCount: improvement signal.averageMillis up with stable resultCount: regression signal.actualResultSizes=diff: semantic/data-shape risk; perf conclusion low confidence.joinAlgorithms=diff or structure=diff: optimizer behavior changed; correlate with runtime delta.estimates=diff only: model/statistics shift; validate with repeated runs.
For more detailed reading patterns and triage prompts, use references/workflow.md.
