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 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 it returns only the first 5.

Using variables makes your query reusable with LWC’s reactivity feature, which means that your query fetches the data only if any of the variable values 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 if 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 if 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 displays

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.

Dynamically generate queries in the wire adapter at run time to support component state or user input. To dynamically construct your query, use JavaScript string interpolation inside the gql tagged template literal. Dynamic query construction in the wire adapter is available in API v65.0 and later and requires the lightning/graphql LWC module.

In this example, ${this.objectName} represents the dynamic part of the query that’s resolved at run time.

Unlike static queries, referential integrity isn’t automatically preserved for dynamically generated queries. You must manually resolve any compilation errors in LWC components caused by renamed or deleted entities or fields.

Send multiple queries in one operation if 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 a parentRelationship type on the Contact object. Similarly, the Cases field is 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 run time, 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 run-time 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.

If 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