Package graphql.schema

Class GraphQLSchema.FastBuilder

java.lang.Object
graphql.schema.GraphQLSchema.FastBuilder
Enclosing class:
GraphQLSchema
@ExperimentalApi @NullMarked public static final class GraphQLSchema.FastBuilder extends Object
A high-performance schema builder that avoids full-schema traversals performed by GraphQLSchema.Builder.build(). This builder is significantly faster (5x+) and allocates significantly less memory than the standard Builder. It is intended for constructing large schemas (500+ types), especially deeply nested ones.

When to use FastBuilder

When NOT to use FastBuilder

  • Type discovery required: If you rely on automatic type discovery by traversing from root types (Query/Mutation/Subscription), use the standard GraphQLSchema.Builder instead. FastBuilder requires ALL types to be explicitly added.
  • Type reuse across schemas: FastBuilder mutates type objects during build() to resolve GraphQLTypeReferences. The same type instances cannot be used to build multiple schemas. Create fresh type instances for each schema if needed.
  • Dynamic schema construction: FastBuilder does not support clearing or resetting state. Each FastBuilder instance should be used exactly once.
  • Schema transformation: For transforming existing schemas, use GraphQLSchema.transform(Consumer) or GraphQLSchema.Builder instead.

Key differences from standard Builder

  • No automatic type discovery: You must add ALL types explicitly, including interface implementations that would normally be discovered via traversal.
  • Type mutation: GraphQLTypeReference instances in added types are replaced in-place with actual types during build. This mutates the original type objects.
  • additionalTypes semantic: GraphQLSchema.getAdditionalTypes() returns ALL non-root types (not just "detached" types as with standard Builder).
  • Validation off by default: Enable with withValidation(boolean) if needed.

Example usage


 GraphQLObjectType queryType = ...;
 GraphQLObjectType mutationType = ...;
 Set<GraphQLNamedType> allTypes = ...;  // All types including interface implementations
 Set<GraphQLDirective> directives = ...;

 GraphQLSchema schema = new GraphQLSchema.FastBuilder(
         GraphQLCodeRegistry.newCodeRegistry(),
         queryType,
         mutationType,
         null)  // no subscription
     .addTypes(allTypes)
     .additionalDirectives(directives)
     .withValidation(true)  // optional, off by default
     .build();
See Also:

  • Constructor Details

    • FastBuilder

      public FastBuilder(GraphQLCodeRegistry.Builder codeRegistryBuilder, GraphQLObjectType queryType, @Nullable GraphQLObjectType mutationType, @Nullable GraphQLObjectType subscriptionType)
      Creates a new FastBuilder with the given code registry builder and root types.
      Parameters:
      codeRegistryBuilder - the code registry builder (required)
      queryType - the query type (required)
      mutationType - the mutation type (optional, may be null)
      subscriptionType - the subscription type (optional, may be null)

  • Method Details

    • addType

      public GraphQLSchema.FastBuilder addType(GraphQLNamedType type)
      Adds a named type to the schema. All non-root types added via this method will be included in GraphQLSchema.getAdditionalTypes().

      Warning: The type object will be mutated during build() if it contains GraphQLTypeReference instances. Do not reuse the same type instance across multiple FastBuilder instances.

      Parameters:
      type - the named type to add
      Returns:
      this builder for chaining

    • addTypes

      public GraphQLSchema.FastBuilder addTypes(Collection<? extends GraphQLNamedType> types)
      Adds multiple named types to the schema. All non-root types added via this method will be included in GraphQLSchema.getAdditionalTypes().
      Parameters:
      types - the named types to add
      Returns:
      this builder for chaining

    • additionalDirective

      public GraphQLSchema.FastBuilder additionalDirective(GraphQLDirective directive)
      Adds a directive definition to the schema.
      Parameters:
      directive - the directive to add
      Returns:
      this builder for chaining

    • additionalDirectives

      public GraphQLSchema.FastBuilder additionalDirectives(Collection<? extends GraphQLDirective> directives)
      Adds multiple directive definitions to the schema.
      Parameters:
      directives - the directives to add
      Returns:
      this builder for chaining

    • withSchemaDirective

      public GraphQLSchema.FastBuilder withSchemaDirective(GraphQLDirective directive)
      Adds a schema-level directive (deprecated, use applied directives).
      Parameters:
      directive - the directive to add
      Returns:
      this builder for chaining

    • withSchemaDirectives

      public GraphQLSchema.FastBuilder withSchemaDirectives(Collection<? extends GraphQLDirective> directives)
      Adds multiple schema-level directives.
      Parameters:
      directives - the directives to add
      Returns:
      this builder for chaining

    • withSchemaAppliedDirective

      public GraphQLSchema.FastBuilder withSchemaAppliedDirective(GraphQLAppliedDirective applied)
      Adds a schema-level applied directive.
      Parameters:
      applied - the applied directive to add
      Returns:
      this builder for chaining

    • withSchemaAppliedDirectives

      public GraphQLSchema.FastBuilder withSchemaAppliedDirectives(Collection<? extends GraphQLAppliedDirective> appliedList)
      Adds multiple schema-level applied directives.
      Parameters:
      appliedList - the applied directives to add
      Returns:
      this builder for chaining

    • definition

      public GraphQLSchema.FastBuilder definition(SchemaDefinition def)
      Sets the schema definition (AST).
      Parameters:
      def - the schema definition
      Returns:
      this builder for chaining

    • extensionDefinitions

      public GraphQLSchema.FastBuilder extensionDefinitions(List<SchemaExtensionDefinition> defs)
      Sets the schema extension definitions (AST).
      Parameters:
      defs - the extension definitions
      Returns:
      this builder for chaining

    • description

      public GraphQLSchema.FastBuilder description(String description)
      Sets the schema description.
      Parameters:
      description - the description
      Returns:
      this builder for chaining

    • introspectionSchemaType

      public GraphQLSchema.FastBuilder introspectionSchemaType(GraphQLObjectType type)
      Sets the introspection schema type.
      Parameters:
      type - the introspection schema type
      Returns:
      this builder for chaining

    • withValidation

      public GraphQLSchema.FastBuilder withValidation(boolean enabled)
      Enables or disables schema validation.
      Parameters:
      enabled - true to enable validation, false to disable
      Returns:
      this builder for chaining

    • build

      public GraphQLSchema build()
      Builds the GraphQL schema.

      Warning: This method mutates the type and directive objects that were added to this builder. Any GraphQLTypeReference instances within those objects are replaced in-place with the actual resolved types. After calling this method, the added types should not be reused with another FastBuilder.

      Returns:
      the built schema
      Throws:
      InvalidSchemaException - if validation is enabled and the schema is invalid
      AssertException - if a type reference cannot be resolved or if an interface/union type is missing a type resolver