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:

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

Apollo iOS will generate a HeroNameQuery class with variables:

1class 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:):

1apollo.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>:

1class 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:

1.init(episode: .null)

1.init(episode: .none)

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

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

1let 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:

1query HeroName(
2  $episode: Episode! = .EMPIRE
3) {
4  hero(episode: $episode) {
5    name
6  }
7}

1class HeroNameQuery: GraphQLQuery {
2  ...
3
4  var episode: Episode
5
6  init(episode: Episode = .empire) {
7    self.episode = episode
8  }
9}

Note: This only applies for operation arguments defined by the client.

Default values for fields on Input Objects are defined by the schema, and not generated.