Limits of D3.js .enter() selection with key functions

Direct Answers

Duplicate keys: D3's data-join uses a Map keyed by the key function's return value. When multiple data points produce the same key, only the first datum is matched to an existing DOM element (or enters as a new one). Subsequent data points with that key are excluded from the .enter() selection entirely—they produce no DOM nodes and are effectively dropped from the visual representation.

Undefined or null keys: D3 treats undefined and null as literal key values. If your key function returns null for several data points, they all share the same key null. Only the first such datum enters; the rest are ignored, just like any other duplicate key.

Performance at tens of thousands of items: The key function itself runs in O(n) and is rarely the bottleneck. The cost comes from the internal Map construction during .data() and, more significantly, from DOM mutation when the enter selection is materialized. For 50,000+ items, the join reconciliation can block the main thread for hundreds of milliseconds, especially if the enter selection appends complex SVG structures.

Why This Happens

The data-join algorithm (D3 v3–v7) builds a Map<string, Element> from the current selection's bound data keys. It then iterates the new data array, looking up each key in that map. A key seen for the first time creates an enter node; a key already consumed by a prior datum in the same join is skipped. This single-pass design guarantees O(n) join time but makes duplicate-key behavior deterministic: first occurrence wins.

Practical Verification

const data = [
  {id: 1, val: 'a'},
  {id: 2, val: 'b'},
  {id: 1, val: 'c'} // duplicate key
];

const sel = d3.select('body').selectAll('div')
  .data(data, d => d.id);

console.log(sel.enter().nodes().length); // logs 2, not 3

Run the snippet in a console with D3 loaded. The enter selection length equals the count of unique keys, not the data array length.

Mitigations

• Ensure key uniqueness by composing a compound key (e.g., d => `${d.category}-${d.index}`) or using a UUID.
• Guard against null/undefined in the key function: d => d.id ?? `missing-${index}`.
• Prefer .join() over .enter() (D3 v5+). .join() handles enter, update, and exit in one call and avoids orphaned nodes.
• For >10k items, consider canvas/WebGL rendering, virtualization, or batching DOM mutations across frames with requestAnimationFrame.

One Diagnostic Detail

What D3 version are you targeting? The .join() API and some internal Map behaviors differ between v4, v5, v6, and v7, which changes the exact migration path.