docs(gfql): start-here nav with perf/reference hubs; result-first benchmark pages

[lmeyerov]

Summary

Docs-only. Base is master because develop was promoted and deleted in #2016. Two changes to the GFQL docs, no page moves, no product code, no benchmark numbers changed.

1. GFQL navigation: short start path + two hubs. gfql/index had one 22-entry User Guide toctree. It now has:

Before (one flat list)

After

about, overview, remote, engines, indexing, index_adjacency, performance, benchmark_filter_pagerank, benchmark_graphframes, translate, combo, quick, cypher, where, return, predicates/quick, datetime_filtering, builtin_calls, policy, strict_mode, schema, wire_protocol_examples; Developer Resources: spec, validation

Start Here: about, overview, quick, cypher Guides: Performance and Benchmarks (gfql/perf/index: engines, performance, indexing, index_adjacency, remote, both benchmark pages), Language Reference (gfql/reference/index: where, return, predicates, datetime_filtering, builtin_calls, combo, translate, policy, strict_mode, schema, wire_protocol_examples, loading_graph_data) Developer Resources: spec, validation (unchanged)

Every existing URL is unchanged: the hubs are new index pages that list the existing files, so first-time readers see four pages and experienced readers expand a hub. gfql/loading_graph_data was not in any toctree before; it now sits in the reference hub. The bench-number policy pins gfql/index.rst and gfql/benchmark_filter_pagerank.rst by path, which is another reason not to move files.

2. Benchmark pages: result first, one limits section, plain technical English. gfql/benchmark_filter_pagerank and gfql/benchmark_graphframes now open with the measured outcome and which engine to use, and move all measurement rules into one "Method and limits" section per page. Removed: repeated inline caveats, self-referential wording ("honest", "stated plainly", "documented, not hidden"), triple restatement of the same numbers, and the trailing "What this shows / Why this matters / For more" sections. Sentences are short and active.

Numbers: unchanged. The filter/PageRank page still prints every figure through :bench: roles with both bench-provenance blocks and bench-disclosures. Every GraphFrames literal was re-derived from gfql/_static/graphframes/results.json (ratios recompute to the published 43x/7.4x/2.3x/14.7x/0.33x and 42x/8.7x/1.3x/10.5x/0.23x). Two edits to unverifiable text: the host memory is now "about 120 GB" (the exact 119 GB figure has no source in the repo), and Friendster node/edge counts cite SNAP. The Cypher example's -- comments are now // (valid Cypher; removes a Sphinx lexer warning).

Follow-up (not in this PR): migrating the GraphFrames literals to :bench: cells needs a new exporter kind in pyg-bench.

Validation

• rstcheck --config docs/.rstcheck.cfg on all five touched .rst: clean
• python -m pytest docs/test_bench_numbers.py: 26 passed
• Local sphinx-build -b html (Sphinx 9.1, no Docker): exit 0; zero warnings on touched pages; remaining warnings are pre-existing (missing demos/ in a bare checkout, API duplicate targets)
• Every gfql/ page is in exactly one toctree (scripted check over 36 pages); rendered sidebar matches the table above
• CHANGELOG: ## [Development] → ### Docs
• CI note: the test-docs lane skipped because it needs: python-lint-types, which skips on docs-only changes (pre-existing workflow gap, not changed here). The Read the Docs PR build is the CI evidence for this PR.

Slop audit criteria followed the anti-style guide in ~/Work/research/ai-slop-anti-guide (result first, no self-assessment residue, one caveat per claim, named comparison scope).

Owner review wave (second commit)

• gfql/overview: opens with the positioning (only open-source in-process Cypher on dataframes; columnar/vectorized framing alongside DuckDB/ClickHouse); the empty hidden toctree that made the page render as a folder is removed.
• Neo4j page retitled Case Study: Cypher + PageRank Pipeline, GFQL vs Neo4j + GDS and listed under Start Here (URL unchanged). The lede says what is compared, what GFQL and Neo4j + GDS are, and the outcome; the above-the-fold caveat paragraph is gone; "The pipeline" gets a lead sentence.
• GraphFrames page: the lede states the comparison and the outcome (best engine faster in all 8 cells; CPU alone in 6 of 8), and two per-task bar charts (livejournal_tasks.svg, orkut_tasks.svg) are rendered from results.json by gfql_bench_charts.py under the same sync test as the Neo4j charts.
• Provenance: bench-provenance accepts several run ids and renders one Measurement block with reader-facing fields only and caveats folded in; the separate "About these measurements" box is gone from this page. Run provenance strings now lead with the RAPIDS base image (pyg-bench [BUG] Neptune p3.16 instance does not start #220, vendored byte-identical).

Wave 3 (owner review, 2026-09-04)

• Numbers were stale, now fixed at the source: the vendored pyg-bench artifact pointed at the 2026-07-26 q1–q9 board; pyg-bench ci(mypy) #222 retargets it to the relaned 2026-08-13 board (GFQL bound cold per timed run) with Kuzu, Memgraph, and Neo4j columns, publishes the aligned SNB SF0.1/SF1 four-engine matrix, and adds a valid-lane audit so a newer valid board can no longer sit unpublished. This PR vendors that artifact byte-identically.
• Prevention in this repo: the bench extension enforces policy.max_compute_commit_drift against the checkout (git history permitting; per-run waivers with reasons ride in the artifact), and a new :bench-tally: role derives "N of M queries faster" from cells so counts never go stale by hand.
• gfql/performance: no release-pinned headings; every hand-typed legacy figure removed; SNB tables with the databases' wins stated; five-engine q1–q9 boards; one Measurement block.
• Structure/wording: Start Here = 10-minute guide, overview, Speedup Case Study; quick reference and Cypher syntax head the Language Reference hub; plain titles for the indexing pages; engines page note boxes folded into prose and a rewritten "coming from" table (Memgraph added, PuppyGraph dropped); overview merges Why/Key Features and links the engine-design and launch posts; about examples 3–7 gain tested Cypher twins (example 4 now returns rows on its own sample graph); marketing filler removed.
• Filed while testing the examples: gfql cypher: WHERE on a single alias of a multi-alias MATCH is rejected as multi-source #2019 (single-alias WHERE rejected in multi-alias MATCH), gfql cypher pandas: three IN predicates across (a)-[e]->(t) crash with 'Unalignable boolean Series' (polars OK) #2020 (pandas three-IN crash).

Wave 3 evidence (2026-09-04, commits a3e4e91 + 751b37b)

• T2.9.12 q1–q9 boards re-measured at PyGraphistry 0.59.0 with a polars-gpu column (pyg-bench ci(mypy) #222/[FEA] Remote hypergraph #230): performance.rst prints tallies (GFQL Polars beats Kuzu 8/9 at 20k and 8/9 at 100k; Memgraph 7/9 and 6/9; Neo4j 9/9 and 8/9; GPU beats CPU 4/9 at 100k) and names every loss, including GPU q8 at 100k.
• T2.9.16/.17 GraphFrames ladder, first publication (pyg-bench [FEA] Docker security scan #235): benchmark_graphframes.rst now prints cells only — host-Spark GraphFrames baselines for LiveJournal and Orkut, GFQL GPU PageRank with the cuGraph solver stage split out (shaded in the charts: LJ 890.9 ms query / 59.3 ms solver, 18.3x vs GraphFrames; Orkut 2,795.7 ms / 151.4 ms, 12.5x), and the released code's LJ filter/hop rows as diagnostic cells. The June results.json and the parity file are removed; charts render from cells and are tested on a synthetic ladder.
• Loss stated: the released undirected multi-hop path is ~30x slower than in June (LJ 2-hop 64 s) — issue perf(gfql): undirected multi-hop is ~30x slower since #1918 — pure-Python O(E) seed-rediscovery loop #2023, fix in PR perf(gfql): numpy form of the undirected seed-rediscovery rule (#2023) #2024 (engine-native rework after review). The released code's LJ 2-hop stays on the page as a diagnostic before-state sentence.
• Ladder at the fix head (commit 1b81975, pyg-bench [FEA] Bill of materials tracking #236): GFQL filter/hop cells and ratios for LiveJournal and Orkut measured at PR perf(gfql): numpy form of the undirected seed-rediscovery rule (#2023) #2024's head (disclosed as pre-landing in the provenance block; re-receipt after it lands): CPU faster than GraphFrames on filter and 1-hop on both graphs, GraphFrames wins 2-hop on both (0.5x LJ, 0.4x Orkut), the GPU streaming executor loses every hop.
• T2.9.16/T2.9.15 Friendster: one attempt on the CPU streaming path — 1.8B edges bound from a lazy scan, degree filter 3.1 s (6,585,312 nodes), 1-hop 6.1 s (166,615 nodes), peak RSS 106 GB of the 119 GB host; 2-hop/PageRank not attempted (projected past the host from the Orkut peak), GraphFrames did not load it. The page opens with that measured ceiling, has a Friendster table and chart, and one bench-provenance block over both ladder runs.
• Prevention (T2.9.18): lane audit + compute-commit drift enforcement + bench-tally (this PR), PR-template checklist and a fixed load-breach classifier in pyg-bench (Dev/hypergraph fixes #231, [FEA] RDF/sparql support - neptune, ... #234).
• Validation for this push: rstcheck, local sphinx build (bench-number audit clean), docs/test_bench_numbers.py 36 passed; RTD preview checked in Chrome after build.

🤖 Generated with Claude Code

https://claude.ai/code/session_01WwMmVFo44ADiRRj5cxh7i1

[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.