What is the difference D3 datum vs. data?

Question

I found the correct answer here from Mike himself:

D3 - how to deal with JSON data structures?

If you want to bind your data to a single SVG element, use

(...).data([data])

or

(...).datum(data)

If you want to bind your data to multiple SVG elements

(...).data(data).enter().append("svg")

.....

After having looked into this a bit, I've found that the answers here on SO are not complete as they only cover the case when you invoke selection.data and selection.datum with an input data parameter. Even in that scenario, the two behave differently if the selection is a single element versus when it contains multiple elements. Moreover, both of these methods can also be invoked without any input arguments in order to query the bound data/datum in the selection, in which case they once again behave differently and return different things.

Edit - I posted a slightly more detailed answer to this question here, but the post below pretty much captures all the key points regarding the two methods and how they differ from each other.

When supplying data as an input argument

• selection.data(data) will attempt to perform a data-join between the elements of the data array with the selection resulting in the creation of enter(), exit() and update() selections that you can subsequently operate on. The end result of this is if you pass in an array data = [1,2,3], an attempt is made to join each individual data element (i.e. datum) with the selection. Each element of the selection will only have a single datum element of data bound to it.

• selection.datum(data) bypasses the data-join process altogether. This simply assigns the entirety of data to all elements in the selection as a whole without splitting it up as in the case of data-joins. So if you want to bind an entire array data = [1, 2, 3] to every DOM element in your selection, then selection.datum(data) will achieve this.

Warning: Many people believe that selection.datum(data) is equivalent to selection.data([data]) but this is only true if selection contains a single element. If selection contains multiple DOM elements, then selection.datum(data) will bind the entirety of data to every single element in the selection. In contrast, selection.data([data]) only binds the entirety of data to the first element in selection. This is consistent with the data-join behavior of selection.data.

When supplying no data input argument

• selection.data() will take the bound datum for each element in the selection and combine them into an array that is returned. So, if your selection includes 3 DOM elements with the data "a", "b" and "c" bound to each respectively, selection.data() returns ["a", "b", "c"]. It is important to note that if selection is a single element with (by way of example) the datum "a" bound to it, then selection.data() will return ["a"] and not "a" as some may expect.

• selection.datum() only makes sense for a single selection as it is defined as returning the datum bound to the first element of the selection. So in the example above with the selection consisting of DOM elements with bound datum of "a", "b" and "c", selection.datum() would simply return "a".

Note that even if selection has a single element, selection.datum() and selection.data() return different values. The former returns the bound datum for the selection ("a" in the example above) whereas the latter returns the bound datum within an array (["a"] in the example above).

Hopefully this helps clarify how selection.data and selection.datum() differ from each other both when providing data as an input argument and when querying for the bound datum by not providing any input arguments.

PS - The best way to understand how this works is to start with a blank HTML document in Chrome and to open up the console and try adding a few elements to the document and then start binding data using selection.data and selection.datum. Sometimes, it's a lot easier to "grok" something by doing than by reading.

Here are some good links:

• Good discussion on D3 "data()": Understanding how D3.js binds data to nodes

• D3 for Mere Mortals

• Mike Bostock's D3 Wiki

Per the latter:

# selection.data([values[, key]])

Joins the specified array of data with the current selection. The specified values is an array of data values, such as an array of numbers or objects, or a function that returns an array of values.

...

# selection.datum([value])

Gets or sets the bound data for each selected element. Unlike the selection.data method, this method does not compute a join (and thus does not compute enter and exit selections).

I think the explanation given by HamsterHuey is the best so far. To expand on it and give a visual representation of the differences I created a sample document that illustrates at least part of the differences between data and datum.

The below answer is more of an opinion derived from using these methods, but I am happy to be corrected if I'm wrong.

This example can be run below or in this Fiddle.

const data = [1,2,3,4,5];
const el = d3.select('#root');

 el
  .append('div')
  .classed('a', true)
  .datum(data)
  .text(d => `node => data: ${d}`);

const join= el
.selectAll('div.b')
.data(data);

join
.enter()
.append('div')
.classed('b', true)
.text((d, i) => `node-${i + 1} => data: ${d}`)

I think that datum is simpler to grasp since it doesn't do a join, but of course this also mean it has different use cases.

To me one big difference - although there are more - is the fact that data is just the natural way of doing (live) updates on a d3 chart, as the whole enter/update/exit pattern makes it simple, once you get it.

datum on the other hand seems to me to be more suited for static representations. In the example below for example I could achieve the same result my looping on the original array and accessing the data by index like so:

data.map((n, i) => {
 el
  .append('div')
  .classed('a', true)
  .datum(data)
  .text(d => `node-${n} => data: ${d[i]}`);
});

Try it here: https://jsfiddle.net/gleezer/e4m6j2d8/6/

Again, I think this is way easier to grasp as you keep free from the mental burden coming from the enter/update/exit pattern, but as soon you need to update or change the selection you will surely be better off resorting to .data().

const data = [1,2,3,4,5];
const el = d3.select('#root');

 el
  .append('div')
  .classed('a', true)
  .datum(data)
  .text(d => `node => data: ${d}`);

const join= el
.selectAll('div.b')
.data(data);

join
.enter()
.append('div')
.classed('b', true)
.text((d, i) => `node-${i + 1} => data: ${d}`)

/* Ignore all the css */
html {
  font-family: arial;
}

.l {
  width: 20px;
  height: 20px;
  display: inline-block;
  vertical-align: middle;
  margin: 10px 0;
}
.l-a {
  background: #cf58e4;
}
.l-b {
  background:  #42e4e4;
}

.a {
  border-bottom: 2px solid #cf58e4;
}

.b {
  border-bottom: 2px solid #42e4e4;
}

<script src="https://cdnjs.cloudflare.com/ajax/libs/d3/5.6.0/d3.min.js"></script>


<div style="margin-bottom: 20px;">
  <span class="l l-a"></span> .datum() <br />
  <span class="l l-b"></span> .data()
</div>

<div id="root"></div>