Operation Arguments

GraphQL operations can define arguments as part of their definitions, the values of these arguments can be passed to field arguments or directive arguments (eg. @skip and @include).

Apollo iOS generates type-safe initializers for your operation that accept your operation's arguments. These arguments can be built-in scalar types, custom scalars, enums, or input objects defined in your schema.

Let's say we define a GraphQL query named HeroName with an episode argument which is a custom Episode enum defined in our schema:

1
query HeroName($episode: Episode!) {
2
  hero(episode: $episode) {
3
    name
4
  }
5
}

Apollo iOS will generate a HeroNameQuery class with variables:

1
class HeroNameQuery: GraphQLQuery {
2
  ...
3

4
  var episode: Episode
5

6
  init(episode: Episode) {
7
    self.episode = episode
8
  }
9
}

Your HeroNameQuery will have a property for the episode variable, which will be passed to any field or directive arguments that use the $episode variable in the operation definition.

This query object can be initialized and passed to ApolloClient.fetch(query:):

1
apollo.fetch(query: HeroNameQuery(episode: .empire)) { result in
2
  guard let data = try? result.get().data else { return }
3
  print(data.hero.name) // Luke Skywalker
4
}

Working with nullable arguments

When defining an operation argument with a nullable value, Apollo iOS will wrap the generated argument's type in a generic GraphQLNullable wrapper enum.

According to the GraphQL spec, explicitly providing a null value for an input value to a field argument is semantically different from not providing a value at all (nil). This enum allows you to distinguish your input values between null and nil.

If the HeroName query is defined with a nullable episode argument, the generated HeroNameQuery will have an episode field with the type GraphQLNullable<Episode>:

1
class HeroNameQuery: GraphQLQuery {
2
  ...
3

4
  var episode: GraphQLNullable<Episode>
5

6
  init(episode: GraphQLNullable<Episode>) {
7
    self.episode = episode
8
  }
9
}

The HeroNameQuery can be initialized with a GraphQLNullable value:

.init(episode: .null)

.init(episode: .none)

.init(episode: .some(.empire))

Or with an optional value using the nil coalescing operator to provide a fallback.

1
let optionalEpisode: Episode?
2

3
.init(episode: optionalEpisode ?? .none)

For more usage information see the GraphQLNullable documentation.

Default values

When defining your operation's arguments, you may provide default values for the arguments. These default arguments will be included in your generated operation's initializer:

query HeroName(
  $episode: Episode! = .EMPIRE
) {
  hero(episode: $episode) {
    name
  }
}

class HeroNameQuery: GraphQLQuery {
  ...

  var episode: Episode

  init(episode: Episode = .empire) {
    self.episode = episode
  }
}