Purpose of @relay(pattern:true)

Question

New expression @relay(pattern: true) was introduced in change log for relay.js 0.5.

But can't figure out from description nor tests what exactly it does and when I should use it when writing fatQueries.

Some example would be very helpful.

Answer 1

Consider a GraphQL query like the following:

viewer {
  friends(first: 10) {
    totalCount
    edges { node { name } }
    pageInfo { hasNextPage }
  }
}

When defining a fat query for a Relay mutation, to include the name of a field without specifying any of its subfields tells Relay that any subfield of that field could change as a result of that mutation.

Unfortunately, to omit connection arguments such as find, first, and last on the friends field will cause a validation error on the connection-argument-dependent fields edges and pageInfo:

getFatQuery() {
  return Relay.QL`
    fragment on AddFriendMutationPayload {
      viewer { 
        friends { edges, pageInfo }  # Will throw the validation error below
      }
    }
  `;
}

// Uncaught Error: GraphQL validation/transform error ``You supplied the `pageInfo` 
// field on a connection named `friends`, but you did not supply an argument necessary 
// to do so. Use either the `find`, `first`, or `last` argument.`` in file 
// `/path/to/MyMutation.js`.

You can use the @relay(pattern: true) directive to indicate that want to use the fat query to pattern match against the tracked query, instead of to use it as a fully-fledged query.

getFatQuery() {
  return Relay.QL`
    fragment on AddFriendMutationPayload @relay(pattern: true) {
      viewer {
        friends { edges, pageInfo }  # Valid!
      }
    }
  `;
}

For more information about mutations see: https://facebook.github.io/relay/docs/guides-mutations.html#content