That said, with key caching turn on (the default), it will still be more efficient using `dataloader` than without it.

If you are using `graphql`, you are likely to making queries on a graph of data (surprise surprise). `dataloader` will help

you to make this a more efficient process by both caching and batching requests for that graph of data items. If `dataloader`

has previously see a data item before, it will cached the value and will return it without having to ask for it again.

Imagine we have the StarWars query outlined below. It asks us to find a hero and their friend's names and their friend's friend's

names. It is likely that many of these people will be friends in common.

{

hero {

name

friends {

name

friends {

name

}

}

}

}

The result of this query is displayed below. You can see that Han, Leia, Luke and R2-D2 are tight knit bunch of friends and

share many friends in common.

[hero: [name: 'R2-D2', friends: [

[name: 'Luke Skywalker', friends: [

[name: 'Han Solo'], [name: 'Leia Organa'], [name: 'C-3PO'], [name: 'R2-D2']]],

[name: 'Han Solo', friends: [

[name: 'Luke Skywalker'], [name: 'Leia Organa'], [name: 'R2-D2']]],

[name: 'Leia Organa', friends: [

[name: 'Luke Skywalker'], [name: 'Han Solo'], [name: 'C-3PO'], [name: 'R2-D2']]]]]

]

A naive implementation would called a `DataFetcher` to retrieved a person object every time it was invoked.

In this case it would be *15* calls over the network. Even though the group of people have a lot of common friends.

With `dataloader` you can make the `graphql` query much more efficient.

As `graphql` descends each level of the query ( eg as it processes `hero` and then `friends` and then for each their `friends`),

the data loader is called to "promise" to deliver a person object. At each level `dataloader.dispatch()` will be

called to fire off the batch requests for that part of the query. With caching turned on (the default) then

any previously returned person will be returned as is for no cost.

In the above example there are only *5* unique people mentioned but with caching and batching retrieval in place their will be only

*3* calls to the batch loader function. *3* calls over the network or to a database is much better than *15* calls you will agree.

If you use capabilities like `java.util.concurrent.CompletableFuture.supplyAsync()` then you can make it even more efficient by making the

the remote calls asynchronous to the rest of the query. This will make it even more timely since multiple calls can happen at once

if need be.

Here is how you might put this in place:

```java

// a batch loader function that will be called with N or more keys for batch loading

BatchLoader<String, Object> characterBatchLoader = new BatchLoader<String, Object>() {

@Override

public CompletionStage<List<Object>> load(List<String> keys) {

//

// we use supplyAsync() of values here for maximum parellisation

//

return CompletableFuture.supplyAsync(() -> getCharacterDataViaBatchHTTPApi(keys));

}

};

// a data loader for characters that points to the character batch loader

DataLoader characterDataLoader = new DataLoader<String, Object>(characterBatchLoader);

//

// use this data loader in the data fetchers associated with characters and put them into

// the graphql schema (not shown)

//

DataFetcher heroDataFetcher = new DataFetcher() {

@Override

public Object get(DataFetchingEnvironment environment) {

return characterDataLoader.load("2001"); // R2D2

}

};

DataFetcher friendsDataFetcher = new DataFetcher() {

@Override

public Object get(DataFetchingEnvironment environment) {

StarWarsCharacter starWarsCharacter = environment.getSource();

List<String> friendIds = starWarsCharacter.getFriendIds();

return characterDataLoader.loadMany(friendIds);

}

};

//

// DataLoaderRegistry is a place to register all data loaders in that needs to be dispatched together

// in this case there is 1 but you can have many

//

DataLoaderRegistry registry = new DataLoaderRegistry();

registry.register(characterDataLoader);

//

// this instrumentation implementation will dispatched all the dataloaders

// as each level fo the graphql query is executed and hence make batched objects

// available to the query and the associated DataFetchers

//

DataLoaderDispatcherInstrumentation dispatcherInstrumentation

= new DataLoaderDispatcherInstrumentation(registry);

//

// now build your graphql object and execute queries on it.

// the data loader will be invoked via the data fetchers on the

// schema fields

//

GraphQL graphQL = GraphQL.newGraphQL(buildSchema())

.instrumentation(dispatcherInstrumentation)

.build();

One thing to note is the above only works if you use `DataLoaderDispatcherInstrumentation` which makes sure `dataLoader.dispatch()` is called. If

this was not in place, then all the promises to data will never be dispatched ot the batch loader function and hence nothing would ever resolve.

See below for more details on `dataLoader.dispatch()`

The original [Facebook DataLoader](https://github.com/facebook/dataloader) was written in Javascript for NodeJS. NodeJS is single-threaded in nature, but simulates

return (result, t) -> {

if (t == null) {

// only dispatch when there are no errors

dataLoaderRegistry.dispatchAll();

}

};

import graphql.GraphQL;

import graphql.schema.DataFetcher;

import graphql.schema.DataFetchingEnvironment;

import graphql.schema.GraphQLSchema;

import org.dataloader.DataLoaderRegistry;

import org.dataloader.graphql.DataLoaderDispatcherInstrumentation;

@SuppressWarnings("ALL")

class StarWarsCharacter {

List<String> getFriendIds() {

return null;

}

}

void starWarsExample() {

// a batch loader function that will be called with N or more keys for batch loading

BatchLoader<String, Object> characterBatchLoader = new BatchLoader<String, Object>() {

@Override

public CompletionStage<List<Object>> load(List<String> keys) {

//

// we use supplyAsync() of values here for maximum parellisation

//

return CompletableFuture.supplyAsync(() -> getCharacterDataViaBatchHTTPApi(keys));

}

};

// a data loader for characters that points to the character batch loader

DataLoader characterDataLoader = new DataLoader<String, Object>(characterBatchLoader);

//

// use this data loader in the data fetchers associated with characters and put them into

// the graphql schema (not shown)

//

DataFetcher heroDataFetcher = new DataFetcher() {

@Override

public Object get(DataFetchingEnvironment environment) {

return characterDataLoader.load("2001"); // R2D2

}

};

DataFetcher friendsDataFetcher = new DataFetcher() {

@Override

public Object get(DataFetchingEnvironment environment) {

StarWarsCharacter starWarsCharacter = environment.getSource();

List<String> friendIds = starWarsCharacter.getFriendIds();

return characterDataLoader.loadMany(friendIds);

}

};

//

// DataLoaderRegistry is a place to register all data loaders in that needs to be dispatched together

// in this case there is 1 but you can have many

//

DataLoaderRegistry registry = new DataLoaderRegistry();

registry.register(characterDataLoader);

//

// this instrumentation implementation will dispatched all the dataloaders

// as each level fo the graphql query is executed and hence make batched objects

// available to the query and the associated DataFetchers

//

DataLoaderDispatcherInstrumentation dispatcherInstrumentation

= new DataLoaderDispatcherInstrumentation(registry);

//

// now build your graphql object and execute queries on it.

// the data loader will be invoked via the data fetchers on the

// schema fields

//

GraphQL graphQL = GraphQL.newGraphQL(buildSchema())

.instrumentation(dispatcherInstrumentation)

.build();

}

private GraphQLSchema buildSchema() {

return null;

}

private List<Object> getCharacterDataViaBatchHTTPApi(List<String> keys) {

return null;

}

import static org.hamcrest.Matchers.equalTo;

assertThat(registry.getDataLoaders(), equalTo(asList(dlA, dlB, dlC)));

assertThat(registry.getDataLoaders(), equalTo(asList(dlA, dlB, dlC)));

assertThat(registry.getDataLoaders(), equalTo(asList(dlA, dlB)));

import java.util.concurrent.CompletionStage;

class CountingLoader implements BatchLoader<Object, Object> {

int invocationCount = 0;

List<Object> loadedKeys = new ArrayList<>();

@Override

public CompletionStage<List<Object>> load(List<Object> keys) {

invocationCount++;

}

}

@Test

public void basic_invocation() throws Exception {

final CountingLoader batchLoader = new CountingLoader();

DataLoader<Object, Object> dlA = new DataLoader<>(batchLoader);

DataLoader<Object, Object> dlB = new DataLoader<>(batchLoader);

DataLoader<Object, Object> dlC = new DataLoader<>(batchLoader);

assertThat(batchLoader.invocationCount, equalTo(3));

assertThat(batchLoader.loadedKeys, equalTo(asList(singletonList("A"), singletonList("B"), singletonList("C"))));

}

@Test

public void exceptions_wont_cause_dispatches() throws Exception {

final CountingLoader batchLoader = new CountingLoader();

DataLoader<Object, Object> dlA = new DataLoader<>(batchLoader);

DataLoaderRegistry registry = new DataLoaderRegistry()

.register(dlA);

DataLoaderDispatcherInstrumentation dispatcher = new DataLoaderDispatcherInstrumentation(registry);

InstrumentationContext<CompletableFuture<ExecutionResult>> context = dispatcher.beginExecutionStrategy(null);

// cause some activity

dlA.load("A");

context.onEnd(null, new RuntimeException("Should not run"));

assertThat(batchLoader.invocationCount, equalTo(0));