Data Joins in d3js

Data Joins is probably the most complicated thing in d3.js to understand.

I typically call this creating things out of thin air You will have the ability to create elements based on your data.

To use data joins we need to use selectAll to create a selection of multiple elements and then we call data on the selection. (Learn more about Selection here)

What this will do is to map the data to the selection.

There are three ways to look at this map/join.

We don‘t have any of those elements on that page
We have less elements on that page than data entries
We have too many elements on that page

Let‘s start with the simpler case:

We don‘t have any of those elements on that page

It‘s easier to look at it with an example. Suppose we have the following data: data = ['Daisy', 'Jemma', 'Phil', 'Mac'] And we want to make a list with these names. A list in html is ul and one list element is li

What we do is create a selection of li list elements. And then join these with the data we have and create them.

d3.selectAll('li').data(data)

We select all list elements (selectAll). This selection is empty because we don‘t have any list elements on the page.

When we join the data to it with data we tell d3 that we want four elements of type li. Internally d3 creates a few arrays were going to take a closer look at: Interesting for our first use case is that it creates an enter array which contains a selection of placeholders for how many elements need to be created. In our case all of the data objects, so four. The array contains placeholder elements for those which d3 created for us which makes it possible for d3 to create the actual elements. We take a look at the other arrays later, when we deal with the next cases.

We can get the enter selection with

d3.selectAll('li').data(data).enter()

This is a new selection of the not yet created elements. It is slightly different than the usual selection. It has a few more methods we can use. We can call append on the selection and it will create those elements and append it to the parent of our selection.

d3.selectAll('li').data(data).enter().append('li')

We end up with four new li elements on the page. Let's look at the difference in creating elements.

If you do d3.select('ul').append('li') It will append just one element to the selection. You could even do

d3.selectAll('li').append('p')

Which will append one paragraph to all existing list elements

d3.selectAll('li').data(data).enter().append('li')

Will create new elements.

We have less elements on that page than data entries

Let’s look at a case where we already have elements of the type we’re looking to create already available on the page. Let’s say we already have an li element on the page. If we call:

d3.selectAll('li').data(data)

And we look at the enter array. The enter array now only contains two elements. Because we don’t need to create the third since it’s already on the page.

And now we take a look at one of the two other arrays d3 created internally. Introducing groups.

Groups contains your selection usually. If we use data to bind the data to a selection groups contains the element that are already on the page but also empty placeholders for the amount of elements that we eventually want.

With this selection we then call enter as before to create the missing elements. Remember we have elements on the page already, so then enter selection will have only those elements that are not yet available.

d3.selectAll('li').data(data).enter().append('li')

Will create the missing elements.

How to change the remaining elements?

Now that we‘ve created the missing elements, we need to change the appearance of elements the already on the page.

We do that by calling merge with our previous selection.

var selection = d3.selectAll('li').data(data)
selection.enter().append('li').merge(selection)

Due to method chaining (read about it here) after we call append, the resulting selection are the new elements. We then merge these two selections into one selection.

The following code achieves the same thing (merging the two selections) but with slightly more code:

var selection = d3.selectAll('li').data(data)
var enter = selection.enter().append('li')
selection.merge(enter)

Now we can change the attributes of all these elements, since we merged them into one selection.

var selection = d3.selectAll('li').data(data)
selection.enter()
.append('li')
.merge(selection)
.attr('class', 'selection')

We have more elements than data entries

The last case is that we have more elements on our page than entries in our data array. So we don‘t need to create new elements, but delete the ones that are not needed anymore.

D3 shorthand

Lucky for us d3 v5 introduced a new method that removes unecessary boilerplate code.

Introducing join: The join method will take care of all the append , remove, and merge calls for us:

Instead of

var selection = d3.selectAll('li').data(data)
selection.enter()
.append('li')
.merge(selection)
.attr('class', 'selection')
.text('paragraph')
selection.exit().remove()

We just call

var selection = d3.selectAll('li').data(data)
.join('li')
.attr('class', 'selection')
.text('paragraph')

Pretty nice, right?