d3.json method doesn't return my data array

Question

I'm using d3.json to load a JSON file containing my data, like this:

var data = d3.json(url, callback)

If I do a console.log(data) I can see that data is neither empty nor null. However, it doesn't seem to contain my data array, but something else instead.

What am I doing wrong here?

---

^{Note: this is a self-answered question, trying to provide a "canonical" Q&A on a subject that has been touched on by many previous questions and not (clearly) explained by the API. The answer below was written as a general guidance to those questions.}

Answer 1

TL;DR

d3.json (as well as d3.csv, d3.tsv etc) does not return the content of the loaded/parsed file. Instead of that, it returns an object related to the request in D3 v4 or lower, and a promise in D3 v5 or higher.

What does d3.json return? (v4 or lower)

d3.json is one of the alternatives to XMLHttpRequest provided by D3. According to the API, d3.json...

Returns a new request to get the JSON file at the specified url with the default mime type application/json.

... which, we can agree, is not particularly clear. Because of that, you probably thought that you could return the loaded data using var data = d3.json(url, callback), but that's incorrect. What d3.json returns is an object (not an array), associated with the request. Let's see it.

I have this JSON in a file:

{"foo": "42"}

What happens if we use d3.json the way you used it in your question? Click "run code snippet" to see:

var data = d3.json("https://api.npoint.io/5b22a0474c99d3049d2e", function() {});

console.log(data)

<script src="https://d3js.org/d3.v4.min.js"></script>

As you can see in the console, we have an object like this:

{header: ƒ, mimeType: ƒ, responseType: ƒ, timeout: ƒ, user: ƒ, …}

Well, this is not our data array.

The same thing happens if you use a function:

function getData() {
  return d3.json("https://api.npoint.io/5b22a0474c99d3049d2e", function() {})
}

var data = getData()

console.log(data)

<script src="https://d3js.org/d3.v4.min.js"></script>

Also, it's worth mentioning that the same thing happens with d3.csv, d3.tsv and the other request methods:

var data = d3.csv("https://www.ibm.com/support/knowledgecenter/SVU13_7.2.1/com.ibm.ismsaas.doc/reference/AssetsImportCompleteSample.csv", function() {});

console.log(data)

<script src="https://d3js.org/d3.v4.min.js"></script>

How to use d3.json?

The correct way to load the data with d3.json, as you can see in several online examples, is using its callback:

d3.json(url, function(data){
    //use data here...
});

And here is the snippet with our JSON file:

d3.json("https://api.npoint.io/5b22a0474c99d3049d2e", function(data) {
  console.log(data)
})

<script src="https://d3js.org/d3.v4.min.js"></script>

You can also call another function: the data will be passed as the first argument. Here is a demo:

d3.json("https://api.npoint.io/5b22a0474c99d3049d2e", callback)

function callback(data) {
  console.log(data)
}

<script src="https://d3js.org/d3.v4.min.js"></script>

What does d3.json return? (v5 or higher)

In D3 v5, d3.json (as well as d3.csv, d3.tsv etc) returns a promise:

var data = d3.json("https://api.npoint.io/5b22a0474c99d3049d2e");

console.log(data)

<script src="https://d3js.org/d3.v5.min.js"></script>

Check it in your browser's console, not the Stack snippet console.