What do 3 dots/periods/ellipsis in a relay/graphql query mean?

Question

The relay docs contain this fragment:

query RebelsRefetchQuery {
  node(id: "RmFjdGlvbjox") {
    id
    ... on Faction {
      name
    }
  }
}

What does this ... on Faction on syntax mean?

Answer 1

There are two uses of ... related to fragments.

Incorporating a fragment by reference

query Foo {
  user(id: 4) {
    ...userFields
  }
}

fragment userFields on User {
  name
}

Has the effect of composing the fields from the fragment into the embedding query:

query Foo {
  user(id: 4) {
    name
  }
}

Note that fragments may compose other fragments.

Inline fragments

From the docs:

If you are querying a field that returns an interface or a union type, you will need to use inline fragments to access data on the underlying concrete type.

https://graphql.org/learn/queries/#inline-fragments

These can be used to compose fields in a type-dependent way. For example:

query Foo {
  profile(id: $id) {
    url
    ... on User {
      homeAddress
    }
    ... on Business {
      address
    }
  }
}

In this example, the server will determine whether to return the homeAddress or address field at runtime, based on whether the requested object is a User or a Business.