At Salesforce, we’re committed to investing in GraphQL as an integral part of our flexible, composable platform. Previously, we shared that the Salesforce GraphQL API had become generally available (GA). Now, we’re excited to announce the pilot launch of the Salesforce GraphQL Wire Adapter in our Spring ’23 release. In this article, we’ll explore the benefits of the GraphQL Wire Adapter and how it makes it easier to access Salesforce data from Lightning Web Components (LWCs).

This new adapter will enable LWC developers to natively query Salesforce data using an industry-standard query language with rich predicates for filtering, grouping, aggregation, and sorting. A developer will be able to use the GraphQL wire adapter to build web components and mobile offline apps with LWCs. Please refer to the developer documentation for the currently available features.

As of now, the Salesforce GraphQL stack consists of, from the backend to the server:

1. a GraphQL API that exposes the data available via User Interface (UI) API,
2. the GraphQL Wire Adapter that interfaces with the GraphQL API to fetch data, and
3. web and mobile apps built with LWCs. Note, the GraphQL API will integrate more Salesforce APIs later.

Customer use case: Building a dashboard with GraphQL Wire Adapter

To illustrate the benefits of the GraphQL Wire Adapter, let’s look at a customer support dashboard use case. Imagine a developer who wants to build a dashboard that enables the support team to quickly triage incoming cases based on a set of criteria and take appropriate actions. Under the hood, this requires fetching multiple types of records that are connected to each other along with specific fields to display.

There are a few different ways the author of these UI components could retrieve the necessary data:

1. By using existing REST-style wire adapters such as the deprecated getListUi to retrieve record ids and getRecords to retrieve record data. While these wire adapters can retrieve the necessary data, this is an awkward solution that will require multiple round trips to the server. Additionally, someone in the org will need to create and maintain a list view that identifies the records to be shown on this UI.
2. By calling an Apex method to return some or all of the information, and using existing REST-style wire adapters to retrieve the remaining data. Apex allows the developer to exactly express the SOQL query that needs to be run, but the resulting record data will be opaque to the Lightning Data Service (LDS) caching layer on the client. If the Apex method is cacheable the client will have multiple copies of the same record cached, with no way to guarantee consistency across those copies. Record data retrieved using REST-style wire adapters won’t have this issue but will require additional roundtrips to the server. As with the list view in (1), there’s the additional challenge of creating and maintaining the Apex code to keep it synchronized with the component.
3. By using GraphQL, the component author is able to precisely express both the query to be run and the data to be retrieved for each record in a single server call. Because GraphQL is strongly-typed and described by a formal schema, LDS can understand the shape of the result, cache it effectively, and provide consistency guarantees across all the components rendered on the client.

The benefits of the GraphQL Wire Adapter

The GraphQL Wire Adapter provides several benefits that make it easier for developers to access Salesforce data in LWCs:

• Native queryability for LWCs: Query Salesforce data using industry-standard query language with rich predicates. Developers can now easily and efficiently query Salesforce data in their LWCs, without needing to use Apex to handle data queries.

• A single endpoint and data aggregation: You get one endpoint for all your resources, and data can be aggregated across multiple resources. Fewer, more specific requests help you optimize the performance of your app.
• Better developer experience: GraphQL enables a better developer experience with rich expressions, a comprehensive view of data, and extensible experiences.
• Modular, distributed data fetching logic: GraphQL fragments allow a clean separation of application and presentation logic. Components that fetch data and components that render data can be written and tested independently, with no overlap in responsibilities. This also makes the components more reusable.
• Built-in shared caching by LDS: GraphQL data is strongly-typed and described by a formal schema. LDS leverages this deep understanding of the data to cache it more effectively and efficiently and to provide consistency guarantees that span both GraphQL and non-GraphQL results. LDS can, for example, combine and reuse data from previous GraphQL and non-GraphQL wire adapter requests to satisfy subsequent requests without requesting data from the server, which improves app performance beyond the gains from GraphQL’s data aggregation.
• User permissions and security: Just like with REST, when running a query, GraphQL respects Field-Level Security, Org Perms, and User CRUD permissions.
• Mobile offline support: In mobile offline-enabled environments, GraphQL queries can be evaluated against locally-cached data, which allows components to use GraphQL queries offline. This capability is important for our customers who operate mission-critical functions in low or no connectivity conditions such as rural areas, underground, and disaster sites. Offline queries reflect draft changes (record creations and updates) that haven’t yet been replicated to the server. These runtime environments also support the use of GraphQL queries to prime the local data cache in preparation for offline mode.

The above benefits are in addition to standard GraphQL features such as query predicates, runtime parameterization using variables, fragments, aliases, and pagination.

Getting started

To join the pilot and test this adapter in your sandbox or pre-production org, contact your account representative and ask them to nominate you for the GraphQL Wire Adapter pilot.

Check out the developer guides:

• GraphQL Wire Adapter
• GraphQL API

How to use it

Using the GraphQL Wire Adapter is easy and straightforward. You only need to upgrade your org to the latest Salesforce build (Spring ’23 release). Here’s how you can get started:

1. Validate your query. Use Altair, GraphiQL, or Postman (with Salesforce APIs) tools to validate your query. These clients allow you to quickly iterate on your query and ensure that it retrieves exactly the information your component needs.
2. Import the adapter. Import the Salesforce GraphQL Wire Adapter (graphql) and tagged template function (gql) into your LWC’s code. gql identifies the GraphQL queries within your component source code so that the framework can handle them correctly. graphql is the wire adapter used to retrieve the results of your GraphQL query.
3. Invoke your query. Use the imported graphql wire adapter to evaluate the GraphQL query and get the data you need. Data is automatically retrieved and emitted back to your component. Data can be re-emitted to your component if LDS observes changes to previous results.

Please refer to this trailhead project on how to create and deploy a Lightning Web Component.

Next steps

Reminder: Salesforce is a publicly traded company, and customers should base their purchasing decisions on products and services that are currently available.

We’re committed to continuing to invest in GraphQL and the GraphQL Wire Adapter. Here’s what you can expect in upcoming releases (forward-looking statement applies):

Summer ’23:

• GraphQL Wire Adapter (Beta)
• Aggregate query support in GraphQL API

Winter ’24 and Beyond:

• GraphQL Wire Adapter (GA)
• Mutations support in GraphQL API (Pilot)
• Persisted queries

Join us at TrailblazerDX

Come join us at TrailblazerDX, the Salesforce developer event of the year. You can learn more about GraphQL, LWC, and other Salesforce technology and product offerings, and meet the people who have built them.

Check out these sessions and booths at TrailblazerDX:

• Main Keynote: Khushwant Singh will demo how to build your customer’s business with LWC and GraphQL.
• Breakout Session: Power your LWCs with GraphQL. Suvda Myagmar and Stephen Carraway will showcase the Salesforce GraphQL offerings.
• LWC Booth in Platform Park: Meet our product managers and developers and see the demo.

About the authors

Suvda Myagmar is a Director of Product Management at Salesforce passionate about Data and AI platforms. She loves long runs while listening to audiobooks.

Mike Burr is a Principal Software Developer at Salesforce with more years of experience building data access APIs than he cares to admit. In his spare time, he dabbles in home automation and helps out the local high school marching band.