GraphQL Glossary

Familiarize yourself with common GraphQL terms

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

A mechanism for including multiple instances of a single field in a GraphQL operation. This enables you to provide different argument values to each instance.

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 operations to pass data to that field's resolver. Argument values can be hardcoded as literal values (shown below for clarity) or provided via GraphQL 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 by enabling clients to execute operations by passing an identifier, instead of by passing the entire operation string.

For very large operation strings, APQ meaningfully reduces bandwidth use and speeds up client loading times.

Learn more about APQ.

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, indicating that the GraphQL server can return all other fields before the deferred fields are ready. The server can then return the deferred fields in subsequent payloads.

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

By deferring slow-to-resolve fields, a client can receive other data as quickly as possible.

Learn how to use @defer with Apollo GraphOS.

Directive

A declaration prefixed with @ that you apply to various locations in a GraphQL schema or operation:

1
type User {
2
  username: String! @lowerCase
3
}

A directive usually has some associated logic that modifies the behavior of the associated location. For example, the @lowerCase directive above might define logic to always convert the username field to lower case before returning it.

GraphQL includes some built-in directives (such as @deprecated), and you can also define custom directives.

Docstring

Provides the description of a type, field, or argument. Docstrings automatically appear in many common GraphQL tools, including the GraphOS 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. A resolver can define any custom logic to populate its data, but it usually involves fetching from a data source (such as a database, REST API, or other microservice).

Learn about resolvers in Apollo Server.

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. All GraphQL APIs can use SDL to represent their schema, regardless of which programming language the API is implemented in.

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 "base" type in GraphQL that resolves to a single value. GraphQL includes the following scalar types by default: Int, Float, String, Boolean, and ID.

You can also define custom scalars. Learn more about the default scalar types.

Type system

A collection of types that 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.

Why adopt GraphQL?

FAQ