Toggle optional fields
A client needs optional profile data without maintaining separate query documents.
GraphQL · Directive
@skip
@skip conditionally omits a field or fragment when its Boolean if argument is true. It lets one query make optional selections controlled by a literal or runtime variable.
How it works
The built-in @skip directive conditionally excludes a field or fragment from query execution when its Boolean if argument is true. Clients can provide a literal or variable value, allowing one operation to request optional data without defining separate queries.
Syntax
@skip(if: Boolean)Parameters
| Name | Type | Description |
|---|---|---|
if | Boolean | Boolean condition that determines whether the annotated field is skipped. |
Returns
No value is returned by the directive itself; it controls whether the annotated selection contributes to query execution and results.
Key points
- @skip applies to an individual field or to a fragment inclusion in an executable operation.
- Its companion @include directive expresses the inverse condition: include a selection only when the Boolean is true.
- The selection is skipped whenever the directive's Boolean argument is true.
- Portable GraphQL clients can rely on these directives when communicating with specification-compliant servers.
Common mistakes
- A true if value omits the selected field or fragment from the result.
- @skip is a standard built-in directive, but a server must support it as part of GraphQL specification compliance.
Example: Conditionally skip a field
query GetUser($skipBio: Boolean!) {
user(id: "1") {
id
name
bio @skip(if: $skipBio)
}
}The variable controls whether the bio field is omitted from execution.
When to use it
Feature-gated selections
A feature flag determines whether experimental data should be requested.
Conditionally include fragment data
A fragment contains data relevant only for a particular runtime condition.
Interview questions
QWhat does @skip do?
@skip conditionally omits a field when its if argument evaluates to true. It is one of the two built-in executable directives that spec-compliant GraphQL servers must support.
Follow-up: How would you request the field only when a condition is true? Use @include(if: condition), which has the opposite inclusion behavior.
QHow is the skip condition supplied?
The directive takes a Boolean if argument and can be attached to a field or fragment inclusion. A variable is useful when the condition is supplied at runtime.
Follow-up: What happens when the variable is true? The annotated selection is skipped, so it is not included in the response data.
QShow a practical client query using @skip.
A client can place @skip on a field, such as bio, and pass a Boolean variable in the operation variables. The server then evaluates that condition during execution.
Follow-up: Why use this instead of separate query documents? It keeps one operation reusable while allowing optional selections to be controlled by runtime input.
Related
@includedirectivesfieldsfragment inclusion