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
gqlparses the GraphQL query into a format that the wire adapter can use.
variables—A key-value pair of dynamic values for the
variableswith 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
operationNameto select the operation to run if your GraphQL query defines more than one operation. We recommend labeling your queries with
query operationNameinstead of using the shorthand syntax
queryfor improved debugging on the server-side to identify different GraphQL requests. For example,
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
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
The example declares the
Currency type for the
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
format fields. We recommend that you review the schema documentation using the Altair GraphQL client.
The GraphQL API wire adapter doesn't currently support these use cases.
- Experience Cloud sites
- 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
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.
- GraphQL API Developer Guide: Use GraphQL API with Lightning Web Components
- Mobile and Offline Developer Guide: Use Salesforce Features While Offline