Fields

Fields are the basic building block of GraphQL data.

Objects and interfaces are composed of fields. Queries and mutations are a special kind of field.

Fields are functions. Or, more specifically, fields are a kind of operation that begins with some data, adds in other details (such as field arguments provided in the query), and produces new data that can be incorporated into the overall result.

Field Definition

A field definition occurs in the schema to describe the type and other details of a field. A field definition is a map with specific keys.

Field Type

The main key in a field definition is :type, which is required. This is the type of value that may be returned by the field resolver, and is specified in terms of the type DSL.

Types DSL

Types are the essence of fields; they can represent scalar values (simple values, such as string or numbers), composite objects with their own fields, or lists of either scalars or objects.

In the schema, a type can be:

  • A keyword corresponding to an object, interface, enum, or union
  • A scalar type (built in, or schema defined)
  • A non-nillable version of any of the above: (non-null X)
  • A list of any of the above: (list X)

The built-in scalar types:

  • String
  • Float
  • Int
  • Boolean
  • ID

Field Resolver

The :resolve key identifies the field resolver function, used to provide the actual data.

This data, the resolved value, is never directly returned to the client; this is because in GraphQL, the client query identifies which fields from the resolved value are selected (and often, renamed) to form the result value.

:resolve is optional; when not provided it is assumed that the containing field’s resolved value is a map containing a key exactly matching the field’s name.

A field resolver function may be provided on a field inside an object definition, or inside a query definition or mutation definition. No field resolver function should be provided in the fields of an interface definition: if provided in an interface definition, the resolve will be silently ignored.

The field’s resolver is passed the resolved value of the containing field, object, query, or mutation.

The return value may be a scalar type, or a structured type, as defined by the field’s :type.

For composite (non-scalar) types, the client query must include a nested set of fields to be returned in the result map. The query is a tree, and the leaves of that tree will always be simple scalar values.

Arguments

A field may define arguments using the :args key; this is a map from argument name to an argument definition.

A field uses arguments to modify what data, and in what order, is to be returned. For example, arguments could set boundaries on a query based on date or price, or determine sort order.

Argument definitions define a value for :type, and may optionally provide a :description. Arguments do not have resolvers, as they represent explicit data from the client passed to the field.

Arguments may also have a :default-value. The default value is supplied to the field resolver when the request does not itself supply a value for the argument.

An argument that is not specified in the query, and does not have a default value, will be omitted from the argument map passed to the field resolver.

Description

A field may include a :description key; the value is a string exposed through Introspection.

Deprecation

A field may include a :deprecation key; this identifies that the field is deprecated.