GraphQL Glossary

As you explore the GraphQL ecosystem, you might encounter some unfamiliar terms and phrases along the way. To help you on your journey, we've defined some of the most common GraphQL vocabulary here in this handy cheat sheet.

Alias

An alternative name provided for a query field to avoid conflicts during data fetching. Use an alias if a query fetches multiple instances of the same field, as shown:

1
query AdminsAndManagers {
2
  admins: users(role: "admin") {
3
    id
4
    firstname
5
    lastname
6
  }
7
  managers: users(role: "manager") {
8
    id
9
    firstname
10
    lastname
11
  }
12
}

The query above uses admins and managers as aliases for the users field.

Argument

A key-value pair associated with a particular schema field, enabling you to pass data to customize that field's return value. Argument values can be passed as literal values (as shown below for clarity) or via variables (recommended).

1
query GetHuman {
2
  human(id: "200") {
3
    name
4
    height(unit: "meters")
5
  }
6
}

The query above provides two arguments:

• The id argument for the human field (indicating which Human object to return)
• The unit argument for the height field (indicating which unit of measurement to use for the return value)

Automatic Persisted Queries (APQ)

A technique for improving GraphQL network performance with zero build-time configuration by reducing request size over the wire. A smaller signature reduces bandwidth use and speeds up client loading times. See the Apollo Server docs..

Data source

A pattern for fetching data from a particular service, with built-in support for caching, deduplication, and error handling. When deploying GraphQL as a layer between your apps and existing APIs and services, data sources provide the best experience for fetching and caching data from REST endpoints.

Deferred query

A query that has certain fields tagged with the @defer directive, so that fields that take a long time to resolve do not need to slow down the entire query.

1
query NewsFeed {
2
  newsFeed {
3
    stories {
4
      text
5
      comments @defer {
6
        text
7
      }
8
    }
9
  }
10
}

Directive

A declaration prefixed with an @ character that encapsulates programming logic for query execution on the client or server. GraphQL includes some built-in directives (such as @skip and @include), and you can define custom directives. Directives can be used for features such as authentication, incremental data loading, etc.

1
type User @auth {
2
  name: String!
3
  banned: Boolean @auth
4
}

Docstring

Provides the description of a type, field, or argument. Docstrings automatically appear in many common GraphQL tools, including the Apollo Studio Explorer.

1
"""
2
Description for the User
3
"""
4
type User {
5
  """
6
  Description for first Name
7
  """
8
  firstName: String!
9

10
  age(
11
    """
12
    Must be an integer
13
    """
14
    arg: Int
15
  )
16
}

Document

A file or request string that contains one or multiple definitions of a GraphQL type system and can be interpreted by a GraphQL execution engine.

Most Apollo libraries use the gql template literal to create GraphQL documents:

1
// A schema document created with the gql template literal
2
const typeDefs = gql`
3
  type Book {
4
    title: String
5
    author: String
6
  }
7

8
  type Query {
9
    books: [Book]
10
  }
11
`;

Extensions

A GraphQL operation's response can include an extensions object to provide metadata about the operation:

1
{
2
  "data": {
3
    "books": [
4
      {
5
        "title": "The Awakening"
6
      },
7
      {
8
        "title": "City of Glass"
9
      }
10
    ]
11
  },
12
  "extensions": {
13
    "timestamp": 1633038919
14
  }
15
}

The extensions object can have any structure. GraphQL servers can use this object to include timing data, additional error details, or any other helpful information.

Field

A unit of data that belongs to a type in your schema. Every GraphQL query requests one or more fields.

1
type Author {
2
  id: Int!
3
  firstName: String
4
  lastName: String
5
}

In the schema definition above, id, firstName, and lastName are fields of the Author type.

Fragment

A selection set of fields that can be shared between multiple query operations. See the documentation.

1
fragment UserData on User {
2
  id: ID!
3
  firstName: String!
4
  lastName: String!
5
}
6

7
query getUsers {
8
  allUsers {
9
    ...UserData
10
  }
11
}

gql function

A JavaScript template literal tag that parses GraphQL queries into an abstract syntax tree (AST).

1
const typeDefs = gql`
2
  type Book {
3
    title: String
4
    author: String
5
  }
6

7
  type Query {
8
    books: [Book]
9
  }
10
`;

GraphQL server

A server that contains a GraphQL schema and can resolve operations that are executed against that schema. Apollo Server is an example of a GraphQL server.

Introspection

A special query that enables clients and tools to fetch a GraphQL server's complete schema. Types and fields used in introspection are prefixed with __ (two underscores).

Introspection should be disabled in production.

1
{
2
  __schema {
3
    types {
4
      name
5
    }
6
  }
7
}

Mutation

A GraphQL operation that creates, modifies, or destroys data. See the documentation.

1
mutation AddTodo($type: String!) {
2
  addTodo(type: $type) {
3
    id
4
    type
5
  }
6
}

Normalization

A technique for transforming the response of a query operation before saving it to Apollo Client's in-memory cache. The result is split into individual objects, creating a unique identifier for each object, and storing those objects in a flattened data structure. See the documentation.

Object Type

A type in a GraphQL schema that has one or more fields.

1
type User {
2
  name: String!
3
}

User is an object type in the example above.

Operation

A single query, mutation, or subscription that can be interpreted by a GraphQL execution engine.

Operation name

The name of a particular query, mutation, or subscription. You should provide a name for every operation to improve logging and debugging output when an error occurs.

1
mutation AddTodo($type: String!) {
2
  addTodo(type: $type) {
3
    id
4
    type
5
  }
6
}
7

8
query GetHuman {
9
  human(id: "200") {
10
    name
11
    height(unit: "meters")
12
  }
13
}

The operations above are named AddTodo and GetHuman.

Operation signature

The normalized representation of a particular GraphQL operation (query, mutation, or subscription). Normalizing an operation transforms it deterministically to reduce the number of possible forms it could take. For example, many normalization algorithms sort an operation's fields alphabetically.

Other normalization algorithms replace in-line variables(literals) with empty, null, or zero values, sort fragments, remove whitespace, or remove aliases.

The following example shows the default signature algorithm for GraphOS metrics reporting.

Here's an operation definition before normalization:

1
query getHuman {
2
  human(id: 200) {
3
    pounds: weight(unit: "pounds")
4
    height
5
  }
6
}

And here's that operation's signature after normalization, which hides literals, sorts fields, removes aliases, and removes whitespace:

1
query getHuman { human(id: 0) { height weight(unit: "") } }

Partial query caching

A technique for caching inputs to GraphQL queries. This type of caching ensures that if the query is slightly different but with the same inputs, those inputs can simply be retrieved from the cache instead of fetching data again from the backend. This is implemented in the RESTDataSource class, which Apollo Server can use to fetch data from REST APIs.

Query

A read-only fetch operation to request data from a GraphQL server.

Query colocation

A practice of placing a GraphQL query in the same location as the app component that uses that query to render itself. This practice makes it easier to fetch data and render your UI responsively.

1
const EXCHANGE_RATES = gql`
2
  query GetExchangeRates {
3
    rates(currency: "USD") {
4
      currency
5
      rate
6
    }
7
  }
8
`;
9

10
function ExchangeRates() {
11
  const { loading, error, data } = useQuery(EXCHANGE_RATES);
12

13
  if (loading) return <p>Loading...</p>;
14
  if (error) return <p>Error :(</p>;
15

16
  return data.rates.map(({ currency, rate }) => (
17
    <div key={currency}>
18
      <p>
19
        {currency}: {rate}
20
      </p>
21
    </div>
22
  ));
23
}

Resolver

A function that populates data for a particular field in a GraphQL schema. Resolvers provide the instructions for turning a GraphQL operation into data. It can retrieve data from or write data to anywhere, including a SQL, No-SQL, or graph database, a micro-service, and a REST API. Resolvers can also return strings, ints, null, and other primitives.

1
const resolvers = {
2
  Query: {
3
    author(root, args, context, info) {
4
      return find(authors, { id: args.id });
5
    },
6
  },
7
  Author: {
8
    books(author) {
9
      return filter(books, { author: author.name });
10
    },
11
  },
12
};

Schema

A GraphQL schema is at the center of any GraphQL server implementation and describes the functionality available to the clients which connect to it.

Schema Definition Language (SDL)

The syntax for writing GraphQL Schemas. It is otherwise known as Interface Definition Language. It is the lingua franca shared by all for building GraphQL APIs regardless of the programming language chosen.

1
type Author {
2
  id: Int!
3
  firstName: String
4
  lastName: String
5
  posts: [Post]
6
}
7

8
type Post {
9
  id: Int!
10
  title: String
11
  author: Author
12
  votes: Int
13
}
14

15
type Query {
16
  posts: [Post]
17
  author(id: Int!): Author
18
}

Schema-first development

A development approach for designing and building modern UIs that involves the frontend and backend teams agreeing on a Schema first, which serves as a contract between the UI and the backend before any API engineering happens.

Schema registry

The central source of truth for your schema. It enables schema registration, schema checks, tracking of detailed schema changes (such types added, fields added, and fields deprecated), and looking up previous versions of a schema.

Schema versioning

Refers to the need to evolve a schema over time. As a schema evolves, there's the potential to introduce breaking changes to clients. Apollo GraphOS assists with schema evolution by checking proposed schema changes for breaking changes. Learn more about schema checks.

Subscription

A long-lived, real-time GraphQL operation. Supported subscriptions are defined in a schema along with queries and mutations.

1
type Subscription {
2
  commentAdded(repoFullName: String!): Comment
3
}
4
...
5
subscription onCommentAdded($repoFullName: String!){
6
  commentAdded(repoFullName: $repoFullName){
7
    id
8
    content
9
  }
10
}

Scalar type

A type that qualifies the data a GraphQL field resolves. GraphQL ships with some scalar types out of the box; Int, Float, String, Boolean and ID. You can also define custom scalars.

Type system

A collection of types which characterizes the set of data that can be validated, queried, and executed on a GraphQL API.

Variable

A value that can be passed to an operation. Variables can be used to fill arguments, or be passed to directives.

1
query GetUser($userId: ID!) {
2
  user(id: $userId) {
3
    firstName
4
  }
5
}

In the query above, userId is a variable. The variable and its type are declared in the operation signature, signified by a $. The type of the variable here is a non-nullable ID. A variable's type must match the type of any argument it's used for.

The userId variable is included in the operation by Apollo Client like so:

1
client.query({ query: getUserQuery, variables: { userId: 1 } });

Whole response caching

A technique used to cache entire results of GraphQL queries. This process improves performance by preventing the fetching of the same results from the server if it has been obtained before. Read more about GraphQL query caching in our guide for caching with Apollo Server.