Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
231 changes: 231 additions & 0 deletions docs/normalized-document.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,231 @@
# NormalizedDocument and lookahead

`NormalizedDocument` is an immutable selection graph built during document
validation. It describes every operation and retains shared fragment bodies,
source locations, aliases, argument AST values, directives and type conditions.
It contains no execution variables, resolved arguments or mutable parent pointers.

## Enabling creation

Creation is **off by default**. Enable it before validation for requests whose
data fetchers or type resolvers use lookahead:

```java
ExecutionInput input = ExecutionInput.newExecutionInput(query)
.graphQLContext(Map.of(NormalizedDocument.ENABLED, true))
.build();
ExecutionResult result = graphQL.execute(input);
```

The same option works with `ParseAndValidate.parseAndValidate(schema, input)`.
`ParseAndValidateResult.getNormalizedDocument()` returns the graph after
successful validation, or null when creation is disabled or validation fails.
`ExecutionContext.getNormalizedDocument()` exposes it during execution.

Calling a lookahead inspection method (`getFields`, `getImmediateFields`,
`contains`, or their variants) without this option and artifact throws
`IllegalStateException`. This also applies to scalar fields and empty patterns.
Merely obtaining `DataFetchingEnvironment.getSelectionSet()` does not throw.
There is no lazy construction or revalidation fallback. As with other data
fetcher exceptions, the normal execution exception handler can turn this into a
field error; type resolver exceptions follow the existing execution error path.

## Stored graph

`getOperations()` contains operations in source order. Each operation has a root
selection set ID. IDs index `getSelectionSets()`. Each selection set contains
ordered `NormalizedField` and `NormalizedSelectionScope` entries:

- A field retains its original AST node and declared parent type. Its child ID
is `-1` for a leaf.
- A scope retains an inline fragment or fragment spread, its type condition and
its target selection set ID. Named scopes also retain the fragment definition.
- A named fragment body is stored once. Conditions belong to each reference,
and remain symbolic AST expressions. No combinations of variable values are
enumerated.

For example:

```graphql
query($a: Boolean!, $b: Boolean!) {
box { ...Details @include(if: $a) ...Details @include(if: $b) }
}
fragment Details on Box { name }
```

The `box` selection set has **two scopes referencing one shared body**. That
body stores **one field**. Expanding both spreads would produce two logical
occurrences, but does not allocate two stored fields. During lookahead the two
active contributions collect into one `name` entry. If both conditions are
false, there is no entry. Nested scope conditions all have to hold.

Validation records fields using its existing resolved parent types. It does not
coerce arguments or construct execution trees. A final pass freezes the recorded
selection sets and their direct references. Validation's merge checks and query
complexity limits continue to use their existing semantics.

## Collection and behavior changes

Lookahead evaluates `@skip`, `@include` and custom `ConditionalNodeDecision`
callbacks for the current execution. It collects immediate fields by **concrete
parent object type and response key** (alias, or field name). Children are
collected when requested. `getFields()` traverses those child views in preorder.

### Separate concrete types

Given a `Pet` interface implemented by `Cat` and `Dog`:

```graphql
{ pet { name } }
```

Previously identical selections could become one entry with object types
`[Cat, Dog]`. Now `getImmediateFields()` returns two entries, `Cat.name` and
`Dog.name`. Each has one object type and one field definition. Their result key
is `name`; `getFieldsGroupedByResultKey().get("name")` contains both. Do not use
that group's size as the number of fields in one concrete response object.

### Aliases on mutually exclusive types

```graphql
{
pet {
... on Cat { label: name }
... on Dog { label: nickname }
}
}
```

There are two entries: `Cat.name` and `Dog.nickname`, both with result key
`label`. They may have different arguments and field definitions. Result-key
grouping alone does not imply identical arguments across concrete types.

### Combining children one level at a time

```graphql
{
pet {
... on Cat { child { name } child { lives } }
... on Dog { child { nickname } }
}
}
```

Immediate lookahead returns `Cat.child` and `Dog.child`. The two active Cat
occurrences contribute to one Cat child view; inspecting it returns `name` and
`lives`. The Dog view contains `nickname`. Identical trees on different parent
types are no longer recursively merged together.

### Ordering, paths and conditions

Concrete types are visited in type-name order. Within each type, fields retain
first-active-occurrence order. Thus a source ordering of Dog then Cat still
returns the Cat group first. Aliases distinguish entries but field paths keep
using schema field names: `child/name` and `Cat.child/Cat.name`.

Immediate fields have no parent within the data fetcher's lookahead view.
Descendants point to their parent in that view. A selected field's own
`getSelectionSet()` uses relative paths again. Levels remain absolute field
levels in the operation, excluding list indices.

`isConditional()` means this entry belongs to one of several possible parent
object types at its level. In `{ pet { name } }`, both entries are conditional,
even though every Pet type provides `name`. Variable conditions have already
been evaluated; an included field on a concrete object is not marked conditional
just because it had `@include`.

Arguments are resolved only when `SelectedField.getArguments()` is called,
using the concrete field definition, execution variables, context and locale.
Defaults can therefore differ between concrete implementations. They are never
stored in the cached document. Source `@defer` directives remain accessible in
the graph; lookahead includes their selected fields but does not expose a
separate normalized deferred-execution model.

## Preparsed caches

Cache and return the **whole entry** produced by the supplied parse/validate
function. Custom preparation can also use:

```java
ParseAndValidateResult prepared = ParseAndValidate.parseAndValidate(schema, input);
// Handle syntax failure separately: its document is null.
PreparsedDocumentEntry entry = new PreparsedDocumentEntry(
prepared.getDocument(), prepared.getErrors(), prepared.getNormalizedDocument());
```

The graph and AST must be the same objects produced by validation. The entry
checks this association and requires an error-free document when a graph is
supplied. The graph is serializable with the entry, under the entry's existing
same-version serialization contract.

Cache keys must distinguish the schema/version and any validation options that
change the cached result, including `NormalizedDocument.ENABLED`. A cached
AST-only entry will not gain a graph when reused by an enabled request.
Invalidate or repopulate existing caches when enabling creation. A graph
can be shared across requests with different variables; collected fields and
resolved arguments belong to each execution. AST-transforming instrumentation
must retain or regenerate the corresponding validation result.

## Removed APIs and migration

This removes `ExecutableNormalizedField`, `ExecutableNormalizedOperation`,
`ExecutableNormalizedOperationFactory`, `ExecutionContext.getNormalizedQueryTree()`,
`ExecutionStrategy.getNormalizedField()`,
the old `graphql.normalized.nf` package, and
`graphql.normalized.incremental.NormalizedDeferredExecution`. It also removes `ExecutableNormalizedOperationToAstCompiler`, the
old normalized-operation compiler and `VariablePredicate` **without replacement**.

Use the opt-in validated graph for static inspection and the selection-set API
for execution lookahead. Custom execution strategies must remove overrides or
calls to the removed normalized-field hook. Update assumptions about type grouping, result counts,
ordering, conditional flags and parents as illustrated above. Consumers that
need to compile normalized operations back to AST must supply that capability
outside this API. `NormalizedInputValue`, variable normalization and execution
query-directive APIs remain available independently of document creation.

For resource protection, continue to use parser limits and
`QueryComplexityLimits` during validation. `NormalizedDocument.getFields().size()`
counts stored AST fields, not expanded occurrences or merged execution fields.

## Bounded lookahead enumeration

The stored graph stays shared, but flat lookahead expands concrete-type paths.
To bound this expansion, each enumeration uses the configured
`QueryComplexityLimits.maxFieldOccurrences` (initial default: 100,000).
Request-specific limits override the current JVM defaults. Each selection-set
view captures its limit when created. `QueryComplexityLimits.NONE`, or setting
`maxFieldOccurrences(Integer.MAX_VALUE)`, disables this bound.

Validation and lookahead use the same threshold for **different counts**:

- Validation counts AST field occurrences after fragment expansion, without
merging duplicates or expanding possible runtime types.
- Lookahead counts collected fields at every concrete-type path. Active
selections with the same concrete parent type and response key merge into one
entry at that position. The field whose selection set is inspected is excluded.

For example, suppose `Node` has two implementations, `A` and `B`, and both expose
`next: Node` and `value: String`:

```graphql
{ node { next { next { value } } } }
```

Validation counts **4** occurrences: `node`, two `next` fields, and `value`.
The `node` data fetcher's full lookahead counts **14**: 2 immediate `next`
entries, 4 second-level `next` entries, and 8 `value` entries. A limit of 13
therefore permits validation but rejects full lookahead. With further nested
`next` selections, the AST grows linearly while concrete paths grow exponentially.

`getImmediateFields()` bounds only its immediate entries. `getFields()`, glob
matching (`getFields(pattern)`, `contains` and their variants), and result-key
grouping bound the full enumeration. Non-matching entries still count because
enumeration precedes filtering. Inspecting a selected field's own selection set
starts a separate count relative to that field; counts are not cumulative across
calls or data fetchers.

Exceeding the limit throws `IllegalStateException` identifying
`QueryComplexityLimits.maxFieldOccurrences` and the configured limit; results
are never truncated. The check occurs before constructing each selected-field
entry. Previously cached child lists still count toward the total, and concurrent
enumerations use separate counters. Successful complete results remain cached.
119 changes: 38 additions & 81 deletions src/jmh/java/performance/DFSelectionSetPerformance.java
Original file line number Diff line number Diff line change
@@ -1,11 +1,13 @@
package performance;

import graphql.execution.CoercedVariables;
import graphql.language.Document;
import graphql.normalized.ExecutableNormalizedField;
import graphql.normalized.ExecutableNormalizedOperation;
import graphql.normalized.ExecutableNormalizedOperationFactory;
import graphql.parser.Parser;
import graphql.ExecutionInput;
import graphql.ParseAndValidate;
import graphql.ParseAndValidateResult;
import graphql.execution.ExecutionContext;
import graphql.execution.ExecutionContextBuilder;
import graphql.execution.MergedField;
import graphql.language.Field;
import graphql.normalized.NormalizedDocument;
import graphql.schema.DataFetchingFieldSelectionSet;
import graphql.schema.DataFetchingFieldSelectionSetImpl;
import graphql.schema.GraphQLOutputType;
Expand All @@ -22,97 +24,52 @@
import org.openjdk.jmh.annotations.Setup;
import org.openjdk.jmh.annotations.State;
import org.openjdk.jmh.annotations.Warmup;
import org.openjdk.jmh.infra.Blackhole;

import java.util.List;
import java.util.Map;
import java.util.concurrent.TimeUnit;

import static graphql.Assert.assertNotNull;
import static graphql.Assert.assertTrue;

@State(Scope.Benchmark)
@Warmup(iterations = 2, time = 5)
@Measurement(iterations = 3)
@Fork(2)
@BenchmarkMode(Mode.AverageTime)
@OutputTimeUnit(TimeUnit.MILLISECONDS)
public class DFSelectionSetPerformance {

@State(Scope.Benchmark)
public static class MyState {

public ExecutableNormalizedField normalisedField;
public GraphQLOutputType outputFieldType;
GraphQLSchema schema;
Document document;

@Setup
public void setup() {
try {
String schemaString = PerformanceTestingUtils.loadResource("large-schema-2.graphqls");
schema = SchemaGenerator.createdMockedSchema(schemaString);

String query = PerformanceTestingUtils.loadResource("large-schema-2-query.graphql");
document = Parser.parse(query);

ExecutableNormalizedOperation executableNormalizedOperation = ExecutableNormalizedOperationFactory.createExecutableNormalizedOperation(schema, document, null, CoercedVariables.emptyVariables());

normalisedField = executableNormalizedOperation.getTopLevelFields().get(0);

outputFieldType = schema.getObjectType("Object42");

} catch (Exception e) {
throw new RuntimeException(e);
}
}

}

@Benchmark
@BenchmarkMode(Mode.AverageTime)
@OutputTimeUnit(TimeUnit.MILLISECONDS)
public void benchMarkAvgTime(MyState myState, Blackhole blackhole) {
List<SelectedField> fields = getSelectedFields(myState);
blackhole.consume(fields);
}

@Benchmark
@BenchmarkMode(Mode.Throughput)
@OutputTimeUnit(TimeUnit.MILLISECONDS)
public void benchMarkThroughput(MyState myState, Blackhole blackhole) {
List<SelectedField> fields = getSelectedFields(myState);
blackhole.consume(fields);
private ExecutionContext context;
private MergedField field;
private GraphQLOutputType fieldType;

@Setup
public void setup() throws Exception {
GraphQLSchema schema = SchemaGenerator.createdMockedSchema(PerformanceTestingUtils.loadResource("large-schema-2.graphqls"));
ExecutionInput input = ExecutionInput.newExecutionInput(PerformanceTestingUtils.loadResource("large-schema-2-query.graphql"))
.graphQLContext(Map.of(NormalizedDocument.ENABLED, true)).build();
ParseAndValidateResult result = ParseAndValidate.parseAndValidate(schema, input);
assertTrue(!result.isFailure(), () -> result.getErrors().toString());
NormalizedDocument document = assertNotNull(result.getNormalizedDocument());
Field root = (Field) document.getOperations().get(0).getSource().getSelectionSet().getSelections().get(0);
field = MergedField.newMergedField(root).build();
fieldType = assertNotNull(schema.getQueryType().getFieldDefinition(root.getName())).getType();
context = ExecutionContextBuilder.newExecutionContextBuilder().executionId(graphql.execution.ExecutionId.generate()).graphQLSchema(schema)
.graphQLContext(input.getGraphQLContext()).locale(input.getLocale())
.document(result.getDocument()).normalizedDocument(document).build();
}

@Benchmark
@BenchmarkMode(Mode.AverageTime)
@OutputTimeUnit(TimeUnit.MILLISECONDS)
public void benchMarkAvgTime_getImmediateFields(MyState myState, Blackhole blackhole) {
List<SelectedField> fields = getImmediateFields(myState);
blackhole.consume(fields);
public List<SelectedField> benchMarkAvgTime() {
return collector().getFields("wontBeFound");
}

@Benchmark
@BenchmarkMode(Mode.Throughput)
@OutputTimeUnit(TimeUnit.MILLISECONDS)
public void benchMarkThroughput_getImmediateFields(MyState myState, Blackhole blackhole) {
List<SelectedField> fields = getImmediateFields(myState);
blackhole.consume(fields);
public List<SelectedField> benchMarkAvgTime_getImmediateFields() {
return collector().getImmediateFields();
}

private List<SelectedField> getSelectedFields(MyState myState) {
DataFetchingFieldSelectionSet dataFetchingFieldSelectionSet = DataFetchingFieldSelectionSetImpl.newCollector(myState.schema, myState.outputFieldType, () -> myState.normalisedField);
return dataFetchingFieldSelectionSet.getFields("wontBeFound");
private DataFetchingFieldSelectionSet collector() {
return DataFetchingFieldSelectionSetImpl.newCollector(context, field, fieldType, 1);
}

private List<SelectedField> getImmediateFields(MyState myState) {
DataFetchingFieldSelectionSet dataFetchingFieldSelectionSet = DataFetchingFieldSelectionSetImpl.newCollector(myState.schema, myState.outputFieldType, () -> myState.normalisedField);
return dataFetchingFieldSelectionSet.getImmediateFields();
}

public static void mainX(String[] args) throws InterruptedException {
MyState myState = new MyState();
myState.setup();

while (true) {
List<SelectedField> selectedFields = new DFSelectionSetPerformance().getSelectedFields(myState);
Thread.sleep(500);
}
}

}
Loading
Loading