Docs
Launch GraphOS 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.

Alias

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

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

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

Argument

A key-value pair associated with a particular schema , enabling s to pass data to that field's resolver. values can be hardcoded as literal values (shown below for clarity) or provided via GraphQL variables (recommended).

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

The query above provides two s:

  • The id for the human (indicating which Human object to return)
  • The unit for the height (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 s by passing an identifier, instead of by passing the entire operation string.

For very large 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 s tagged with the @defer , indicating that the GraphQL server can return all other s before the deferred fields are ready. The server can then return the deferred fields in subsequent payloads.

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

By deferring slow-to-resolve s, 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 or :

type User {
username: String! @lowerCase
}

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

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

Docstring

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

"""
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:

// A schema document created with the gql template literal
const typeDefs = gql`
type Book {
title: String
author: String
}
type Query {
books: [Book]
}
`;

Extensions

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

{
"data": {
"books": [
{
"title": "The Awakening"
},
{
"title": "City of Glass"
}
]
},
"extensions": {
"timestamp": 1633038919
}
}

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 . Every GraphQL query requests one or more s.

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

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

Fragment

A selection set of s that can be shared between multiple query s. 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 server

A server that contains a GraphQL and can resolve s 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 . Types and s used in are prefixed with __ (two underscores).

should be disabled in production.

{
__schema {
types {
name
}
}
}

Mutation

A GraphQL 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 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 that has one or more s.

type User {
name: String!
}

User is an in the example above.

Operation

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

Operation name

The name of a particular query, , or . You should provide a name for every 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 s above are named AddTodo and GetHuman.

Operation signature

The normalized representation of a particular GraphQL (query, , or ). 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 s alphabetically.

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

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

Here's an definition before normalization:

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

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

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

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>
));
}

Resolver

A function that populates data for a particular in a GraphQL . A can define any custom logic to populate its data, but it usually involves fetching from a (such as a database, REST API, or other microservice).

Learn about resolvers in Apollo Server.

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

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 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 . It enables schema registration, , tracking of detailed schema changes (such types added, s added, and fields deprecated), and looking up previous versions of a schema.

Schema versioning

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

Subscription

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

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

Scalar type

A "base" type in GraphQL that resolves to a single value. GraphQL includes the following 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 . s can be used to fill s, or be passed to s.

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

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

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

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.

Previous
Why adopt GraphQL?
Next
FAQ
Edit on GitHubEditForumsDiscord