⚠ New Class-Based API ⚠

This describes a new API in v1.8.0. Check the upgrade notes for more info.

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], null: true

# 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:

Here’s how those combinations play out:

  nullable field non-null field
nullable items [Integer, null: true], null: true
# => [Int]
[Integer, null: true], null: false
# => [Int]!
non-null items [Integer], null: true
# => [Int!]
[Integer], null: false
# => [Int!]!

(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:

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

Nullable lists with nullable items

Here’s an example field:

field :scores, [Integer, null: true], 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:

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

Nullable lists with non-null items

Here’s an example field:

field :scores, [Integer], null: true
# 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:

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