// Reconcile a fresh payload into the live graph by id: the payload is the next state of the same graph — the next query result, a server's refresh — and the patch computes what to add, remove and update, applies it as one batch, and returns what it did
cy.patch(input: ElementsInput<NodeData, EdgeData>, options?: PatchOptions): PatchDiff<NodeData, EdgeData>Reconcile a fresh payload into the live graph by id: the payload is the next state of the same graph — the next query result, a server's refresh — and the patch computes what to add, remove and update, applies it as one batch, and returns what it did. A surviving element keeps selection, bypasses, running animations, listeners and scratch. Position follows the payload when carried; miniature state and its applied factor are adopted together with those current positions. The sheet, viewport and graph-level data() are never touched — elements only.
cy.json() is export-only; use a fresh core to restore a serialized session. patch() updates an existing graph. It reconciles a data refresh, and it takes all three input forms — definition, columnar and wire — through the load path's one funnel.
The rules, per payload element, keyed on its id: - Survives when the graph holds the id in the same group (and, for an edge, the same source and target). Its data record is replaced, not deep-merged: a key the payload element lacks is cleared, and a value compares structurally, so a fresh payload equal to the state changes nothing. Its position is written when the payload carries one and kept when it does not — except that a locked node (or every node, under autolock) holds its position and a compound parent's derives from its children, as at load. Its parent follows the payload (none means an orphan). Its miniature state follows when carried; the payload's applied factor is installed without rescaling its already-current positions. Its selection and selectable/locked/grabbable/pannable flags are session state and are never read from the payload. - Added when the id is new, and when the payload element has no id — exactly as cy.add() would add it, flags included. - Removed and re-added when an edge's source or target changed identity (rewiring is not a patch), or when the id changed group. - Removed when the graph holds an id the payload does not name — in 'reconcile' mode, the default. In 'merge' mode it is kept, and a definition-form payload may name kept nodes as endpoints and parents. Removal cascades as remove() does.
Events: remove, add, moveout + move (a reparented survivor), data, position, and committed collapse/expand state changes fire once per element, inside the batch and after every mutation has landed; then one core-level patch event carries the diff as event.diff — for an app that only wants the summary. A patch whose payload equals the state fires no element event, writes nothing and returns an empty diff (its patch event still fires). The patch is one transaction: batchstart, the element events, patch, then batchend; inside an app's batch it joins that one, and patch fires before the app's batchend.
| Name | Description |
|---|---|
input: ElementsInput<NodeData, EdgeData> | the payload, in definition, columnar or wire form |
options: PatchOptions? |
|
Fields of input
| Name | Description |
|---|---|
columnar: true | discriminant so the loader can tell the forms apart |
nodes: ElementDefinition<NodeData>[]? | |
edges: ElementDefinition<EdgeData>[]? | |
refs: string[] | PackedIds? | Node references (experimental with the wire format until 4.x): the
ids of nodes this payload does not carry but indexes — an edge endpoint
or a node parent |
data: DefinitionData<Data>? | |
group: GroupName? | inferred from |
position: Position? | nodes only |
collapsed: boolean? | nodes only: persisted miniature-compound state |
appliedCollapseScale: number? | nodes only: current applied factor when collapsed; omitted uses the configured collapse-scale |
selected: boolean? | |
selectable: boolean? | |
grabbable: boolean? | |
locked: boolean? | |
pannable: boolean? | dragging this element pans the graph instead (default: true for edges, false for nodes) |
Fields of options
| Name | Description |
|---|---|
mode: PatchMode? |
|
PatchDiff<NodeData, EdgeData>the diff: the added, removed and updated collections
Example
cy.patch([{ data: { id: 'a', score: 10 } }]);console.log(cy.getElementById('a').data('score')); // 10before anything is mutated, if the payload names an id twice, if an edge lacks a source or target or names one that is not a node (in the payload, or — merge mode — in the graph), if a column does not fit the payload's counts, or on an unknown option or mode