bindings docs: whole-type aggregates and distinct values, SQL GROUP BY in the parallel workers (26.10.1, upstream #8797, #8799) - #41

Closes #40.

The queries guide gains two paragraphs under 'Scans run in parallel only outside a transaction', both measured on upstream main 3d5e1a5, 2,000,000 records, 12 cores, Temurin 25 and 21, one bucket and eight, every answer equal across forms:

1. Whole-type aggregates: in 26.10.1 a SQL aggregate over a type scan runs in the parallel workers, while an openCypher aggregate over a label runs on one thread (an unfiltered label scan is sequential; with a WHERE the scan is parallel and the aggregation is not). sum 127-130 ms in SQL against 680-752 ms in Cypher; group-by 226-239 ms against 973-1,146 ms. Advice: write whole-type aggregates in SQL until openCypher: an aggregate over a label runs on one core, 4-8x behind the same SQL aggregate since #8524 (sum over 2M vertices: 680 ms against 127 ms) ArcadeData/arcadedb#8797 changes it.
2. Distinct values: SQL SELECT DISTINCT projects and dedups on one thread, while GROUP BY over the same columns runs in the workers and returns the same rows. 1,185-1,481 ms against 92-111 ms; with a WHERE 695-859 ms against 98-103 ms. Advice: GROUP BY (SQL SELECT DISTINCT projects and dedups on the consumer thread: 13x slower than GROUP BY over the same column (1,185 ms against 92 ms at 2M records) ArcadeData/arcadedb#8799).

Example 05 (and its docs page) now reads its user ids with SELECT userId FROM Rating GROUP BY userId ORDER BY userId in place of a SELECT DISTINCT subquery; its docstring note about the older direct DISTINCT form is rewritten. All three creation modes (--method sql, --method java, --method java --no-async) re-run on the 26.10.1.dev0 wheel against movielens-small with both databases open: 610 users and every baseline match, as before the change.

Repros kept in the private notes (agg-parallel).

🤖 Generated with Claude Code

https://claude.ai/code/session_01WWcDr7TwvcfMsQkeYQVHZr