Skip to content

Commit 0b6e4c3

Browse files
dondonzdondonz
committed
Merge branch 'master' into happy-10th-birthday
2 parents 3dee3ff + 78084b7 commit 0b6e4c3

File tree

4 files changed

+186
-6
lines changed

4 files changed

+186
-6
lines changed

‎documentation/batching.md

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -370,3 +370,67 @@ DataFetcher<?> dataFetcherThatCallsTheDataLoader = new DataFetcher<Object>() {
370370
}
371371
};
372372
```
373+
374+
## Chained DataLoaders
375+
376+
The automatic dispatching of Chained DataLoaders is a new feature included in GraphQL Java 25.0 onwards. Before this version, DataLoaders in chains needed to be manually dispatched.
377+
378+
A Chained DataLoader is where one DataLoader depends on another, within the same DataFetcher.
379+
380+
For example in code:
381+
```java
382+
DataFetcher<CompletableFuture<Object>> df1 = env -> {
383+
return env.getDataLoader("name").load("Key1").thenCompose(result -> {
384+
return env.getDataLoader("email").load(result);
385+
});
386+
};
387+
```
388+
389+
### How do I enable Chained DataLoaders?
390+
You must opt-in to Chained DataLoaders via `GraphQLUnusualConfiguration.DataloaderConfig`, as this may change order of dispatching.
391+
392+
Set `enableDataLoaderChaining(true)` to enable Chained DataLoaders.
393+
394+
For example, to set `enableDataLoaderChaining`:
395+
```java
396+
GraphQL graphQL = GraphQL.unusualConfiguration(graphqlContext)
397+
.dataloaderConfig()
398+
.enableDataLoaderChaining(true);
399+
```
400+
401+
### What changed in GraphQL Java 25.0?
402+
The DataFetcher in the example above, before version 25.0 would have caused execution to hang, because the second DataLoader ("email") was never dispatched.
403+
404+
Prior to version 25.0, users of GraphQL Java needed to manually dispatch DataLoaders to ensure execution completed. From version 25.0, the GraphQL Java engine will automatically dispatch Chained DataLoaders.
405+
406+
If you're looking for more examples, and the technical details, please see [our tests](https://github.com/graphql-java/graphql-java/blob/master/src/test/groovy/graphql/ChainedDataLoaderTest.groovy).
407+
408+
Note: The GraphQL Java engine can only optimally calculate DataLoader dispatches on a per-level basis. It does not calculate optimal DataLoader dispatching across different levels of an operation's field tree.
409+
410+
### A special case: Delayed DataLoaders
411+
412+
In a previous code snippet, we demonstrated one DataLoader depending on another DataLoader.
413+
414+
Another special case is a "delayed" DataLoader, where a DataLoader depends on a slow async task instead. For example, here are two DataFetchers from [a test example](https://github.com/graphql-java/graphql-java/blob/master/src/test/groovy/graphql/ChainedDataLoaderTest.groovy):
415+
416+
```groovy
417+
def fooDF = { env ->
418+
return supplyAsync {
419+
Thread.sleep(1000)
420+
return "fooFirstValue"
421+
}.thenCompose {
422+
return env.getDataLoader("dl").load(it)
423+
}
424+
} as DataFetcher
425+
426+
def barDF = { env ->
427+
return supplyAsync {
428+
Thread.sleep(1000)
429+
return "barFirstValue"
430+
}.thenCompose {
431+
return env.getDataLoader("dl").load(it)
432+
}
433+
} as DataFetcher
434+
```
435+
436+
By opting in to Chained DataLoaders, GraphQL Java will also calculate when to dispatch "delayed" DataLoaders. These "delayed" DataLoaders will be enqueued for dispatch after the async task completes.

‎documentation/getting-started.mdx

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@ repositories {
2525
}
2626
2727
dependencies {
28-
implementation 'com.graphql-java:graphql-java:24.1'
28+
implementation 'com.graphql-java:graphql-java:24.2'
2929
}
3030
```
3131
</TabItem>
@@ -38,7 +38,7 @@ repositories {
3838
}
3939

4040
dependencies {
41-
implementation("com.graphql-java:graphql-java:24.1")
41+
implementation("com.graphql-java:graphql-java:24.2")
4242
}
4343
```
4444
</TabItem>
@@ -51,7 +51,7 @@ Dependency:
5151
<dependency>
5252
<groupId>com.graphql-java</groupId>
5353
<artifactId>graphql-java</artifactId>
54-
<version>24.1</version>
54+
<version>24.2</version>
5555
</dependency>
5656
```
5757

‎documentation/profiler.md

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
---
2+
title: "Profiling requests"
3+
date: 2025-08-05T12:52:46+10:00
4+
---
5+
6+
# Profiling GraphQL requests
7+
8+
We've introduced a new profiling feature to help you understand the performance of your GraphQL executions. It provides detailed insights into DataFetcher calls, Dataloader usage, and execution timing. This guide will show you how to use it and interpret the results.
9+
10+
The Profiler is available in all versions after v25.0.beta-5. It will also be included in the forthcoming official v25.0 release.
11+
12+
## Enabling the Profiler
13+
14+
To enable profiling for a GraphQL execution, you need to set a flag on your `ExecutionInput`. It's as simple as calling `.profileExecution(true)` when building it.
15+
16+
```java
17+
import graphql.ExecutionInput;
18+
import graphql.GraphQL;
19+
20+
// ...
21+
GraphQL graphql = GraphQL.newGraphQL(schema).build();
22+
23+
ExecutionInput executionInput = ExecutionInput.newExecutionInput()
24+
.query("query Hello { world }")
25+
.profileExecution(true) // Enable profiling
26+
.build();
27+
28+
graphql.execute(executionInput);
29+
```
30+
31+
## Accessing the Profiler Results
32+
33+
The profiling results are stored in the `GraphQLContext` associated with your `ExecutionInput`. After the execution is complete, you can retrieve the `ProfilerResult` object from the context.
34+
35+
The result object is stored under the key `ProfilerResult.PROFILER_CONTEXT_KEY`.
36+
37+
```java
38+
import graphql.ExecutionInput;
39+
import graphql.ExecutionResult;
40+
import graphql.GraphQL;
41+
import graphql.ProfilerResult;
42+
43+
// ...
44+
ExecutionInput executionInput = /* ... see above ... */
45+
ExecutionResult executionResult = graphql.execute(executionInput);
46+
47+
ProfilerResult profilerResult = executionInput.getGraphQLContext().get(ProfilerResult.PROFILER_CONTEXT_KEY);
48+
49+
if (profilerResult != null) {
50+
Map<String, Object> summary = profilerResult.shortSummaryMap();
51+
System.out.println(summary); // or log as you prefer
52+
}
53+
```
54+
55+
## Understanding the Profiler Results
56+
57+
A great way to get a quick overview about `ProfilerResult` is by using the `shortSummaryMap()` method. It returns a map with key metrics about the execution, which you can use for logging. Let's break down what each key means.
58+
59+
### The ProfilerResult Short Summary Map
60+
61+
Here's a detailed explanation of the fields you'll find in the map returned by `shortSummaryMap()`:
62+
63+
| Key | Type | Description |
64+
| ------------------------------------- | ----------- |------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
65+
| `executionId` | `String` | The unique ID for this GraphQL execution. |
66+
| `operationName` | `String` | The name of the operation, if one was provided in the query (e.g., `query MyQuery { ... }`). |
67+
| `operationType` | `String` | The type of operation, such as `QUERY`, `MUTATION`, or `SUBSCRIPTION`. |
68+
| `startTimeNs` | `long` | The system time in nanoseconds when the execution started. |
69+
| `endTimeNs` | `long` | The system time in nanoseconds when the execution finished. |
70+
| `totalRunTimeNs` | `long` | The total wall-clock time of the execution (`endTimeNs - startTimeNs`). This includes time spent waiting for asynchronous operations like database calls or external API requests within your DataFetchers. |
71+
| `engineTotalRunningTimeNs` | `long` | The total time the GraphQL engine spent actively running on a thread. This is like the "CPU time" of the execution and excludes time spent waiting for `CompletableFuture`s to complete. Comparing this with `totalRunTimeNs` can give you a good idea of how much time is spent on I/O. |
72+
| `totalDataFetcherInvocations` | `int` | The total number of times any DataFetcher was invoked. |
73+
| `totalCustomDataFetcherInvocations` | `int` | The number of invocations for DataFetchers you've written yourself (i.e., not the built-in `PropertyDataFetcher`). |
74+
| `totalTrivialDataFetcherInvocations` | `int` | The number of invocations for the built-in `PropertyDataFetcher`. |
75+
| `totalWrappedTrivialDataFetcherInvocations` | `int` | The number of invocations for DataFetchers that wrap a `PropertyDataFetcher`. |
76+
| `fieldsFetchedCount` | `int` | The number of unique fields fetched during the execution. |
77+
| `dataLoaderChainingEnabled` | `boolean` | `true` if the experimental Dataloader chaining feature was enabled for this execution. |
78+
| `dataLoaderLoadInvocations` | `Map` | A map where keys are Dataloader names and values are the number of times `load()` was called on them. Note that this counts all `load()` calls, including those that hit the Dataloader cache. |
79+
| `oldStrategyDispatchingAll` | `Set` | If Chained DataLoaders are not used, the older dispatching strategy is used instead. This key lists the levels where DataLoaders were dispatched. |
80+
| `dispatchEvents` | `List<Map>` | A list of events, one for each time a Dataloader was dispatched. See below for details. |
81+
| `instrumentationClasses` | `List<String>` | A list of the class names of the `Instrumentation`s used during this execution. |
82+
| `dataFetcherResultTypes` | `Map` | A summary of the types of values returned by your custom DataFetchers. See below for details. |
83+
84+
#### `dispatchEvents`
85+
86+
This is a list of maps, each detailing a `DataLoader` dispatch event.
87+
88+
| Key | Type | Description |
89+
| -------------- | -------- | -------------------------------------------------------------------- |
90+
| `type` | `String` | The type of dispatch. Can be `LEVEL_STRATEGY_DISPATCH`, `CHAINED_STRATEGY_DISPATCH`, `DELAYED_DISPATCH`, `CHAINED_DELAYED_DISPATCH`, or `MANUAL_DISPATCH`. |
91+
| `dataLoader` | `String` | The name of the `DataLoader` that was dispatched. |
92+
| `level` | `int` | The execution strategy level at which the dispatch occurred. |
93+
| `keyCount` | `int` | The number of keys that were dispatched in this batch. |
94+
95+
#### `dataFetcherResultTypes`
96+
97+
This map gives you more information into the type of your DataFetchers' return values.
98+
99+
The keys are `COMPLETABLE_FUTURE_COMPLETED`, `COMPLETABLE_FUTURE_NOT_COMPLETED`, and `MATERIALIZED`.
100+
Each key maps to another map with two keys:
101+
* `count`: The number of unique fields with DataFetchers that returned this result type.
102+
* `invocations`: The total number of invocations across all fields that returned this result type.
103+
104+
Here's what the result types mean:
105+
106+
| Result Type | Meaning |
107+
| ---------------------------------- | --------------------------------------------------------------------------------------------- |
108+
| `COMPLETABLE_FUTURE_COMPLETED` | The DataFetcher returned a `CompletableFuture` that was already completed when it was returned. |
109+
| `COMPLETABLE_FUTURE_NOT_COMPLETED` | The DataFetcher returned an incomplete `CompletableFuture`. |
110+
| `MATERIALIZED` | The DataFetcher returned a simple value (i.e., not a `CompletableFuture`). |
111+
112+
### A note on engine timing statistics logged from an `Instrumentation`
113+
114+
If you're logging the `ProfilerResult` from an `Instrumentation`, note that engine timing statistics such as `startTimeNs`, `endTimeNs`, `totalRunTimeNs`, `engineTotalRunningTimeNs` will be set to `0`. This is because the timing is set after all `Instrumentation`s have run, so it is not available from within an `Instrumentation`.
115+
116+
Apart from engine timing information, all other `ProfilerResult` information is still valid if accessed from within an `Instrumentation`.

‎versioned_docs/version-v24/getting-started.mdx

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@ repositories {
2525
}
2626
2727
dependencies {
28-
implementation 'com.graphql-java:graphql-java:24.1'
28+
implementation 'com.graphql-java:graphql-java:24.2'
2929
}
3030
```
3131
</TabItem>
@@ -38,7 +38,7 @@ repositories {
3838
}
3939

4040
dependencies {
41-
implementation("com.graphql-java:graphql-java:24.1")
41+
implementation("com.graphql-java:graphql-java:24.2")
4242
}
4343
```
4444
</TabItem>
@@ -51,7 +51,7 @@ Dependency:
5151
<dependency>
5252
<groupId>com.graphql-java</groupId>
5353
<artifactId>graphql-java</artifactId>
54-
<version>24.1</version>
54+
<version>24.2</version>
5555
</dependency>
5656
```
5757

0 commit comments

Comments
 (0)