docs(gfql): publish final performance results and simplify engine guides

[lmeyerov]

Status 2026-09-15. Rebased onto current master 65c359b (head a489e9a). The vendored-number freshness contract is intentionally RED: the vendored SNB runs are from f7a7253, now 20 compute commits behind master, past the 12-commit policy. The fix is a single re-vendor once the open performance PRs (#2084, #2086, #2087) land, since those change the published numbers again; re-vendoring now would be thrown away and would churn the measured prose twice. Not ready to merge — per the landing rule this goes last, after the benchmarks win.

GFQL documentation now gives readers a short start path, separate performance and language-reference hubs, and an engine guide tied to measured results. Existing page URLs are preserved. The performance hub leads with the speedup case study and separates examples and architecture from benchmark tables and methodology.

The benchmark pages use verified publication cells for values, ratios, query tallies, and generated charts. This refresh includes GraphBench Q1–Q9 at 20k/100k from PyGraphistry d20c6ae1af73e64b05aa4b24459dfd3ba247edf9 and SNB SF0.1/SF1 from f7a7253bc95d9cc0663bd130a53a03f2f355cbcd. The source revisions remain distinct. The final artifact is byte-identical to merged pyg-bench #267; #268 records and enforces matching CPU placement. Historical database measurements keep their original dates and methods.

The engine guide explains input-based auto selection, frame conversion, unsupported-query behavior, and when Polars-GPU still executes CPU operations. Indexed message-content and creator lookups lead the measured four-engine SNB comparisons at both scales. The full tables retain every eligible result. GraphBench 20k q8 is explicitly identified as CPU-only under Polars-GPU. Instrumented GPU diagnostics are excluded from published timings.

The editorial pass addresses the recorded review items: shorter prose, defined lookup terms, consolidated engine decisions and memory guidance, simpler comparison tables, and one provenance section per page. The Neo4j/GDS and GraphFrames case studies retain their measured scope and limits. Benchmark contracts enforce source freshness, correct references, derived tallies, and chart synchronization.

Validation on the final data and prose:

• Benchmark contracts: 37 passed, one intentional skip; source freshness passes without a new waiver.
• Relevant documentation examples: two passed, two skipped because those pages have no runnable blocks; 32 other pages were outside this check.
• RST checks passed. A clean full HTML build passed with RTD content-copy steps and the pinned ipykernel version. Repository-wide warnings remain, including a Cypher lexer warning for $ parameters in the case study; none point to the four final edited pages.
• All 90 internal article links on those pages resolve. Engine/performance layouts were inspected in Chrome; benchmark tables and all five case-study SVGs resolve.
• Upstream publication: 1,414 tests passed and 131 skipped locally and in PR/main CI; strict publication regression checks pass with no exceptions. Current-master GPU integration passed 926 tests with no skips, and the fresh 30-point automatic sentinel gate passed unchanged bounds.

Review previews:

• Performance hub: reader paths and case-study lead.
• Engine guide: engine selection, comparisons, CPU/GPU behavior.
• Performance tables: final GraphBench/SNB values and measurement methods.
• Overview: positioning and measured results.
• Neo4j/GDS case study and GraphFrames case study: charts, examples, and scope.

Performance changes and private benchmark/TCK companions are merged. This public documentation PR is the remaining owner review and merge step. Final head 048b454673dcf673ba23784d938f9ab73845f02b passed GitHub CI with 57 successful jobs and 11 conditional skips, plus CodeQL. Read the Docs build 34554961 passed on that exact head. Eleven hosted pages match the locally verified tables and headings; all six SVG assets load, and the final source/run identifiers were checked through the preview source link. The hosted performance page was also inspected in Chrome. The skipped route/TCK/GPU jobs do not add coverage; the separately recorded merged-master and private-companion validation remains the evidence for those areas.

[lmeyerov]

READY (cab184f) but LAST per the landing order: rebased on master; 59 green + 10 skipped + RTD; re-vendor from the master re-measure follows before the final merge.

[lmeyerov]

Re-vendored from the master re-measure: docs/source/_data/gfql_benchmarks.json now equals pyg-bench published/docs-numbers.json at pyg-bench main af1513f (PR graphistry/pyg-bench#249: SNB SF0.1/SF1 arms and q1–q9 20k/100k boards at pygraphistry master 5a6586f, sentinel baseline at 86de0f5). 166 of 262 cells changed, all within noise of the 4 September board except the seeded SNB shapes, which are the release wins (pandas message-content 10.06→1.66 ms, seed-lookup 30.12→3.91 ms; polars seed-lookup 21.82→10.19 ms). Losses stay on the pages through the same cells (100k q8 Kuzu 9.7 ms vs polars 14.0 ms; polars tag-cooccurrence 30.2→31.7 ms, inside its 17% run-to-run spread). The SNB pre-landing disclosure is gone (both scales are the release measurement); the GraphFrames note now says #2024 has landed since and the ladder was not re-run. docs/test_bench_numbers.py 37 pass. Stays open until the rest of the queue lands (merges last).

[lmeyerov]

CI receipt at 090ad9e: 59 check-runs success, 10 skipped by the path filter (docs-only change). docs/test_bench_numbers.py 37 pass locally; the vendored JSON equals pyg-bench main af1513f.

[lmeyerov]

Rebased onto master 1a41079 (60d39f0, docs only, clean). Expect the docs-numbers contract test to be RED on this head by design: the vendored boards were measured at 5a6586f and the landed 0.60 stack put them 19 compute commits behind master (policy allows 12). Rather than waive, the SNB arms, q1–q9 boards and sentinel are being re-measured at master 1a41079 on dgx now; this PR gets re-vendored from that run, with any cell that moved called out here. The three 0.59.0-era runs (GraphFrames ladder ×2, filter-pagerank) get explicit drift waivers with the reason stated in the pyg-bench PR. Review the prose and structure via the RTD preview meanwhile: https://pygraphistry--2017.org.readthedocs.build/en/2017/gfql/index.html

[lmeyerov]

CI on 60d39f0: 59 green, 11 filter-skipped. Correction to my note above: CI does not run docs/test_bench_numbers.py on this PR (it is among the skips), so CI green here is not evidence for the numbers. Locally that test fails on drift (19 compute commits past the policy's 12) until the re-vendor from the master 1a41079 re-measure lands.

[lmeyerov]

Editorial pass 1 (owner items 1–5, 7–12 on engines; 6 started) at 3dbf8fc. Preview rebuilds from this head in a few minutes:

• engines: https://pygraphistry--2017.org.readthedocs.build/en/2017/gfql/engines.html — the opening and the old 'Switching engines' section are one 'Switch engines with one keyword' section; the [F1]–[F5] footnotes are gone (their facts live in the decision table notes and three plain rules under it); 'When not to use Polars' is merged into that table; 'Parity and fallback rules' is three bullets under 'Same results on every engine'; 'Methodology' and the committed-artifact sentence are gone; 'Coming from another graph tool' states what GFQL removes and what you gain, and no longer describes competitors' strengths; the memory note has no parentheticals. Prose is about 40% shorter; every table and code block is kept.
• perf hub: https://pygraphistry--2017.org.readthedocs.build/en/2017/gfql/perf/index.html — two reader tracks: 'See what it is worth' (case study vs Neo4j + GDS first, then the boards, then GraphFrames) and 'Get the speed on your data' (engine, adjacency index, indexing guide, remote GPU), plus a short reference list.
• Editorial policy started at agents/skills/docs-review/SKILL.md (plain-language rules, a jargon table with replacements, AI-writing tells, review procedure). Jargon pass on the other perf pages is next; queued with your further items in plan.md before any edit.

[lmeyerov]

Jargon pass (item 6) at 777475d across performance, index_adjacency, indexing, benchmark_filter_pagerank, benchmark_graphframes, overview: 'seeded' → 'from known nodes' except the two defining first uses; 'receipt' / 'committed artifact' → 'run record'; 'parity' → 'identical results'; 'point lookup' → 'single-node lookup by id'; 'lane' → 'path'. No number changed. Items 1–12 from your list are now all applied; add more per page and I queue them in plan.md before editing.

[lmeyerov]

Re-vendored at d660e33 from the master 1a41079 re-measure (pyg-bench #251, publishing now). docs/test_bench_numbers.py passes locally including the drift policy (37 passed). Cells that moved more than 15% vs the 5a6586f vendoring: graphbench.20k.q4.polars_gpu 16.41 → 4.53 ms (the GPU tiny-point outlier did not reproduce), graphbench.20k.q8.polars_gpu 2.17 → 2.53, snb.sf01.message_creator.gfql_pandas_idx 2.87 → 2.33; everything else within run-to-run spread. Verdict changes on the boards: 100k q5 polars vs Kuzu is now a tie (0.97×, was a weak 1.12× win); 20k q8 is a tie (1.10×); 100k q8 stays the one loss. Board prose on performance.rst updated to the new verdicts; the tallies are roles and follow the cells automatically.