perf(kuzu): write Parameter, Module and ExternalClass as node-only then relationship-only batches - #1748

Problem

EmbeddedSessionWrapper.run sends every UNWIND batch that MERGEs a node and a relationship down a per-row loop.
This is a guard against the Kùzu 0.11.3 mis-binding of repeated node keys (#1605).

Three writers use exactly that shape:

• add_file_to_graph → Function–Parameter, HAS_PARAMETER;
• add_file_to_graph → File–Module, IMPORTS;
• write_inheritance_links._run_external → child–ExternalClass, INHERITS.

On a 2062-file C# repository these three turn about 3400 batches into about 48 000 single-row queries. That is about
half of the total graph-write time.

Change

Each of the three writes now runs two queries. Neither of them hits the guard, and the guard itself is unchanged.

1. Node-only UNWIND with distinct node keys, so no key repeats inside a batch. The old MATCH stays, so a node is
   created only where the combined query would have created it:
   • Parameter keys are first read under the Function MATCH;
   • Module keeps MATCH File;
   • ExternalClass keeps MATCH child.
2. Relationship-only UNWIND — MATCH both ends, MERGE the relationship, same SET.

Behaviour kept on purpose:

• Module metadata. Per field, the first non-null value in the existing sort_import_rows_for_metadata order —
  what the sequential coalesce SETs leave.
• Repeated IMPORTS key. Rows sharing an IMPORTS relationship key keep the last row's values. A batched
  MERGE … SET keeps the first row of a non-adjacent duplicate key; row by row, the last one wins. Rows with different
  keys are never merged.
• External inheritance. Label-less rows still fan out over every populated child label.
• Missing field. A missing confidence_label still defaults to 'INFERRED'.
• Errors. Any error in the split pair reruns that chunk through the old combined query, i.e. the old per-row path
  with its skip / retry / drop semantics. All MERGEs involved are idempotent.

Diff: writer.py +96 / −7. New tests/unit/tools/test_split_node_rel_batches.py. One query-text assertion in
test_graph_builder_perf_fixes.py now looks for the Module coalesce SETs on the node query.

Evidence (Kùzu 0.11.3, Windows)

Equivalence: before vs after, whole-DB dump — every table and property.

The fixture covers:

• two occurrences of one function;
• shared and duplicate args;
• a missing Function;
• competing, braced, super::* and pub use imports;
• a non-adjacent duplicate IMPORTS key;
• one Module from two files;
• duplicate and fan-out external parents;
• a missing child.

Results on the fixture:

• the graph is identical;
• the per-row path is taken 11 times before and never after;
• five deliberately wrong variants are all caught: no occurrence_index, last-non-null metadata, no last-row rule, a
  parent created without its child, no label-less fan-out.

Real C# repository (2062 files):

• first 301 writer calls: identical whole-DB dump;
• first 2000 external-inheritance rows on a full graph: identical ExternalClass nodes and edges.

Silent-fallback guard. If the split pair ever starts failing and quietly falls back to the per-row path, the new
tests fail. They were checked against that mutation, and they fail only on the "no forced per-row query" assertion,
because the fallback's result is still correct.

Speed. Exclusive query time, on main vs this commit, same data:

The 301-call sample took 171.2 s → 64.0 s in total.

A replay of the complete write workload of that repository (2066 writer calls, fresh graph) went from 8808.5 s to
2209.0 s (×3.99) with an identical semantic projection. That figure was measured on a development branch that also
carries unrelated SCIP-parser changes below this commit. Those changes do not touch these writers, and on main the
same sample graphs are byte-identical to that branch's.

Tests. tests/unit/tools + tests/unit/core fail on exactly the same 4 pre-existing tests before and after.

Not in scope

• the wrapper guard itself;
• other node+relationship shapes (js_imports, module_inclusions, …);
• UID matching, path normalization, buffer / checkpoint settings.

🤖 Generated with Claude Code