Choose efficient graph operations and understand measured scale and rendering limits.
The graph model is built around a CPU-canonical columnar model. Hot graph fields are stored
in typed arrays, arbitrary data is kept in sidecars, and an id index supports
direct lookup. This avoids creating and retaining one mutable JavaScript
object per field access. Collections are the public convenience layer; APIs
that consume or produce columns/slots can avoid materializing a handle for
every element when operating on large graphs.
For bulk input, prefer the constructor's elements option, a columnar payload
or streamed cy.load() chunks over a loop of one-element mutations. The
classic object format is convenient at application boundaries; convert it to
columnar form when allocation and transfer volume matter. load() applies
chunks progressively and lets a rendered graph draw between them.
Use cy.batch() when several writes can share one stylesheet application.
It defers style work to the outermost end of the batch; reads of derived style
values may be stale inside it. cy.patch() can preserve the state of surviving
elements during data refresh, but it still scans and applies a diff. Its cost
depends on id overlap and on which fields changed, so compare it with
recreation for the application's actual workload instead of treating it as a
universal faster path.
At 100k elements, in milliseconds, with recreate rows that vary by ~40% run to
run because of GC placement:
Id overlap
Recreate (wire)
App-side diff
patch (wire)
90%
167.4
265.6
96.2
80%
236.5
314.4
145.2
70%
161.2
369.2
197.9
50%
168.1
498.4
310.6
10%
230.2
777.7
522.2
A payload equal to the state costs 18–24 ms, one scan. The crossover is about
70% id overlap: above it a patch is cheaper and keeps every survivor's state;
below it, a refresh with no state worth keeping should reload (recreating is
1.8× cheaper at 50% and 2.3× at 10%). A diff written over the public API is
slower than recreating at every overlap.
Structured query objects test indexed flags and data columns without making a
predicate closure and element handle for every candidate. Use
getElementById() for a direct id lookup. Query objects are deliberately less
expressive than an arbitrary function; predicates remain available when the
application needs custom logic. A predicate pays the per-element callback and
handle cost, so use the structured form for common state/data filtering when it
expresses the rule.
The layout context exposes slot-oriented reads/writes for custom implementations.
Built-ins use these paths where suitable, and setPositions() batches the
tracked position updates. Directly modifying a public live column is not a
supported optimization; it can skip renderer dirty notifications and leave
the displayed graph stale.
Algorithm execution policy is per algorithm. Some algorithms are synchronous
CPU routines; whole-graph routines may return a cancelable promise and select
between CPU, worker and GPU executors. An explicit executor may reject when
the build or environment does not provide it. 'cpu' is the reproducible
reference for APIs that offer it. 'auto' is a policy choice, not a promise
that the GPU always wins or that all algorithms have a GPU implementation.
Read each method's API entry before relying on result timing or numerical
details.
The force layout can move its simulation to a worker or GPU. During a live
GPU force run, the position column is GPU-owned and CPU reads are stale until
the layout's readback at completion. Its live stream also does not emit one
CPU position event per node. Await the run or read at layoutstop when final
positions or CPU-side persistence matter. GPU trajectories can vary in
floating-point order; the CPU executor is the repeatable reference.
Rendering uses the GPU for geometry, labels, visibility and edge picking. Labels, mapped styles, edge routes, arrows and
compound bounds add work that a node-only graph does not have. Measure the
features and graph shapes the application actually uses. Headless mode avoids
the renderer entirely, but headless text dimensions are estimates; a rendered
font atlas provides the glyph measurements used for exact label layout.
Avoid benchmarking only constructor time or total graph throughput. A useful
profile separates conversion, first visible chunk, settled layout, interaction,
dirty style updates, export/readback, memory and allocations. Profile on your
users' target devices with representative graph data and styles.
The ceiling is 16,776,960 elements per group, and the same number of glyphs per
label stream, which is about 2M labelled nodes. It is one dispatch's reach,
65,535 workgroups × 256, rather than a memory limit. A node slot costs 164
bytes and an edge slot 132. Custom polygons have no such guard: 8-point polygons
reach their pool's limit at about 1M nodes.
What cannot fit or failed to allocate stops drawing once, with a gpuerror
carrying degraded, and the frame stays valid. The order is:
'labels': a glyph stream past its limit stops uploading and every label
is no longer drawn. Label dimensions remain available to graph operations.
'charts', 'images', 'curves': an oversized blob is replaced by a
placeholder and its pass is skipped.
'gradients': gradients draw solid.
A refused core column has nothing to degrade to. The scene holds its last frame
('frames'), a pending pick or count answers null and an export rejects, until
a re-mount.
// The renderer's frame statistics, or null when headlesscy.stats(): RendererStats | null
The renderer's frame statistics, or null when headless. The snapshot carries the frame timings, cache hit rates and pass counters — note that cpuFrameMs is encode/submit cost only (submission is fire-and-forget), so reconcile fps against gpuFrameMs.