GraphQL Wire Adapter Best Practices

When creating queries for your GraphQL wire adapter, follow these best practices to get the most out of GraphQL API for your LWC development.

Here's where the power of GraphQL really shines. You can write a query that satisfies your data needs and gives you exactly what you asked for, nothing more and nothing less. Writing a brief query that satisfies your data requirements makes the return result predictable, while ensuring that your query remains performant.

Use the first argument to limit the number of results, and paginate your results with the after argument. The default is 10.

In this example, including the totalCount field makes the query look up all existing records, even though only the first 5 are returned.

Using variables makes your query reusable with LWC's reactivity feature, which means that your query fetches the data only when any of the variable values is changed.

Using variables ensures that your query results reflect the arguments being used. It also helps improve performance so that the client framework understands that the query itself hasn’t changed and it can skip parsing and revalidating the query.

The $minAmount GraphQL variable enables the component to set and change the minimum amount.

For more information, see Make Your Variables Reactive.

To delay your query from executing, such as for testing or when you're working with multiple queries, use a getter and pass in the query using a variable like query: '$recordQuery'. For example, delaying the query can be helpful when you’re fetching contacts by account Id and don't have the account Id when the component loads.

In this example, the accountId isn't reactive to changes.

In some cases, you don't have the account Id when the component loads, for example:

• You expect the user to select an account, which then sets the account Id
• You set the account Id depending on which account record page is displayed

To delay query execution, make your query reactive by updating the query and variables parameters like in the next example.

This example queries the associated contacts on an account record page that's currently displayed. The AccountId field value on the Contact object is provided by @api recordId, which makes a component aware of its record context.

The HTML template looks like this.

Send multiple queries in one operation when you want to request record data for multiple objects. Combining multiple queries can help prevent unnecessary requests to the server. For example, send your query in a separate call if the query depends on a field or value from an earlier query.

Alternatively, work with semi-joins or auto-joins to query records with parent and child relationships.

You can specify a parent or child relationship in your query for the GraphQL wire adapter. Objects can have children relationships to the same object, just like a parent account can have child accounts. Some objects have children relationships to other objects. For example, accounts have child relationships to assets, cases, and contacts among other objects.

The GraphQL API schema provides details of parent-child relationships. For example, the Account field is defined as a parentRelationship type on the Contact object. Similarly, the Cases field is defined as a childRelationship type on the Contact object.

For more information, see Relationship Filters.

Salesforce automatically understands references to objects and fields within your GraphQL queries and applies referential integrity to those references. If your GraphQL query references a custom entity or field and that entity or field is renamed, Salesforce updates your GraphQL query to use the new name. While this update prevents your query from failing at runtime, it also changes the shape of the data returned from the query.

To protect against unintentional change of the data shape, we recommend that you add GraphQL aliases to any custom object and field names in your GraphQL query that could change. Adding aliases preserves the names used for these objects and fields in the GraphQL result, while still allowing Salesforce’s referential integrity mechanisms to work correctly. Aliases ensure that your component remains valid and prevents any runtime errors in the future.

Let's say you are querying a custom object and a custom field like this.

Add aliases to all custom objects and fields used in your query during development, before you publish a managed package. See Use a Namespace and Alias in Managed Packages.

When a subscriber org or your team member changes the object or field name, updating Custom_object__c to Custom_object2__c, and Object_name__c to Object_name2__c, your component preserves its referential integrity.

The wire adapter returns a JSON response that looks like this.

GraphQL Wire Adapter Limitations