G3: writes and transactions

[tamnd]

Milestone G3 of the GQL program (Spec/2064g/gql/plan/00-overview.md). Specs: plan/03 §7, plan/06 §4.

Blocked by P5 (#78). Blocked by G2 (#117), because writes need labels and edge properties to write.

The parser rejects CREATE, SET, DELETE, DETACH and MERGE by name, so zu is read only as far as GQL is concerned, and three whole graph-bench families produce no zu numbers at all: snb-update, linkbench and fb-write. The machinery underneath is not the problem, M3 delivered WAL, single writer commit, overlays, checkpoint, recovery and a crash injection harness, and the recovery matrix is checked in. This milestone is the statement surface over machinery that is already crash tested, plus the one genuinely new thing, which is a transaction local catalog overlay.

writes (plan/03 §7):

• INSERT in both subquery and simple expression forms
  • standalone node patterns, with property values run through the same evaluator every other expression goes through
  • edges between the elements one INSERT creates, with the endpoint check against the tables the edge type declares
  • edges carrying properties, through the log record and the fold that hold them
  • MATCH followed by INSERT, so the write runs once for every row the clauses before it answered
  • a label that names no node table, which today is a reference error and wants catalog work to become a table
• SET and REMOVE for properties and for labels
  • SET of a property of a node, run once per row, with the clauses after it reading what it wrote
  • SET of a property of an edge, which is addressed by the order its table holds its edges
  • SET of a whole record, which empties every property the record does not name
  • REMOVE of a property, which the binder turns into a null and the fold records in a validity mask
  • SET and REMOVE of a label the row's table already declares, which puts the bit on and takes it off the row's label word so a pattern naming it finds the row afterwards
  • SET of a label the table has not declared, which the statement declares itself, publishing the widened catalog before it stages the bit and taking the declaration back with the rows when it raises
• DELETE and DETACH DELETE
  • DELETE of a node with no edges on it, which stages a tombstone the fold merges into the table's chain and every read filters by
  • DELETE of a node that still has edges raises G1001 rather than leaving an edge pointing at nothing
  • DETACH DELETE, which takes the edges on an element with it through a log record that names a removed edge by the rows it runs between and a fold that drops that pair out of the CSR it rebuilds
  • DELETE of an edge the statement named itself, which is the one delete that never has to refuse, and NODETACH DELETE, which is the default said out loud
• key label set changes, which move an element between element types
• graph type violations raise the right code and name the offending element

transactions (plan/06 §4):

• START TRANSACTION, COMMIT, ROLLBACK as explicit statements
• transaction characteristics, READ ONLY and READ WRITE
• implicit transactions, committed on success and rolled back on any raising condition
• READ ONLY enforced before any work happens, so the planner can skip write path setup
• multiple graphs in one transaction within a catalog, cross catalog raises 40000 class rather than half committing
• transaction local catalog overlay, merged at commit and discarded at rollback

status codes:

• the eleven write time limit and dependent object codes of plan/07

done when:

• GD 4 of 4 and GT 3 of 3 supported in the gql-compat report
• the seven transactions capability skips are gone
• crash harness green including the catalog overlay
• snb-update, linkbench and fb-write produce zu numbers for the first time, recorded in graph-bench results/
• bench/budgets.toml green, no regression anywhere in the comparative matrix

[tamnd]

First piece landed, though it is groundwork rather than a checklist line: #211 makes the parser refuse the write and transaction statements by name instead of guessing. Before it, INSERT (x:Person) came back as "expected MATCH, OPTIONAL MATCH, CALL, UNWIND, WITH, or RETURN", which sends a reader looking for a typo in a statement that has nothing wrong with it. Now it says "line 1, column 1: INSERT is not implemented yet", and the same goes for SET, REMOVE, DELETE, DETACH, MERGE, START, COMMIT, ROLLBACK, SESSION, FINISH and FOR. Eleven cases in the gql-compat corpus changed message. CREATE stays on the list for the opposite reason, being the Cypher spelling of a statement GQL does not have, so naming it is still the better answer than a parse position.

On the shape of the work itself, having read the pipeline end to end this week: the executor takes &mut dyn Graph and every method on that trait reads, while a write needs the file. The overlay store from M3 is real and crash tested, but nothing on the query side has ever opened a WAL, and Zu1Graph does not consult an overlay, so a committed insert is invisible to the next MATCH in the same session. That is the actual gap, not the parser. Plan is to land it in order: first a write side for a session that owns the log and the overlay and can commit and fold, tested on its own with no statement surface over it, then INSERT of standalone node patterns on top of that, then MATCH followed by INSERT for edges between matched nodes, then SET, REMOVE and DELETE, then the explicit transaction statements. Each of those is a separate PR against a piece that is already green.

Benchmarks stay honest about the machine they run on: the write families here are snb-update, linkbench and fb-write, none of which have produced a zu number yet, and graph-bench now measures its own noise floor before calling anything a regression, so the first write numbers will land with the floor recorded alongside them.

[tamnd]

Second piece landed: #212 gives a session a write side. This is the part of the plan above about owning the log and the overlay before there is any statement surface over them, and it is done. crates/zu/src/write.rs holds a Writer over one open file: it owns the WAL and the Mvcc store, recovers whatever the log holds above the last checkpoint, and turns a staged transaction into a committed epoch. Session::write runs one of those against a closure, which is how the implicit transaction rule gets answered for free, because a closure that raises has staged nothing durable and dropping it on the way out is the whole of the undo.

The interesting decision is that every commit that changed something folds, and that is temporary and documented as temporary in the module. Zu1Graph reads the sealed file and never consults an overlay, so a change that is not folded is a change the next MATCH cannot see, and a write nobody can read is not a write. A fold rewrites every column of every table the transaction touched, so paying one per statement is exactly the wrong shape for a write workload and it will be the first thing to go once the read path consults overlays. At that point this becomes a policy and a background checkpoint and the only line that moves is where Writer::fold gets called. Writing it down now so the first write benchmark numbers are read with that in mind, because they will be slow for a reason that is known and scheduled rather than mysterious.

The other thing worth recording is the reconciliation with the bulk load appender that landed in #213 the same week. Both open a WAL beside the same database, and two logs beside one database is two recoveries that disagree, so there is one sidecar path and both use it. Session::file_mut drops the writer before it hands the file out, since an appender holding the same log can truncate it, and that costs a recovery pass on the next write and loses nothing, because a writer that has folded holds an empty store and recovery reconstructs exactly what it was holding. Six tests cover the contract: a committed row the next query reads, a committed edge the next hop walks, a raise that leaves the epoch where it was, a transaction that stages nothing and publishes nothing, a log left behind by a crash that the next open seals, and an appender and a write statement sharing one log.

No checklist line ticks yet, since none of them describe groundwork. Next up is INSERT of standalone node patterns, which is where the first box starts to move.

[tamnd]

Third piece landed: #216 makes INSERT of standalone node patterns a statement that runs, so the first checklist line has its first tick, split into three parts because standalone nodes are not the whole of INSERT and ticking the line whole would say they were. INSERT (x:person {age: 30, name: 'zoe'}) RETURN x.name AS name writes a row and answers the row it wrote, and the next MATCH in the same session finds it, which is the thing that was missing when the write side landed on its own in #212.

The seam is worth writing down because it is the one that will move. LogicalPlan::Insert is a real plan node and EXPLAIN prints the elements the statement writes, but the session performs the write before the plan runs and hands each created element to the plan as an argument past the last declared parameter, one UNWIND per element. The reason is the same one from the comment above: the executor reads through zu_query::exec::Graph and every method on that trait reads, while appending a row needs the file. When the read path consults overlays this moves into the executor and the compiled plan does not change, which is why the plan node exists now rather than later.

Property values run as a projection over the one empty row through the ordinary executor rather than through an evaluator written for writes. That was deliberate: a second evaluator is a second set of answers, and 20 + 10 and $who and 1 / 0 have to mean here what they mean in a WHERE, so there is one implementation and the tests for arithmetic and parameters in an INSERT pass because the tests for them everywhere else pass.

What is refused, and why each refusal exists rather than a surprise later: a value the column cannot hold raises 22G03 before the transaction opens, a label that names no table raises 42002, an element that leaves a column out is named by the column it left out because the fold has nowhere to put an absence, an element carrying a key that is not a column is named rather than silently dropped, and a table that stores no properties has no column for a row to grow so creating an element in it is refused outright instead of staging nothing and handing back an element at an offset no row occupies. A read only connection is told it is read only before any of that is worked out, so the answer is about the connection rather than about the statement. The session less entry points zu::query::run, profile and explain_analyze refuse a write and name the API that owns the log, which is zu::db::Database or zu::session::Session; zu shell, zu query, the C ABI and Connection all go through a session and all write.

Two conformance notes went in with it, and they are the honest part. The GD01 cases in gql-compat run against the blank fixture, which declares no tables at all, so INSERT (n:Person {name: 'a'}) there still fails: zu creates an element in an existing node table named by the label, and naming a label does not create a table. That is catalog work and it is now its own unticked sub item. optional/gd01/insert-edge-between-matched-nodes needs the edge piece, which is next.

Gates: 67 test suites green on the workspace, fmt, clippy, deny, miri, fuzz and the three platform test jobs all pass, the API model and the api map are unchanged, terms reports nothing to fix, and conformance.toml was regenerated from the two new notes. No benchmark numbers yet, because one statement at a time still pays one fold per commit and timing that would measure the fold rather than the insert; the write families snb-update, linkbench and fb-write stay unrun until the overlay read path lands, exactly as recorded above. Next is MATCH followed by INSERT for edges between matched nodes.

[tamnd]

PR #218 is merged, so an INSERT can now write an edge.

What landed: the binder binds an edge pattern in an INSERT, checks its endpoints against the node tables the edge type declares and refuses a mismatch by name, and the session stages the new nodes and the new edges in one transaction so a reader never sees an edge whose ends are not there yet. An edge the statement wrote is a value it can return, and it is there to walk on the next statement. The evaluator that runs property values is the same one every other expression goes through, so nothing new was added for them.

What is not in it: an edge carrying properties, because WalRecord::RelInsert has no room for them and giving it room is a log format change that belongs in its own PR. That is now the only part of the edge sub-item left, and it is tracked as its own line below.

The two conformance notes that described the write surface were updated in the same PR and conformance.toml was regenerated, so the gql-compat harness reads the new shape. No case moves yet: the gd01 edge cases need either the properties above or the per row write that is in review next.

[tamnd]

PR #220 is merged, so a write runs once for every row the clauses before it answered.

MATCH (a:person) INSERT (a)-[:knows]->(b:person {name: 'new'}) now writes one node and one edge per person the match found, and the clauses after the write read what came of it rather than the store. The statement is split at each write into parts, each part but the last ends in a projection of the slots that are live where the write sits with the write's property expressions behind them, the session runs the write once per row of that projection and commits the lot in one transaction, and the next part reads those rows back in through a new plan leaf that compiles to an operator feeding an argument's rows in as batches.

Reading the rows back rather than planning through the write is the point. A scan under a write would answer over the store the write just changed, so the statement would meet its own output and write again for it. There is a test named for that.

The old seam went with it. An insert pattern no longer carries an argument position, the session no longer evaluates property values itself, and the Insert plan node no longer compiles to anything: it stays as what EXPLAIN prints and the executor refuses a plan holding one by name, because the session that owns the log is the only thing that runs a write.

EXPLAIN ANALYZE on a statement that writes is refused for now. A profile is the counters of one run of one plan and a write is run as several, so the refusal is the honest answer rather than the counters of whichever part came last.

Still no gql-compat number moves. The one edge case in gd01 writes [k:KNOWS {since: 2020}], so it needs edge properties, which is the remaining unticked line under INSERT and is a log format change of its own. That is the next piece.

[tamnd]

#222 is in, so an edge can now carry properties: INSERT (a)-[:knows {since: 2020}]->(b) writes the year with the edge and a later MATCH reads it back through k.since. That was the last unticked line under INSERT apart from the catalog one.

The reason this needed a log format change rather than a field is that a rel table stores its properties as dense columns in load order, which is the order the neighbour lists are in, so an edge is addressed by its ordinal in that order. An added edge moves every edge behind it and every value with it. So WalRecord RelInsert grew a column list, one entry per column of the table and one value per edge in the same order as the endpoints it already carried, the overlay holds those cells beside the pair each edge runs between, and the fold sorts base edges and overlay edges together, remembers where each one came from, and rewrites the whole of every column into the new order, lanes and blobs alike.

Four things are refused and each says which. An edge written into a table that stores nothing on its edges, because there is no column to put the value in. An edge that leaves a column out, named by the column, because a column holds one value per edge. A second edge over a pair the table already holds, because the ordinal is found by searching the pair and two edges over one pair would both answer to it. A column that may hold a null, which is the same refusal a node column already gets.

No gql-compat number moves yet, but optional/gd01/insert-edge-between-matched-nodes fails further along than it did. Its pair fixture declares no KNOWS edges, so the statement now stops at no edge table is named 'KNOWS' rather than at the property. That is the catalog line above, which is where the next work under this milestone goes along with SET, REMOVE and DELETE.