Skip to content

Commit 7f13f98

Browse files
lmeyerovclaude
andcommitted
docs(gfql): silo benchmark numbers in performance.rst; stable claims elsewhere
Restructure per review: performance.rst is now the canonical benchmark-numbers page (alongside index_adjacency for the index benchmarks) so a benchmark rerun touches one page, not six. - performance.rst: keeps the 0.58.0 release-verified section with provenance stated once at the top; absorbs the full Orkut/LiveJournal bulk-sweep table, reading notes, crossover figures, and methodology from engines.rst with a single dating sentence instead of scattered "prior sweep" tags. - engines.rst: number tables and inline figures removed; new qualitative "How the engines compare" section; competitor rows (Neo4j, Kuzu, LadybugDB, GraphFrames), decision-matrix notes, and footnotes now make stable qualitative claims and link to performance.rst / index_adjacency; methodology section is a pointer to the numbers page. - quick.rst / about.rst / overview.rst / index.rst: one-liners reworded to stable "often an order of magnitude faster on query-heavy workloads" phrasing with links — no datasets, versions, or ratios. - Rebased on master (PR #1771 merged); CHANGELOG entries placed alongside, entry rewritten to describe the siloed architecture. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Y6dQEcjdazEnzuvuwf73ZL
1 parent 2f7c8c9 commit 7f13f98

7 files changed

Lines changed: 194 additions & 249 deletions

File tree

CHANGELOG.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
1010

1111
### Documentation
1212
- **GFQL pay-as-you-go resident indexing user guide**: New :doc:`Pay-As-You-Go Resident Indexing <gfql/indexing>` page — the lifecycle guide to resident indexes (`gfql_index_all()` / `gfql_index_edges()` / `create_index()` / `show_indexes()` / `drop_index()`): what the node-id + CSR in/out adjacency sidecars are, what engages them on 0.58.0 (seeded typed-hop fast paths incl. property RETURNs and property-seeded lookups per #1768/#1770, direct `g.hop()`; the general polars chain traversal honestly noted as not yet covered), the staleness/validity contract (identity + fingerprint; rebind invalidates; declines are safe — identical results either way), engine notes (polars needs `gfql_index_all(engine='polars')` until #1767), 0.58.0-tag measured numbers, and a runnable end-to-end example. Wired into the GFQL toctree + recommended paths alongside :doc:`Seeded Traversal Indexes <gfql/index_adjacency>`.
13-
- **GFQL performance docs refreshed with 0.58.0 release-tag-verified numbers**: `gfql/performance.rst` and `gfql/engines.rst` now lead with numbers measured on the `0.58.0` release tag (DGX Spark GB10, warm medians N=30, results verified identical across engines): the seeded typed-hop Cypher fast path across all four engines (pandas 29.9→2.46ms 12.1×, polars 13.8→2.28ms 6.1×, cuDF 30.1→4.89ms 6.1×, polars-gpu 25.2→2.49ms 10.1×; native chain pandas 21.1→1.65ms 12.8×), resident-index covered-shape lookups (1.59–5.78ms, with the 0.58.0 `gfql_index_all(engine='polars')` caveat / PR #1767), flat seeded-hop scaling on pandas (0.159–0.164ms from 0.25M to 32M edges), the one-keyword `engine='polars'` LDBC SNB SF1 seed-lookup win (1,299.6→106.1ms, 12.3×), LDBC SNB interactive SF1 vs Neo4j 5.26 same-box pairs (GFQL 4 of 5; Neo4j wins recent-replies — reported as-is), and OLAP multi-join vs embedded Kuzu (q8 200×, q9 14.2×) with the honest inverse (Kuzu wins single-table aggregates 2–4× and seeded property-projection lookups 2.4–64×). Older Orkut/LiveJournal bulk-sweep tables are retained but relabeled as prior-release measurements; the stale "up to ~38×" headline in `engines.rst`, `performance.rst`, `quick.rst`, `about.rst`, `overview.rst`, and `index.rst` is replaced with the tag-verified 12.3× LDBC figure.
13+
- **GFQL performance docs: 0.58.0 release-tag-verified numbers, siloed in one page**: `gfql/performance.rst` is now the canonical benchmark-numbers page (alongside `gfql/index_adjacency.rst` for the index benchmarks) — a benchmark rerun updates it alone. It carries the 0.58.0 tag sweep (DGX Spark GB10, warm medians N=30; four-engine numbers cross-engine parity-verified, competitor pairs validated against expected result rows): seeded typed-hop fast path across all four engines (e.g. pandas 29.9→2.46ms, 12.1×), native chain form, resident-index covered-shape lookups (with the `gfql_index_all(engine='polars')` caveat / PR #1767), flat seeded-hop scaling on pandas (0.159–0.164ms from 0.25M to 32M edges), the one-keyword `engine='polars'` LDBC SNB SF1 seed-lookup win (1,299.6→106.1ms, 12.3×), LDBC SNB interactive SF1 vs Neo4j 5.26 same-box pairs (GFQL 4 of 5; Neo4j wins recent-replies — reported as-is), OLAP multi-join vs embedded Kuzu (q8 200×, q9 14.2×) with the honest inverse (Kuzu wins single-table aggregates 2–4×, seeded property-projection lookups 2.4–64×), plus the prior Orkut/LiveJournal bulk sweep (moved from `engines.rst`, dated once) and its methodology. All other pages — `engines.rst`, `quick.rst`, `about.rst`, `overview.rst`, `index.rst` — now carry stable qualitative claims (e.g. "often an order of magnitude faster on query-heavy workloads") that link into `performance.rst` instead of inline figures, replacing the stale "up to ~38×" headlines and avoiding scattered per-claim version labels.
1414

1515
## [0.58.0 - 2026-07-22]
1616

docs/source/gfql/about.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -382,7 +382,7 @@ results on every engine — see :doc:`Choosing an Engine <engines>`.
382382

383383
::
384384

385-
g_result = g.gfql([ ... ], engine='polars') # e.g. 12.3x over pandas on LDBC SNB SF1 seed-lookup
385+
g_result = g.gfql([ ... ], engine='polars') # often much faster on query-heavy workloads
386386

387387
**Example: Force GFQL to use a GPU engine**
388388

0 commit comments

Comments
 (0)