graphql

The GraphQL wire adapter manages your data using Lightning Data Service (LDS). You don’t need different wire adapters for each query defined in the GraphQL schema, unlike the other wire adapters. Instead, LDS provides a single wire adapter that accepts a GraphQL query document and a variables map.

The GraphQL wire adapter uses the Salesforce GraphQL API schema, which enables you to use UI API enabled objects with the object-level security and field-level security of the current user. UI API supports the GraphQL Cursor Connections Specification for pagination.

To explore the GraphQL API schema, we recommend reviewing the schema documentation via introspection using the Altair GraphQL client. The client provides a query editor that includes field auto-completion, enabling you to add fields easily for a given type on any Salesforce object. We recommend that you use this client to help you build your queries quickly and accurately.

The GraphQL wire adapter uses this GraphQL API resource.

  • query— (Required) Parsed GraphQL query. Parse the query using the gql JavaScript template literal function. gql parses the GraphQL query into a format that the wire adapter can use. gql isn’t reactive.

  • variables—A key-value pair of dynamic values for the gql query. Use variables with a getter function so the wire adapter can react to changes.

    The value passed to variables must be a map that includes a value for every variable on the query that does not specify a default value.

  • operationName—The name of the operation you want to perform in the query. Use operationName to select the operation to run if your GraphQL query defines more than one operation. We recommend labeling your queries with query operationName instead of using the shorthand syntax query for improved debugging on the server-side to identify different GraphQL requests. For example, query bigAccounts or query serviceReports.

To maintain compatibility with the GraphQL response specification, the GraphQL wire adapter uses errors instead of error, unlike other LWC wire adapters.

To start using the wire adapter, import an identifier and provide a configuration for the properties on your component. Pass in your query using the gql function.

This HTML template displays the first 10 account names returned by the query.

To add reactivity, pass in your values to the variables parameter and create a getter for the return value.

The getter function enables the GraphQL wire adapter to be reactive to changes in minAmount.

The example declares the Currency type for the $minAmount variable. Currency refers to types in the Salesforce GraphQL API schema. A Currency type is a raw value, for example, 1000. In this case, you can’t pass in a value with formatting, like 1,000. When a user selects a different amount, the handleMinAmountChange event handler updates the query.

This HTML template enables you to select a minimum amount and displays the queried accounts.

Many Salesforce fields map to a raw value and an object with value, displayValue, and format fields. We recommend that you review the schema documentation using the Altair GraphQL client.

The lwc-recipes repo has many GraphQL API examples. Look for components that start with graphql, such as graphqlContacts.

The GraphQL API wire adapter doesn't currently support these use cases.

  • Dynamic construction of GraphQL queries at runtime, such as referencing a fragment from another component
  • String interpolation constructs using ${}
  • Using variables in directives such as @skip and @include

GraphQL API features can take several releases to be available in the wire adapter. See GraphQL Wire Adapter Limitations.

If your GraphQL query fails prefetch in the Salesforce mobile app, Salesforce Field Service, or Mobile Offline, you must continue to use metaschema directives in your GraphQL query for referential integrity and priming functionality. See Known Issue: GraphQL query fails prefetch with an "Unknown Field" warning.

Additionally, the usage of fragments on custom objects and custom fields has known limitations. Currently, referential integrity breaks if the custom object or field gets renamed. Since a GraphQL query that uses fragments can be composed without the fragments, you can query the same data by replacing the fragments.

Let's look at a query that contains a fragment. To maintain referential integrity, remove the fragment from the query.

To use the query without a fragment, remove and replace the fragment like this.

Some fields are not filterable using the where filter. To find out if a field is supported for filtering, see the Object Reference for the Salesforce Platform. For example, the NewValue and OldValue fields on the CaseHistory object don't include "Filter" in the Properties section and aren't supported for filtering. If you attempt to pass in an unsupported field to the where filter, you get a "Field 'FieldName' in type 'ObjectName' is undefined" error.

See Also