query-plan-snapshot-cli
/query-plan-snapshot-cli
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.
- Author
- eclipse-rdf4j ↗
- Repository
- rdf4j ↗
- Licence
- BSD-3-Clause
- Last repository change
- 27.10.2026
Assessment and security
- Files in this package
- 4
- Scripts
- 2
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.
BSD-3-Clause, otwarta.
- 2 scripts in this package. Review them before installing, as Claude may execute them.
Scripts: scripts/interpret_query_plan_regression.py, scripts/run_query_plan_snapshot.sh
What it does and when to use it
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.
Original author 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.
How it works
- Fast workflow
- History triage
- Fast regression test loop (persistent LMDB theme stores)
- Snapshot diff workflow
- Commands
- Interpretation rule-of-thumb
SKILL.md preview
--- 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, triage historical theme-query benchmark results, and classify likely regression/improvement signals. ## Fast workflow 1. Capture raw benchmark output into a normalized result file when needed. 2. Analyze the newest dated run against historical results. 3. Drill into the fastest known runs for a specific theme/query. 4. If needed, capture baseline/candidate plan snapshots and diff them semantically. ## History triage Result files live in: - `core/sail/lmdb/src/test/java/org/eclipse/rdf4j/sail/lmdb/benchmark/theme-query-benchmark-results` Normalize raw JMH output into a new result file: - `pbpaste | scripts/theme-query-benchmark-results.sh capture` - `scripts/theme-query-benchmark-results.sh capture raw-jmh.txt` Analyze only the queries that are more than 20% slower than history: - `core/sail/lmdb/src/test/java/org/eclipse/rdf4j/sail/lmdb/benchmark/theme-query-benchmark-results/analyze-theme-query-history.sh` Sort regressions from biggest to smallest: - `core/sail/lmdb/src/test/java/org/eclipse/rdf4j/sail/lmdb/benchmark/theme-query-benchmark-results/analyze-theme-query-history.sh --sort-regressions` Only print the top N regressions: - `core/sail/lmdb/src/test/java/org/eclipse/rdf4j/sail/lmdb/benchmark/theme-query-benchmark-results/analyze-theme-query-history.sh --top 10` Analyze every latest query, including current-run wins over previous best: - `core/sail/lmdb/src/test/java/org/eclipse/rdf4j/sail/lmdb/benchmark/theme-query-benchmark-results/analyze-theme-query-history.sh --all` Drill into the three fastest known runs for one theme/query and print optimized plan/query when present: - `core/sail/lmdb/src/test/java/org/eclipse/rdf4j/sail/lmdb/benchmark/theme-query-benchmark-results/analyze-theme-query-history.sh --theme PHARMA --query-index 10` Interpretation: - Default mode: newest dated file only for the “latest” baseline; compares against all other `results-*.md`, including `results-develop.md` and `results-main-branch.md`, but prints only queries where latest is more than 20% slower than historical best. - `--sort-regressions`: flat regression list, biggest slowdown first. - `--top N`: top N regressions only; implies regression sorting. - `--all`: prints every latest query; if latest is a new best it prints how much faster it is than the previous best. - Query detail mode: top three runs sorted by score ascending; ties prefer richer files with plan/query content. - `plan no | query yes`: optimized query rendered, no physical plan block in that result file. - `plan no | query no`: summary-only run or no per-query capture in that file. Use this path when the goal is optimizer-loop work: find the fastest known plan/query for a theme/query, then compare new runs back to that history before touching production logic. ## Fast regression test loop (persistent LMDB theme stores) Theme regression/snapshot tests in `core/sail/lmdb` now support reusing a prepared LMDB store across runs. - Enable persistent reuse: - `-Drdf4j.lmdb.themeRegression.persistentStore.enabled=true` - Optional custom root directory: - `-Drdf4j.lmdb.themeRegression.persistentStore.root=persistent-lmdb-theme-store` - Default root directory: - `persistent-lmdb-theme-store` Behavior: - If the store has expected `triples/data.mdb` and `values/data.mdb` sizes (from `expected-db-file-sizes.properties`), tests reuse it and skip rebuild/ingest. - If sizes mismatch or the marker file is missing/invalid, tests rebuild the store, then refresh the expected-size file. Example focused run: - `mvn -o -Dmaven.repo.local=.m2_repo -pl core/sail/lmdb -Dtest=LmdbThemeQueryRegressionTest#socialMediaFiveCycleInterleavesValuesWithFollowsEdges -Drdf4j.lmdb.themeRegression.persistentStore.enabled=true test` ## Snapshot diff workflow Use this when you need semantic plan diffs between two controlled captures of the same query. 1. Capture baseline run (main/reference commit). 2. Capture candidate run (changed commit) with same query selector + `--query-id`. 3. Produce semantic diff (`--compare-existing`). 4. 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`.
Files in this package (4)
- SKILL.md 6 KB
- references/workflow.md 3 KB
- scripts/interpret_query_plan_regression.py 5 KB
- scripts/run_query_plan_snapshot.sh 2 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · eclipse-rdf4j/rdf4j | 100 | BSD-3-Clause |
| eclipse-rdf4j/rdf4j | 100 | BSD-3-Clause |
Database snapshot: 13.11.2026 · package version 69046b0b6364 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100query-optimizer
Optimize SQL queries for performance with indexing strategies, query rewriting, and execution plan analysis. Use when queries are slow, optimizing database performance, or analyzing query execution. - 100query-optimization
Diagnose and optimize existing slow SQL queries using execution plans, indexing strategies, query rewriting, and ORM tuning. Use when the user provides a query, performance symptom, or EXPLAIN plan; use sql-query-generation when creating a new query from requirements. - 100analyzing-query-performance
Execute use when you need to work with query optimization. This skill provides query performance analysis with comprehensive guidance and automation. Trigger with phrases like "optimize queries", "analyze performance", or "improve query speed". - 100analyzing-query-performance
Execute use when you need to work with query optimization. This skill provides query performance analysis with comprehensive guidance and automation. Trigger with phrases like "optimize queries", "analyze performance", or "improve query speed". - 100query-optimizer
Analyzes query performance on a Fabric Data Warehouse: captures the estimated execution plan, inspects query insights history, identifies costly operators and missing or stale statistics, inspects data-clustering columns, and proposes or applies optimizations. Use when the user… - 100performance-review
Review code and query plans for performance problems such as N+1 queries, missing or unused indexes, unbounded queries, unnecessary React re-renders, large bundles, blocking I/O and memory leaks, then rank findings by measured or likely impact. Use when the user says an…