Docs
Launch GraphOS Studio

GraphQL query best practices

Operation naming, GraphQL variables, and more


When creating queries and , follow these best practices to get the most out of both and Apollo tooling.

Name all operations

These two queries fetch the same data:

# Recommended ✅
query GetBooks {
books {
title
}
}
# Not recommended ❌
query {
books {
title
}
}

The first is named GetBooks. The second is anonymous.

You should define a name for every in your application. Doing so provides the following benefits:

  • You clarify the purpose of each for both yourself and your teammates.
  • You avoid unexpected errors when combining multiple in a single (an anonymous operation can only appear alone).
  • You improve debugging output in both client and server code, helping you identify exactly which is causing issues.
  • Apollo Studio provides helpful -level metrics, which require named operations.

Use GraphQL variables to provide arguments

These two queries can both fetch a Dog object with ID "5":

# Recommended ✅
query GetDog($dogId: ID!) {
dog(id: $dogId) {
name
breed
}
}
# Not recommended ❌
query GetDog {
dog(id: "5") {
name
breed
}
}

The first uses a ($dogId) for the value of the dog 's required . This means you can use the to fetch a Dog object with any ID, making it much more reusable.

You pass values to useQuery (or useMutation) like so:

dog.tsx
const GET_DOG = gql`
query GetDog($dogId: ID!) {
dog(id: $dogId) {
name
breed
}
}
`;
function Dog({ id }) {
const { loading, error, data } = useQuery(GET_DOG, {
variables: {
dogId: id
},
});
// ...render component...
}

Disadvantages of hardcoded GraphQL arguments

Beyond reusability, hardcoded have other disadvantages relative to :

Reduced cache effectiveness

If two otherwise identical queries have different hardcoded values, they're considered entirely different operations by your 's cache. The cache enables your server to skip parsing and validating that it's encountered before, improving performance.

The server-side cache also powers features like automatic persisted queries and in a federated gateway. Hardcoded reduce the performance gains of these features and take up useful space in the cache.

Reduced information privacy

The value of a might include sensitive information, such as an access token or a user's personal info. If this information is included in a string, it's cached with the rest of that query string.

values are not included in strings. You can also specify which values (if any) are included in metrics reporting to Apollo Studio.

Query only the data you need, where you need it

One of 's biggest advantages over a traditional REST API is its support for declarative data fetching. Each component can (and should) exactly the it requires to render, with no superfluous data sent over the network.

If instead your root component executes a single, enormous to obtain data for all of its children, it might query on behalf of components that aren't even rendered given the current state. This can result in a delayed response, and it drastically reduces the likelihood that the 's result can be reused by a server-side response cache.

In the large majority of cases, a such as the following should be divided into multiple queries that are distributed among the appropriate components:

  • If you have collections of components that are always rendered together, you can use to distribute the structure of a single between them. See Colocating fragments.
  • If you're a list that returns more items than your component needs to render, you should paginate that field.

Query global data and user-specific data separately

Some return the exact same data regardless of which user queries them:

# Returns all elements of the periodic table
query GetAllElements {
elements {
atomicNumber
name
symbol
}
}

Other return different data depending on which user queries them:

# Returns the current user's documents
query GetMyDocuments {
myDocuments {
id
title
url
updatedAt
}
}

To improve the performance of your server-side response cache, fetch these two types of in separate queries whenever possible. By doing so, your server can cache just a single response for a like GetAllElements above, while caching separate responses for each user that executes GetMyDocuments.

Set your app's name and version for metrics reporting (paid)

This recommendation is most pertinent to Apollo Studio organizations with a paid plan, however it can be helpful for all apps.

The constructor of ApolloClient accepts the name and version options:

const client = new ApolloClient({
uri: 'http://localhost:4000/graphql',
cache: new InMemoryCache(),
name: 'MarketingSite',
version: '1.2'
});

If you specify these values, automatically adds them to each request as HTTP headers (apollographql-client-name and apollographql-client-version).

Then if you've configured metrics reporting in Apollo Studio, includes your app's name and version in the traces it reports to Studio. This enables you to segment metrics by client.

Previous
Document transforms
Next
Overview
Edit on GitHubEditForumsDiscord

© 2024 Apollo Graph Inc.

Privacy Policy

Company