GraphQL Wire Adapter in LWC Explained with Examples

Updated 9 min read
GraphQL Wire Adapter featured image showing a component requesting selected fields

The GraphQL Wire Adapter lets a Lightning Web Component ask Salesforce for the exact fields it needs, with no Apex class behind it. You write the query inside the component, wire it, and the records arrive shaped the way you asked.

That is the real appeal. A wire call to the UI API returns a fixed shape whether you need two fields or twenty. An Apex method returns whatever the developer decided months ago. Here the component decides, and the payload shrinks to match.

GraphQL Wire Adapter diagram showing query, security checks and cached response

Caption: Security still runs on the server, so a query cannot read a field the user is not allowed to see.

What Is the GraphQL Wire Adapter

It is a wire adapter from the lightning/uiGraphQLApi module. You import two things, a tag function called gql and the adapter itself called graphql.

import { LightningElement, wire } from 'lwc';
import { gql, graphql } from 'lightning/uiGraphQLApi';

Then you build a query as a template string and wire it.

export default class CourseList extends LightningElement {
  courses = [];

  query = gql`
    query courses {
      uiapi {
        query {
          Course__c(first: 10) {
            edges {
              node {
                Id
                Name { value }
                Fee__c { value displayValue }
              }
            }
          }
        }
      }
    }
  `;

  @wire(graphql, { query: '$query' })
  handleResult({ data, errors }) {
    if (data) {
      this.courses = data.uiapi.query.Course__c.edges.map(e => e.node);
    }
  }
}

Three things in that shape surprise people the first time. Fields come back as objects with a value and often a displayValue. Records sit under edges and node. And the whole thing is nested under uiapi and query.

Why Fields Have value and displayValue

A currency field has a raw number and a formatted string. A picklist has an API name and a label. A lookup has an id and a record name. The GraphQL Wire Adapter gives you both, so you never format a value twice.

Field typevaluedisplayValue
Currency4500INR 4,500.00
Date2026-03-011 March 2026
PicklistAdvancedAdvanced
LookupThe record idThe record name

Why the GraphQL Wire Adapter Matters

BenefitWhat it saves you
No ApexNo class, no test class, no deployment for a read
Smaller payloadsOnly the fields the screen shows
Platform securitySharing and field level security applied for you
Built in cachingRepeat views served without a round trip
One call, several objectsRelated data in a single request

That last point is the one teams feel most. A dashboard that needed three Apex calls can often become one query. If you are weighing this against a normal Apex call, the post on wire and imperative calls sets out both styles.

Filtering, Sorting and Paging

A query with no filter is rarely useful, and the GraphQL Wire Adapter gives you three tools for that. The GraphQL Wire Adapter takes a where argument, an orderBy argument, and cursor based paging.

Course__c(
  where: { Fee__c: { gt: { value: 3000 } } }
  orderBy: { Name: { order: ASC } }
  first: 20
) {

To pass a value from the component, build the query with a variable and declare it.

get query() {
  return gql`
    query courses($level: String) {
      uiapi { query { Course__c(where: { Level__c: { eq: $level } }) {
        edges { node { Id Name { value } } }
      } } }
    }
  `;
}

@wire(graphql, { query: '$query', variables: '$variables' })
results;

get variables() {
  return { level: this.selectedLevel };
}

The getter matters. When selectedLevel changes, the variables getter returns a new object, the wire refires, and fresh records arrive. No manual refresh needed.

Paging Through Results

The GraphQL Wire Adapter uses cursor paging. Ask for pageInfo alongside the edges and keep the cursor.

pageInfo { hasNextPage endCursor }

Pass the cursor back as the after argument for the next page. This is why the shape uses edges and nodes, since each edge can carry its own cursor.

GraphQL Wire Adapter vs Apex SOQL

GraphQL Wire Adapter and Apex SOQL comparison diagram

Caption: Read only screens lean one way, and anything with logic or DML leans the other.

The GraphQL Wire Adapter is not the winner everywhere. Aggregates in particular are still easier with SOQL aggregate functions. The honest rule is that a read only screen belongs to the GraphQL Wire Adapter, and anything that writes, calculates or joins awkwardly belongs in Apex.

NeedPick
Show a list of records with chosen fieldsGraphQL wire
Filter on a user selectionGraphQL wire
Aggregate with GROUP BY and HAVINGApex
Insert, update or deleteApex
Call an outside systemApex
Complex multi object logicApex
Reuse the same read in Flow and ApexApex

A Real GraphQL Wire Adapter Example

Our Bright Path Tutors org needed a course browser. The screen shows name, fee, duration and level, with a level picker at the top. The original build used an Apex class with a dynamic SOQL string and a test class.

We replaced it with one query inside the component. The results were easy to measure.

MeasureApex versionGraphQL version
Apex classes to maintain20
Fields returned114
Security code written by us14 lines0
Deployment needed for a field changeYesNo, edit the component

The field change point is the quiet win. When marketing asked to show the start date, we added one line to the query. No Apex, no test, no sharing check to rewrite.

Limits and Things to Watch

  • The adapter is read only, so every write still goes through Apex or a record form
  • Aggregates are limited, so counts and sums are often better in Apex
  • The nesting depth is capped, so very deep relationship chains fail
  • Errors arrive in an errors array rather than as a thrown exception
  • Custom metadata and some objects are not available through the UI API
  • A query that asks for a field the user cannot see returns null, not an error

That last behaviour is worth repeating. Field level security is applied silently, so a blank column on one user’s screen is a permission problem and not a bug in your query. The post on field level security covers where those checks come from.

Handling Errors Properly

@wire(graphql, { query: '$query' })
handleResult({ data, errors }) {
  this.error = errors ? errors[0].message : undefined;
  this.courses = data
    ? data.uiapi.query.Course__c.edges.map(e => e.node)
    : [];
}

The GraphQL Wire Adapter can return a partial answer, so always read both keys. A partial result can arrive with data and errors together, and ignoring the errors array hides the reason a column is empty.

Common Mistakes with the GraphQL Wire Adapter

MistakeWhat you seeFix
Reading the field directlyundefined instead of a numberRead the value property
Forgetting edges and nodeA type error on mapWalk edges then node
Inline variables objectThe wire never refiresReturn it from a getter
Ignoring the errors arraySilent blank columnsRead data and errors together
Asking for every fieldLarge payloads and slow screensList only what the screen shows
Expecting a write to workNothing savesUse a record form or Apex

Best Practices for the GraphQL Wire Adapter

  • List only the fields the screen actually renders
  • Build the query in a getter when any part of it depends on component state
  • Return variables from a getter so changes refire the wire
  • Keep paging cursors in a property rather than recomputing them
  • Read data and errors in the same handler, every time
  • Keep writes in Apex or a record form and reads in the query
  • Name the query so it is easy to find in the network tab

Most Asked GraphQL Wire Adapter Interview Questions

Q1: Which module gives you the GraphQL Wire Adapter?

The lightning/uiGraphQLApi module, which exports gql and graphql.

Q2: What does gql do?

It is a tag function that turns your template string into a query the adapter can send.

Q3: Why are records nested under edges and node?

That is the connection pattern, which lets each record carry a cursor for paging.

Q4: Why does a field have value and displayValue?

The value is raw data and the displayValue is formatted for the user locale.

Q5: Is the GraphQL Wire Adapter read only?

Yes. Writes go through a record form, the record API or Apex.

Q6: Does it apply sharing rules?

Yes. The platform applies sharing, object permissions and field level security on the server.

Q7: What happens when a user cannot see a requested field?

The field returns null rather than an error, so a blank column often means a permission gap.

Q8: How do you pass a filter value from the component?

Declare a query variable, then return the variables object from a getter.

Q9: Why must variables come from a getter?

A getter returns a new object when state changes, which is what makes the wire refire.

Q10: How do you sort results?

With the orderBy argument on the object, naming the field and the order.

Q11: How do you page through a long list?

Request pageInfo, keep the endCursor, and pass it back as the after argument.

Q12: How do you limit the number of records?

With the first argument on the object.

Q13: Where do errors arrive?

In an errors array on the wire result, alongside any partial data.

Q14: Can a single query read two objects?

Yes. Add both under the query block, which is one of the strongest reasons to use it.

Q15: When is Apex still the better choice?

For writes, aggregates, outside callouts, and logic you want to reuse in Flow.

Q16: Does the GraphQL Wire Adapter cache results?

Yes. It uses the same client cache as other UI API wire adapters.

Q17: How do you force fresh data?

Refresh the wire with refreshApex or change a variable so the wire refires.

Q18: Scenario: the list never updates when the picker changes. What is wrong?

The variables object is probably a plain field rather than a getter, so the wire sees no change.

Q19: Scenario: map throws an error on the result. What did you miss?

The edges level. Walk data.uiapi.query.Object.edges and then take each node.

Q20: Scenario: one user sees a blank fee column and another does not. Why?

Field level security on the fee field, since the platform returns null instead of refusing the query.

Q21: Can you query custom metadata types this way?

Not generally, since the UI API does not expose every object. Check before you design around it.

Q22: Does it work in Experience Cloud sites?

Yes, with guest access depending on the site profile and sharing settings.

Q23: How deep can relationship nesting go?

There is a documented depth cap, so very long chains fail and need a different design.

Q24: Is there a test class to write?

No, which is part of the appeal. Component level Jest tests still make sense.

Q25: How does the payload compare with a wire call to getRecord?

Usually smaller, since getRecord returns a fixed shape and this returns only what you asked for.

Q26: What is a good first project for it?

A read only list or detail panel that currently uses an Apex method with one simple SOQL query.

Q27: How do you debug a failing query?

Log the errors array, then check the object and field API names and the nesting shape.

Q28: What is the one habit that prevents most problems?

Ask for the fewest fields the screen needs, and read both data and errors in the handler.

Official Resources

What Is Next

Next, read LWC Dynamic Components Explained with Real Examples.