[rjb32]

What

Brings the docs in line with TuringDB 3.0.2. #19 documented 3.0.1, and this is the delta since then, mostly in the query language.

Query language (query/)

• New page, NEXT and WHEN (query/composition, in the nav after Results and aggregation). It covers:
  • NEXT: passing nodes on, longer chains, after a UNION, braced chains as UNION sides, inside CALL / EXISTS / COUNT, writes, scoping rules
  • WHEN ... THEN ... ELSE: several branches, subquery conditions, per row after NEXT and in CALL, no ELSE, NEXT chains in a branch, UNION, writes, rules
• New syntax:
  • label expressions on nodes and edge types (:A|B, :!A, :A&B), in patterns, OPTIONAL MATCH and WHERE
  • COLLECT { }, with WHERE, DISTINCT, top-k, UNION, collected nodes and its limits; UNION and NEXT bodies for EXISTS / COUNT; CALL (*) { }, and CALL bodies that write and return
  • FOREACH: edges off a matched node, several clauses, list properties, conditional writes with the CASE trick, RETURN after it
  • multi-hop quantified path patterns, with group variables as lists
  • comprehensions over a variable-length edge list ([r IN e | r.since]), and reduce to sum along a route
• Query parameters (new section in the overview): $name works for labels and edge types (MATCH (n:$label), CREATE (n:$label)). Value parameters are still listed as not yet supported.
• Functions:
  • new: substring, left, right, split, replace, char_length, normalize / IS NORMALIZED, keys, properties, the OrNull conversions, stDev, stDevP, percentileCont, percentileDisc
  • function names are now case-insensitive
  • min and max work over lists and mixed types
  • CASE and coalesce branches can mix types
• Maps: keys can be read anywhere (m.key, m[k]), including maps stored as properties (n.meta.level).
• Behaviour:
  • Integers and Doubles compare by value, and Double = Double is still steered to ranges.
  • An unmatched OPTIONAL MATCH node is null.
  • MERGE sees what earlier queries of the change wrote.
  • A null key in CREATE is skipped.
  • Undirected CREATE is reported.
  • list + x appends an element.
• Lookup by native node ID (rewritten): id(n) = 123 is now a direct lookup, and so are ID batches from any list source, including two IDs from one row. The old "exact shape" and "never two IDs per row" rules are gone.
• Writing data:
  • a new "Edges between existing nodes" recipe sends ID pairs in one UNWIND
  • map and mixed-type rows are written with toString() / toInteger(), replacing the parallel-lists workaround

Other pages

• commands:
  • -start-timeout removed, -no-vector-mmap added, and start errors described
  • shell :param / SHOW PARAMETERS
  • HTTP API: JSON body {"query", "parameters"}, decimal change=, a 1 MiB limit (REQUEST_TOO_BIG), full-precision Doubles, and GRAPH_NOT_FOUND
• pythonsdk/reference:
  • turingdb>=3.0.2, upgrading SDK and server together
  • query(q, query_parameters)
  • decimal change IDs and the new error codes
  • a shortestPath path can't yet be read over the native backend
• troubles: new entries for The request body must be a JSON object and REQUEST_TOO_BIG, and the function-name entry updated
• import_data/csv: OPTIONAL MATCH reading row.x works, so the workaround is gone
• import_data/jsonl: load errors name the line
• vector-search: HNSW indexes are memory-mapped, and re-loading IDs replaces their vectors
• shortest-path, graph_dev/create_nodes_edges, claude-skill: small updates to match

How it was checked

• Every cypher example in query/ (332 statements) was run against a server built from the 3.0.2 engine, on the sample graph from the matching page. Writes ran in a change that was deleted afterwards.
  • Every new or changed example runs, and the row counts match the sample graph.
  • The 6 remaining failures need things the test setup lacks: the Stations graph, my_index, knows.csv and the greeter extension. Two blocks list several commands without blank lines between them.
• Edge cases behind each rule (what NEXT, WHEN and COLLECT accept and reject, the exact error messages) were probed on the same server.
• The new Python snippets (parameters, the bulk-edge recipe) were run against the same server. Behaviour claims (the HTTP API, CLI start errors, shell :param, native backend, LOAD JSONL errors, vector reloads) were probed on 3.0.2.
• npm run build passes (43 pages), anchor parity is 293/293, and every new internal link resolves.