Documentation

Alternative field name.

{
  smallPic: profilePic(size: 64)
  bigPic: profilePic(size: 1024)
}

Here "smallPic" and "bigPic" are aliases for the same field, "profilePic", used to distinquish between profile pictures with different arguments (sizes).

Single argument.

{
  user(id: 4) {
    name
  }
}

Here "id" is an argument for the field "user" and its value is 4.

A list of values passed to a field.

type Person {
  name: String
  picture(width: Int, height: Int): Url
}

Person has two fields, "name" and "picture". "name" doesn't have any arguments, so ArgumentsDefinition contains an empty list. "picture" contains definitions for 2 arguments: "width" and "height".

Constant input value.

All kinds of definitions that can occur in a GraphQL document.

GraphQL has built-in capability to document service APIs. Documentation is a GraphQL string that precedes a particular definition and contains Markdown. Any GraphQL definition can be documented this way.

"""
Supported languages.
"""
enum Language {
  English
  EN

  Russian
  RU
}

Directive.

Directives begin with "@", can accept arguments, and can be applied to the most GraphQL elements, providing additional information.

GraphQL document.

Single value in an enum definition.

enum Direction {
  NORTH
  EAST
  SOUTH
  WEST
}

"NORTH, EAST, SOUTH, and WEST are value definitions of an enum type definition Direction.

Top-level definition of a document, either an operation or a fragment.

Definition of a single field in a type.

type Person {
  name: String
  picture(width: Int, height: Int): Url
}

"name" and "picture", including their arguments and types, are field definitions.

Fragment definition.

Defines a list of interfaces implemented by the given object type.

type Business implements NamedEntity & ValuedEntity {
  name: String
}

Here the object type Business implements two interfaces: NamedEntity and ValuedEntity.

Defines an input value.

• Input values can define field arguments, see ArgumentsDefinition.
• They can also be used as field definitions in an input type.

input Point2D {
  x: Float
  y: Float
}

The input type Point2D contains two value definitions: "x" and "y".

Error location, line and column.

Name.

Represents type names.

Helper type to represent Non-Null types and lists of such types.

Key-value pair.

A list of ObjectFields represents a GraphQL object type.

Operation definition.

GraphQL has 3 operation types:

• query - a read-only fetch.
• mutation - a write operation followed by a fetch.
• subscription - a long-lived request that fetches data in response to source events.

Root operation type definition.

Defining root operation types is not required since they have defaults. So the default query root type is Query, and the default mutation root type is Mutation. But these defaults can be changed for a specific schema. In the following code the query root type is changed to MyQueryRootType, and the mutation root type to MyMutationRootType:

schema {
  query: MyQueryRootType
  mutation: MyMutationRootType
}

Extension of the schema definition by further operations or directives.

Selection is a single entry in a selection set. It can be a single field, fragment spread or inline fragment.

The only required property of a field is its name. Optionally it can also have an alias, arguments, directives and a list of subfields.

In the following query "user" is a field with two subfields, "id" and "name":

{
  user {
    id
    name
  }
}

A fragment spread refers to a fragment defined outside the operation and is expanded at the execution time.

{
  user {
    ...userFragment
  }
}

fragment userFragment on UserType {
  id
  name
}

Inline fragments are similar but they don't have any name and the type condition ("on UserType") is optional.

{
  user {
    ... on UserType {
      id
      name
    }
}

"Top-level" selection, selection on an operation or fragment.

Field selection.

Type representation.

Type condition.

Type definitions describe various user-defined types.

Extensions for custom, already defined types.

Type system can define a schema, a type or a directive.

schema {
  query: Query
}

directive example on FIELD_DEFINITION

type Query {
  field: String example
}

This example defines a custom directive "@example", which is applied to a field definition of the type definition Query. On the top the schema is defined by taking advantage of the type Query.

Extension for a type system definition. Only schema and type definitions can be extended.

List of types forming a union.

union SearchResult = Person | Photo

Person and Photo are member types of the union SearchResult.

Input value (literal or variable).

Variable definition.

Each operation can include a list of variables:

query (protagonist: String = Zarathustra) {
  getAuthor(protagonist: $protagonist)
}

This query defines an optional variable protagonist of type String, its default value is Zarathustra. If no default value is defined and no value is provided, a variable can still be null if its type is nullable.

Variables are usually passed along with the query, but not in the query itself. They make queries reusable.