Conditional Field Fetching in GraphQL with @include and @skip Directives

When a UI toggle decides what data you really need

Imagine a mobile screen that shows a user’s name and email by default, but reveals a lengthy biography and a list of social links only after the user taps “Show more”. Fetching those heavy fields every time wastes bandwidth and forces the server to do work that may never be used. Conversely, making a second request after the tap adds latency and a noticeable loading state.

GraphQL lets you move that toggle logic into the query itself using the built‑in @include and @skip directives. By attaching a boolean variable to a field, you tell the server: “Only resolve this field if the variable meets the condition.”

How the directives work

Both directives are part of the GraphQL specification and are implemented in servers such as Apollo Server, GraphQL‑Java, and others. They take a single argument if: that must resolve to a boolean.

• @include(if: $flag) – the field is returned only when $flag evaluates to true.
• @skip(if: $flag) – the field is omitted when $flag evaluates to true (i.e., it is included when the flag is false).

The evaluation happens before the field’s resolver runs. If a field is skipped, the server never invokes the resolver, so the savings occur both on the wire and in backend work.

Worked example: a profile query with optional details

Suppose a client wants the user’s basic info plus an optional biography and social‑links list that should appear only when a UI variable $showDetails is true.

query GetUserProfile($userId: ID!, $showDetails: Boolean!) {
  user(id: $userId) {
    username
    email
    # Included only when $showDetails is true
    biography @include(if: $showDetails)
    # Included only when $showDetails is false (opposite of biography)
    summary @skip(if: $showDetails)

    socialLinks @include(if: $showDetails) {
      platform
      url
    }
  }
}

To try this, send the query to your GraphQL endpoint (e.g., via Apollo Studio, GraphiQL, or curl) and provide the variables:

• { "userId": "1", "showDetails": false }
• { "userId": "1", "showDetails": true }

If the server follows the spec, the JSON response will contain:

Variable showDetails	Fields present in response
false	username, email, summary
true	username, email, biography, socialLinks

Note that omitted fields are absent from the object entirely; they are not present as null. To verify, inspect the response keys after each request. If a field you expect to be skipped still appears, check that the variable was passed correctly and that the server’s directive implementation matches the spec (some servers limit the expression to literals; consult your server’s documentation for exact syntax).

Trade‑offs and practical limits

While useful, directives add runtime indirection that can affect tooling:

• Static analysis: Because the final shape depends on variable values, some IDE features or query‑cost estimators may not predict the exact payload size.
• Debugging opacity: A missing field could be due to a resolver error, a permission issue, or a directive condition. You must check both the variable state and the directive expression to understand why.
• Complex expressions: Nesting many directives or using complicated JavaScript‑style expressions (as Apollo Server allows) can make queries harder to read. If you find yourself chaining several conditions, consider splitting the request into two separate queries.

On the positive side, the server skips resolver execution for omitted fields, so you save both bandwidth and backend work when the condition is false.

Actionable steps to adopt conditional fetching

1. Identify fields that are large (e.g., long text, nested lists) and not always needed in the UI.
2. Replace static inclusion of those fields with @include(if: $flag) or @skip(if: $flag) where $flag reflects the UI state.
3. Pass the boolean UI state as a variable when you execute the query from your client.
4. Confirm the result by checking that the field’s key is missing from the JSON when the condition evaluates to false; if it is present, review variable passing and server directive support.