Skip to content

Performance

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.

#Loading and mutation

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.

#Queries and collections

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.

#Algorithms and layouts

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 costs and limits

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.

#Scale limits

Measured on an RX 580 through Chromium, with n = m/4 and each scene in a fresh browser (benchmark/scale-ceiling.mjs):

Scene (nodes × edges) Init VRAM JS heap GPU frame Outcome
1,048,576 × 4,194,305 4.0 s 1,357 MB 2.47 GB 23.8 ms rendered
2M × 8M 7.9 s 1,466 MB 3.24 GB 48.4 ms rendered
4,194,240 × 16,776,960 17.9 s 2,926 MB 6.02 GB 106.2 ms rendered
4,194,240 × 16,776,961 17.9 s — 6.02 GB — cy.ready rejects with GpuUnfitError
1M × 3M, labelled 4.4 s 1,306 MB 1.81 GB 32.8 ms rendered
2.5M × 2.5M, labelled 8.3 s 1,247 MB 2.94 GB 30.2 ms rendered, labels degraded

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:

  1. 'labels': a glyph stream past its limit stops uploading and every label is no longer drawn. Label dimensions remain available to graph operations.
  2. 'charts', 'images', 'curves': an oversized blob is replaced by a placeholder and its pass is skipped.
  3. '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.

#Diagnostics

#cy.stats()

// The renderer's frame statistics, or null when headless
cy.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.

Returns RendererStats | null

a RendererStats snapshot, or null on a headless instance

Example

console.log(cy.stats()); // null

Example graph and handle setup

All guides · Alphabetical API index · Read continuously