Przejdź do treści
Biblioteka skilli
Dane i analityka · Przegląd i audyt

query-plan-snapshot-cli

/query-plan-snapshot-cli

Porównuje plany zapytań RDF4J z wykonaniem i wskazuje prawdopodobny wzrost lub spadek wydajności po zmianach.

Repozytorium
rdf4j ↗
Licencja
BSD-3-Clause
Ostatnia zmiana repozytorium
27.10.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
4
Skrypty
2
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 27.10.2026, bez odwołań do wycofanych modeli i API.

Licencja

BSD-3-Clause, otwarta.

Co sprawdzić przed instalacją
  • 2 skrypty w paczce. Przejrzyj je przed instalacją, bo Claude może je uruchomić.

Skrypty: scripts/interpret_query_plan_regression.py, scripts/run_query_plan_snapshot.sh

Co robi i kiedy

Porównuje plany zapytań RDF4J z wykonaniem i wskazuje prawdopodobny wzrost lub spadek wydajności po zmianach.

Oryginalny opis (EN)

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.

Jak działa

  1. Fast workflow
  2. History triage
  3. Fast regression test loop (persistent LMDB theme stores)
  4. Snapshot diff workflow
  5. Commands
  6. Interpretation rule-of-thumb
Sekcje z nagłówków SKILL.md, w oryginale · 107 linii, 593 słów
Podgląd SKILL.md
---
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`.
Pliki w paczce (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

Wersje

RepozytoriumWynikLicencja
Ta strona · eclipse-rdf4j/rdf4j100BSD-3-Clause
eclipse-rdf4j/rdf4j100BSD-3-Clause

Migawka bazy z 13.11.2026 · wersja paczki 69046b0b6364 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100query-optimizer
    Optymalizuje zapytania SQL: indeksy, przepisywanie zapytań i analizę planu wykonania, gdy zapytania są wolne.
  • 100query-optimization
    Diagnozuje i optymalizuje istniejące wolne zapytania SQL przez plany wykonania, indeksy, przepisywanie zapytań i strojenie ORM.
  • 100analyzing-query-performance
    Pomaga optymalizować zapytania bazodanowe przez analizę wydajności zapytań z konkretnymi wskazówkami i automatyzacją.
  • 100analyzing-query-performance
    Pomaga optymalizować zapytania bazodanowe przez analizę wydajności zapytań z konkretnymi wskazówkami i automatyzacją.
  • 100query-optimizer
    Analizuje wydajność zapytań w Fabric Data Warehouse: plan wykonania, statystyki, klastrowanie i proponuje lub stosuje poprawki.
  • 100performance-review
    Sprawdza kod i plany zapytań pod kątem problemów wydajności, takich jak N+1, brakujące indeksy czy wycieki pamięci, i sortuje według wpływu.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.