/
Launch Apollo Studio

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.

Apollo

An open-source implementation of GraphQL that helps you manage data between the cloud and your UI. The Apollo platform is pluggable into your existing architecture and features production-ready tooling that helps you scale GraphQL across your organization (Server, Client, and Studio).

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..

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).

query GetHuman {
  human(id: "200") {
    name
    height(unit: "meters")
  }
}

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)

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:

query AdminsAndManagers {
  admins: users(role: "admin") {
    id
    firstname
    lastname
  }
  managers: users(role: "manager") {
    id
    firstname
    lastname
  }
}

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

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

This is an experimental feature. It is not included in any stable releases of Apollo Client or Apollo Server.

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.

query NewsFeed {
  newsFeed {
    stories {
      text
      comments @defer {
        text
      }
    }
  }
}

Directive

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

type User @auth {
  name: String!
  banned: Boolean @auth!
}

Docstring

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

"""
Description for the User
"""
type User {
  """
  Description for first Name
  """
  firstName: String!

  age(
    """
    Must be an integer
    """
    arg: Int
  )
}

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:

const typeDefs = gql`
  type Book {
    title: String
    author: String
  }

  type Query {
    books: [Book]
  }
`;

Extensions

Special fields in a GraphQL response that allow you to attach extra metadata. Apollo tracing is an example of an extension.

Field

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

type Author {
  id: Int!
  firstName: String
  lastName: String
}

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.

fragment UserData on User {
  id: ID!
  firstName: String!
  lastName: String!
}

query getUsers {
  allUsers {
    ...UserData
  }
}

gql function

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

const typeDefs = gql`
  type Book {
    title: String
    author: String
  }

  type Query {
    books: [Book]
  }
`;

GraphQL Playground

An in-browser IDE for GraphQL development and workflow. Provided out-of-the-box in Apollo Server.

GraphQL service

The server that contains a GraphQL schema and the ability to run it. Services have runtime information, and through features of the Apollo Platform they can send metrics and maintain a history of the schemas that have been run on that service in the past.

GraphiQL

An in-browser IDE for GraphQL development and workflow.

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.

{
  __schema {
    types {
      name
    }
  }
}

Mutation

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

mutation AddTodo($type: String!) {
  addTodo(type: $type) {
    id
    type
  }
}

Normalization

A technique for transforming the response of a query operation before saving it to Apollo Client's InMemoryCache. 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.

type User {
   name: String!
}

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.

mutation AddTodo($type: String!) {
  addTodo(type: $type) {
    id
    type
  }
}

query GetHuman {
  human(id: "200") {
    name
    height(unit: "meters")
  }
}

The operations above are named AddTodo and GetHuman.

Operation signature

Representation of a GraphQL operation(query, mutation, or subscription). These operations can be directly executable or normalized to a more simplified form. Normalization transforms an operation deterministically to reduce the number of possible forms it could take. For example, many normalization algorithms sort the fields of the operation to remove field order from the possible representations of an operation. 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 performance monitoring. The first signature is before and the second is after normalization, which hides literal, sorts fields, removes aliases, and removes whitespace:

query getHuman {
  human(id: 200) {
    pounds: weight(unit: "pounds")
    height
  }
}

The normalized operation signature:

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. It is implemented in Apollo Server 2 as Data Source caching.

Query

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

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.

const EXCHANGE_RATES = gql`
  query GetExchangeRates {
    rates(currency: "USD") {
      currency
      rate
    }
  }
`;

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

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

  return data.rates.map(({ currency, rate }) => (
    <div key={currency}>
      <p>
        {currency}: {rate}
      </p>
    </div>
  ));
}

Query safelisting

A technique for preventing unwanted attacks by maintaining a list of approved queries that are allowed in your application. Any query not present in the list that is run against the server will not be allowed. Automatic Persisted Queries is a feature of Apollo Server 2 that enables query whitelisting and persisted queries.

Resolver

A function that connects schema fields and types to various backends. 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.

const resolvers = {
  Query: {
    author(root, args, context, info) {
      return find(authors, { id: args.id });
    },
  },
  Author: {
    books(author) {
      return filter(books, { author: author.name });
    },
  },
};

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.

type Author {
  id: Int!
  firstName: String
  lastName: String
  posts: [Post]
}

type Post {
  id: Int!
  title: String
  author: Author
  votes: Int
}

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

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 is a potential for introducing breaking changes to clients. The Apollo CLI assists schema evolution by checking schema changes for breaking changes using Apollo Studio. Read more in our article about schema checks.

Schema stitching

The process of merging different schemas into one GraphQL schema. These schemas can be local, remote, or from third-party services. In a microservice-style deployment model, where your data exists across multiple APIs, schema stitching makes it possible to combine all of them into one schema that can be queried for all the data at once.

Subscription

A real-time GraphQL operation. A Subscription is defined in a schema along with queries and mutations.

type Subscription {
  commentAdded(repoFullName: String!): Comment
}
...
subscription onCommentAdded($repoFullName: String!){
  commentAdded(repoFullName: $repoFullName){
    id
    content
  }
}

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. However, a custom scalar type such as Date can be specified in a GraphQL service implementation.

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.

query GetUser($userId: ID!) {
  user(id: $userId) {
    firstName
  }
}

In the query above, userId is a variable. The variable and its type is declared in the operation signature, signified by a $. The type of the variable here is a required ID. It's important to note that variable types must match the type of the arguments that they fill.

The userId variable would be passed to the operation by apollo-client like this:

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

In react-apollo it would be passed like this:

<Query query={getUserQuery} variables={{ userId: 1 }}>
  {' '}
  ...{' '}
</Query>

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.

Edit on GitHub