Package graphql.schema

Class GraphQLSchema

java.lang.Object
graphql.schema.GraphQLSchema
@PublicApi @NullMarked public class GraphQLSchema extends Object
The schema represents the combined type system of the graphql engine. This is how the engine knows what graphql queries represent what data.

See https://graphql.org/learn/schema/#type-language for more details

  • Constructor Details

  • Method Details

    • getCodeRegistry

      public GraphQLCodeRegistry getCodeRegistry()

    • getIntrospectionSchemaFieldDefinition

      public GraphQLFieldDefinition getIntrospectionSchemaFieldDefinition()
      Returns:
      the special system field called "__schema"

    • getIntrospectionTypeFieldDefinition

      public GraphQLFieldDefinition getIntrospectionTypeFieldDefinition()
      Returns:
      the special system field called "__type"

    • getIntrospectionTypenameFieldDefinition

      public GraphQLFieldDefinition getIntrospectionTypenameFieldDefinition()
      Returns:
      the special system field called "__typename"

    • getIntrospectionSchemaType

      public GraphQLObjectType getIntrospectionSchemaType()

    • getAdditionalTypes

      public Set<GraphQLNamedType> getAdditionalTypes()
      Returns the set of "additional types" that were provided when building the schema.

      During schema construction, types are discovered by traversing the schema from multiple roots:

      Additional types are types that are not reachable via any of the automatic traversal paths but still need to be part of the schema. The most common use case is for interface implementations that are not directly referenced elsewhere.

      Types that do NOT need to be added as additional types:

      • Types reachable from Query, Mutation, or Subscription fields
      • Types used as directive arguments (these are discovered via directive traversal)

      When additional types ARE typically needed:

      • Interface implementations: When an interface is used as a field's return type, implementing object types are not automatically discovered because interfaces do not reference their implementors. These need to be added so they can be resolved at runtime and appear in introspection.
      • SDL-defined schemas: When building from SDL, the SchemaGenerator automatically detects types not connected to any root and adds them as additional types.
      • Programmatic schemas with type references: When using GraphQLTypeReference to break circular dependencies, the actual type implementations may need to be provided as additional types.

      Example - Interface implementation not directly referenced: 

      
 // Given this schema:
 // type Query { node: Node }
 // interface Node { id: ID! }
 // type User implements Node { id: ID!, name: String }
 //
 // User is not directly referenced from Query, so it needs to be added:
 GraphQLSchema.newSchema()
     .query(queryType)
     .additionalType(GraphQLObjectType.newObject().name("User")...)
     .build();

      Note: There are no restrictions on what types can be added via this mechanism. Types that are already reachable from other roots can also be added without causing errors - they will simply be present in both the type map (via traversal) and this set. After schema construction, use getTypeMap() or getAllTypesAsList() to get all types in the schema regardless of how they were discovered.

      Note on FastBuilder: When a schema is constructed using GraphQLSchema.FastBuilder, this method returns ALL types in the schema except the root operation types (Query, Mutation, Subscription). This differs from schemas built with the standard GraphQLSchema.Builder, which returns only types not reachable from the root types. This semantic difference does not affect schema traversal or correctness, as both approaches ensure all types are properly discoverable.

      Returns:
      an immutable set of types that were explicitly added as additional types
      See Also:

    • getType

      public @Nullable GraphQLType getType(String typeName)
      Gets the named type from the schema or null if it's not present
      Parameters:
      typeName - the name of the type to retrieve
      Returns:
      the type

    • getTypes

      public <T extends GraphQLType> List<T> getTypes(Collection<String> typeNames)
      All types with the provided names. throws AssertException when a type name could not be resolved
      Type Parameters:
      T - for two
      Parameters:
      typeNames - the type names to get
      Returns:
      The List of resolved types.

    • getTypeAs

      public <T extends GraphQLType> @Nullable T getTypeAs(String typeName)
      Gets the named type from the schema or null if it's not present.

      Warning - you are inviting class cast errors if the types are not what you expect.

      Type Parameters:
      T - for two
      Parameters:
      typeName - the name of the type to retrieve
      Returns:
      the type cast to the target type.

    • containsType

      public boolean containsType(String typeName)
      Returns true if the schema contains a type with the specified name
      Parameters:
      typeName - the name of the type to check
      Returns:
      true if there is a type with the specified name

    • getObjectType

      public @Nullable GraphQLObjectType getObjectType(String typeName)
      Called to return a named GraphQLObjectType from the schema
      Parameters:
      typeName - the name of the type
      Returns:
      a graphql object type or null if there is one
      Throws:
      GraphQLException - if the type is NOT an object type

    • getFieldDefinition

      public @Nullable GraphQLFieldDefinition getFieldDefinition(FieldCoordinates fieldCoordinates)
      Returns a GraphQLFieldDefinition as the specified co-ordinates or null if it does not exist
      Parameters:
      fieldCoordinates - the field co-ordinates
      Returns:
      the field or null if it does not exist

    • getTypeMap

      public Map<String,GraphQLNamedType> getTypeMap()
      Returns:
      all the named types in the scheme as a map from name to named type

    • getAllTypesAsList

      public List<GraphQLNamedType> getAllTypesAsList()
      This returns all the GraphQLNamedType named types in th schema
      Returns:
      all the GraphQLNamedType types in the schema

    • getAllElementsAsList

      public List<GraphQLNamedSchemaElement> getAllElementsAsList()
      This returns all the top level GraphQLNamedSchemaElement named types and directives in the schema
      Returns:
      all the top level GraphQLNamedSchemaElement types and directives in the schema

    • getImplementations

      public @Nullable List<GraphQLObjectType> getImplementations(GraphQLInterfaceType type)
      This will return the list of GraphQLObjectType types that implement the given interface type.
      Parameters:
      type - interface type to obtain implementations of.
      Returns:
      list of types implementing provided interface

    • isPossibleType

      public boolean isPossibleType(GraphQLNamedType abstractType, GraphQLObjectType concreteType)
      Returns true if a specified concrete type is a possible type of a provided abstract type. If the provided abstract type is: - an interface, it checks whether the concrete type is one of its implementations. - a union, it checks whether the concrete type is one of its possible types.
      Parameters:
      abstractType - abstract type either interface or union
      concreteType - concrete type
      Returns:
      true if possible type, false otherwise.

    • getQueryType

      public GraphQLObjectType getQueryType()
      Returns:
      the Query type of the schema

    • getMutationType

      public @Nullable GraphQLObjectType getMutationType()
      Returns:
      the Mutation type of the schema of null if there is not one

    • getSubscriptionType

      public @Nullable GraphQLObjectType getSubscriptionType()
      Returns:
      the Subscription type of the schema of null if there is not one

    • getDirectives

      public List<GraphQLDirective> getDirectives()
      This returns the list of directives definitions that are associated with this schema object including built in ones.
      Returns:
      a list of directives

    • getDirectivesByName

      public Map<String,GraphQLDirective> getDirectivesByName()
      Returns:
      a map of non-repeatable directives by directive name

    • getDirective

      public @Nullable GraphQLDirective getDirective(String directiveName)
      Returns a named directive that (for legacy reasons) will be only in the set of non-repeatable directives
      Parameters:
      directiveName - the name of the directive to retrieve
      Returns:
      the directive or null if there is not one with that name

    • getSchemaDirectives

      @Deprecated(since="2022-02-24") public List<GraphQLDirective> getSchemaDirectives()
      Deprecated.
      Use the GraphQLAppliedDirective methods instead
      This returns the list of directives that have been explicitly applied to the schema object. Note that getDirectives() will return directives for all schema elements, whereas this is just for the schema element itself
      Returns:
      a list of directives

    • getSchemaDirectiveByName

      @Deprecated(since="2022-02-24") public Map<String,GraphQLDirective> getSchemaDirectiveByName()
      Deprecated.
      Use the GraphQLAppliedDirective methods instead
      This returns a map of non-repeatable directives that have been explicitly applied to the schema object. Note that getDirectives() will return directives for all schema elements, whereas this is just for the schema element itself
      Returns:
      a map of directives

    • getAllSchemaDirectivesByName

      @Deprecated(since="2022-02-24") public Map<String,List<GraphQLDirective>> getAllSchemaDirectivesByName()
      Deprecated.
      Use the GraphQLAppliedDirective methods instead
      This returns a map of non-repeatable and repeatable directives that have been explicitly applied to the schema object. Note that getDirectives() will return directives for all schema elements, whereas this is just for the schema element itself
      Returns:
      a map of directives

    • getSchemaDirective

      @Deprecated(since="2022-02-24") public GraphQLDirective getSchemaDirective(String directiveName)
      Deprecated.
      Use the GraphQLAppliedDirective methods instead
      This returns the named directive that have been explicitly applied to the schema object. Note that GraphQLDirectiveContainer.getDirective(String) will return directives for all schema elements, whereas this is just for the schema element itself
      Parameters:
      directiveName - the name of the directive
      Returns:
      a named directive

    • getSchemaDirectives

      @Deprecated(since="2022-02-24") public List<GraphQLDirective> getSchemaDirectives(String directiveName)
      Deprecated.
      Use the GraphQLAppliedDirective methods instead
      This returns the named directives that have been explicitly applied to the schema object.
      Parameters:
      directiveName - the name of the directive
      Returns:
      A list of repeated applied directives

    • getSchemaAppliedDirectives

      public List<GraphQLAppliedDirective> getSchemaAppliedDirectives()
      This returns the list of directives that have been explicitly applied to the schema object. Note that getDirectives() will return directives for all schema elements, whereas this is just for the schema element itself
      Returns:
      a list of directives

    • getAllSchemaAppliedDirectivesByName

      public Map<String,List<GraphQLAppliedDirective>> getAllSchemaAppliedDirectivesByName()
      This returns a map of non-repeatable and repeatable directives that have been explicitly applied to the schema object. Note that getDirectives() will return directives for all schema elements, whereas this is just for the schema element itself
      Returns:
      a map of all schema directives by directive name

    • getSchemaAppliedDirective

      public GraphQLAppliedDirective getSchemaAppliedDirective(String directiveName)
      This returns the named directive that have been explicitly applied to the schema object. Note that GraphQLDirectiveContainer.getDirective(String) will return directives for all schema elements, whereas this is just for the schema element itself
      Parameters:
      directiveName - the name of the directive
      Returns:
      a named directive

    • getSchemaAppliedDirectives

      public List<GraphQLAppliedDirective> getSchemaAppliedDirectives(String directiveName)

    • getDefinition

      public @Nullable SchemaDefinition getDefinition()

    • getExtensionDefinitions

      public List<SchemaExtensionDefinition> getExtensionDefinitions()

    • isSupportingMutations

      public boolean isSupportingMutations()

    • isSupportingSubscriptions

      public boolean isSupportingSubscriptions()

    • getDescription

      public @Nullable String getDescription()

    • transform

      public GraphQLSchema transform(Consumer<GraphQLSchema.Builder> builderConsumer)
      This helps you transform the current GraphQLSchema object into another one by starting a builder with all the current values and allows you to transform it how you want.
      Parameters:
      builderConsumer - the consumer code that will be given a builder to transform
      Returns:
      a new GraphQLSchema object based on calling built on that builder

    • transformWithoutTypes

      public GraphQLSchema transformWithoutTypes(Consumer<GraphQLSchema.BuilderWithoutTypes> builderConsumer)
      This helps you transform the current GraphQLSchema object into another one by using a builder that only allows you to change simple values and does not involve changing the complex schema type graph.
      Parameters:
      builderConsumer - the consumer code that will be given a builder to transform
      Returns:
      a new GraphQLSchema object based on calling built on that builder

    • newSchema

      public static GraphQLSchema.Builder newSchema()
      Returns:
      a new schema builder

    • newSchema

      public static GraphQLSchema.Builder newSchema(GraphQLSchema existingSchema)
      This allows you to build a schema from an existing schema. It copies everything from the existing schema and then allows you to replace them.
      Parameters:
      existingSchema - the existing schema
      Returns:
      a new schema builder