Constrain domain values
Model a field with a small, closed set of valid outcomes such as an episode, status, or category.
GraphQL · Const
enum
GraphQL enums are scalar-like leaf types constrained to a finite set of named values. They validate enum arguments and describe the possible values a field can return.
How it works
An enum is a leaf type whose values are limited to a finite, explicitly declared set. The schema uses an enum declaration to define those values, and clients use the unquoted names wherever that enum type is expected.
Syntax
enum TypeName {
VALUE_A
VALUE_B
}Returns
A named value from the enum's declared finite set.
Key points
- Enums belong to the scalar category, but unlike ordinary scalars they constrain values to named members.
- Every enum declaration establishes the complete set of values accepted for that type.
- Enum-typed arguments receive schema validation against the declared members.
- A field's enum type tells clients which finite outcomes the field may expose.
- Enum fields terminate selections and cannot contain nested field selections.
- The enum's declaration controls the legal values everywhere that enum type is referenced.
Example: Defining and using an enum
enum Episode {
NEWHOPE
EMPIRE
JEDI
}
query {
hero(episode: JEDI) {
name
}
}The schema defines the allowed episode values, and the query supplies one enum value without quotes.
When to use it
Validate inputs
Expose valid argument choices directly through the schema so invalid names are rejected during validation.
Describe output contracts
Help clients understand the finite set of values a field may return.
Interview questions
QWhat is a GraphQL enum, and why use one?
An enum is a special scalar restricted to a defined set of values. It communicates that a field can produce only one member of that finite set and lets GraphQL validate enum arguments.
Follow-up: What kind of value does an enum represent internally? The documentation distinguishes enum values from numeric references: they are unique values that may serialize using their names.
QHow are enum values written in a query?
Enum values are written as unquoted names because the expected enum type is already known from the schema. For example, a query can pass JEDI rather than the string "JEDI".
Follow-up: Why is the enum type name omitted at the use site? The surrounding argument or field type supplies the precise enumeration context.
QHow do enums participate in query execution?
Enums are leaf values, so GraphQL queries end when they reach an enum field; clients do not select subfields from an enum. The server must return one of the values declared for that enum.
Follow-up: How can a server map an enum to internal data? Execution can coerce an internal representation, such as a number, into the schema's expected enum value.
Related
Scalar typesSchema definition languageField argumentsExecutionIntrospection