Lists

GraphQL has list types which are ordered lists containing items of other types. The following examples use the GraphQL Schema Definition Language (SDL).

Fields may return a single scalar value (eg String), or a list of scalar values (eg, [String], a list of strings):

type Spy {
  # This spy's real name
  realName: String!
  # Any other names that this spy goes by
  aliases: [String!]
}

Fields may also return lists of other types as well:

enum PostCategory {
  SOFTWARE
  UPHOLSTERY
  MAGIC_THE_GATHERING
}

type BlogPost {
  # Zero or more categories this post belongs to
  categories: [PostCategory!]
  # Other posts related to this one
  relatedPosts: [BlogPost!]
}

Inputs may also be lists. Arguments can accept list types, for example:

type Query {
  # Return the latest posts, filtered by `categories`
  posts(categories: [PostCategory!]): [BlogPost!]
}

When GraphQL is sent and received with JSON, GraphQL lists are expressed in JSON arrays.

List Types in Ruby

To define a list type in Ruby use [...] (a Ruby array with one member, the inner type). For example:

# A field returning a list type:
# Equivalent to `aliases: [String!]` above
field :aliases, [String]

# An argument which accepts a list type:
argument :categories, [Types::PostCategory], required: false

For input, GraphQL lists are converted to Ruby arrays.

For fields that return list types, any object responding to #each may be returned. It will be enumerated as a GraphQL list.

To define lists where nil may be a member of the list, use null: true in the definition array, for example:

# Equivalent to `previousEmployers: [Employer]!`
field :previous_employers, [Types::Employer, null: true], "Previous employers; `null` represents a period of self-employment or unemployment" null: false

Lists, Nullable Lists, and Lists of Nulls

Combining list types and non-null types can be a bit tricky. There are four possible combinations, based on two parameters:

Nullability of the field: can this field return null, or does it always return a list?
Nullability of the list items: when a list is present, may it include null?

Here’s how those combinations play out:

(The first line is GraphQL-Ruby code. The second line, beginning with # =>, is the corresponding GraphQL SDL code.)

Let’s look at some examples.

Non-null lists with non-null items

Here’s an example field:

field :scores, [Integer], null: false
# In GraphQL,
#   scores: [Int!]!

In this example, scores may not return null. It must always return a list. Additionally, the list may never contain null – it may only contain Ints. (It may be empty, but it cannot have null in it.)

Here are values the field may return:

Valid	Invalid
`[]`	`null`
`[1, 2, ...]`	`[null]`
	`[1, null, 2, ...]`

Non-null lists with nullable items

Here’s an example field:

field :scores, [Integer, null: true], null: false
# In GraphQL,
#   scores: [Int]!

In this example, scores may not return null. It must always return a list. However, the list may contain nulls and/or Ints.

Here are values the field may return:

Nullable lists with nullable items

Here’s an example field:

field :scores, [Integer, null: true]
# In GraphQL,
#   scores: [Int]

In this example, scores return null or a list. Additionally, the list may contain nulls and/or Ints.

Here are values the field may return:

Nullable lists with non-null items

Here’s an example field:

field :scores, [Integer]
# In GraphQL,
#   scores: [Int!]

In this example, scores return null or a list. However, if a list is present, it may not contain null – only Ints.

Here are values the field may return: