# GraphQL Glossary

Some useful terms to know when discussing GraphQL

## Document

Any valid GraphQL Document, typically either defining a [Schema](#Schema), or defining (one or more)
[Operations](#Operation) with related [Fragments](#Fragment).

## Operation

A GraphQL Operation defines either a Query or Mutation that can be executed against a GraphQL Schema. Operations can
optionally be named. If you are writing an operation, it is helpful to name it for tracking usage. Operations may also
have arguments if required. It is possible to have multiple operations in a single [GraphQL Document](#Document)

### Query

A Query is a specific operation type for performing read-only operations. The operation takes a [Selection Set](
#Selection%20Set) to resolve against the root Query type of the schema.

```graphql
query MyExampleQuery {
    rootScalarResolver
}
```

### Mutation

A Mutation is a specific operation type for performing write operations. The operation takes a [Selection Set](
#Selection%20Set) to resolve against the root Mutation type of the schema.

```graphql
mutation MyExampleMutation {
    rootMutationResolver
}
```

## Fragment

A fragment is a named [Selection Set](#Selection%20Set) for a particular type. It can then be used in any
[Operation](#Operation) in the same [Document](#Document), to reduce repetition of fields.

```graphql
fragment MyNamedFragment on MyObject {
    fieldA
    fieldB
}

query MyExampleQuery {
    rootObjectResolver {
        ... MyNamedFragment
    }
}

mutation MyExampleMutation {
    rootObjectMutationResolver {
        ... MyNamedFragment
    }
}
```

## Selection Set

Refers to a list of named fields that are to be selected from a GraphQL request, in enclosing curly braces.

```graphql
{
    aScalarField
    aCompositeField {
        subField
    }
}
```

## Alias

It is possible to add an alias to a selection in a [Selection Set](#Selection%20Set). There are many use cases for this,
but the most obvious example is to be able to resolve the same field with multiple arguments in the same Selection Set.

```graphql
{
    alias1: myFieldThatTakesAnArgument(argument: 1)
    alias2: myFieldThatTakesAnArgument(argument: 2)
}
```

## Schema

A collection of GraphQL Type definitions

## Types

You may see thw following terms used when discussing GraphQL types. Most of these are from the [GraphQL Specification](
https://spec.graphql.org/), though some of them are from other places such as the [graphql-js library](
https://github.com/graphql/graphql-js/blob/master/src/type/index.js).

### Scalar Type

A GraphQL type that represents a serializable datum. For example, `String`, `Int`, `Id`

New Scalar Types can be defined in the schema like so:

```graphql
scalar MyScalar
```

### Enum Type

GraphQL enum types represent situations where only a limited number of options exist.

```graphql
enum MyEnum {
    ENUM_VALUE_1
    ENUM_VALUE_2
}
```

### Input Object Types

Input Object Types are types that allow you to pass in a key-value map as an input.

```graphql
input MyInput {
    field: MyScalar
    otherField: MyEnum
}
```

### Object Type

This is the main return type of GraphQL - an Object Type has Fields on it that can be individually selected and resolved recursively.

```graphql
type MyObject {
    field: MyScalar
}
```

### Interface Type

Represents a basic set of fields that a type can implement. Implementing types must define the fields identically.

```graphql
interface MyInterface {
    field: MyScalar
}

type MyImplementingObject implements MyInterface {
    # We must supply all interface fields
    field: MyScalar
    # We can add any other additional fields
    anotherField: MyEnum
}
```

### Union Type

Used when the return value of a field can be one of many types. All member types must be Object types.

```graphql
union MyUnion = MyImplementingObject | MyEnum
```

### Abstract Type

Refers to either a Union or Interface type - these are abstract as when they are used as the result type of a field,
that field could return different concrete result types.

### Output Type

Any type that is valid as the result type of a field. In particular that is Scalar, Enum, Object, Interface and Union
types and any [wrapping](#Wrapping%20Type) of those.

### Input Type

Any type that is valid as the result type of a field. In particular that is Scalar, Enum and Input Object types and any
[wrapping](#Wrapping%20Type) of those.

### Leaf Type

Any [Named Type](#Named%20Type) that is valid as a leaf in the input or output formats. This means that they cannot have
a sub-selection of fields. This is any Scalar or Enum type.

### Composite Type

Any [Named Type](#Named%20Type) that can have a sub-selection of fields. This is any Union, Interface or Object type.
Notaly, this doesn't include [Input Object Types](#Input%20Object%20Types), so it is not the inverse of the [Leaf Type](
#Leaf%20Type)

## Type Modifiers

### List Type

Represents a list of zero and more values of the underlying type. Valid in both input and output contexts. The inner
type can be any GraphQL type (even wrapping types).

```graphql
type Example {
    result: [MyScalar]
}
```

### NonNullable Type

Represents that this value may not be `null`. Valid in both input and output contexts. The inner
type can be any GraphQL type, excluding a `NonNullable` type

```graphql
type Example {
    result: MyScalar!
}
```

#### Nullable Type

Any type that is Nullable at the outermost level. `[MyScalar!]` is still Nullable as it does not have a `!` at the
outermost level (`[MyScalar!]!`)

### Wrapping Type

Any type that is wrapped with either a [List](#List%20Type) or [NonNullable](#NonNullable%20Type) Type.

### Named Type

A type that is defined by just a name without any modifiers - this is the inverse of a [Wrapping Type](#Wrappng%20Type)