Fragment

Fragments are a bunch of fields grouped together that you can use over and over again.

The reason for using fragments is that sometimes you want to query a resource differently than you previously did. The different reasons may be for example:

  • bandwidth, on a low bandwidth you might want to opt for a version where you as for less columns than you would otherwise do on a better bandwidth
  • DRY, you might include the same resource as part of many queries and as soon as you add/remove a column you want to avoid having to alter all those queries

Bandwidth

As we said before our fragment is a grouping of columns. Let's create an example in which we create two different fragments:

  • light user, here we are only asking for a few columns, suitable for a low bandwidth scenario
  • full user, here we are asking for pretty much all the columns we can, at any depth
type Address {
  city: String;
  country: String;
  streetName: String;
  postalCode: String;
}

type User {
  name: String;
  password: String;
  address: Address;
}

type Query {
  User(id: Int): User;
}

fragment LightUser on User {
  name
}

fragment FullUser on User {
  name,
  password
  address {
    city,
    country
    streetName;
    postalCode;
  }
}

Above we have constructed the types Address and User to support the fragments we are about to create. Thereafter we construct the fragments LightUser and FullUser. As you can see they are not types but rather groups of columns that are meant to be part of a query.

Let's now construct some queries to show how we would put the fragments to good use :

{
  query MyUser($id: Int!) {
    User(id: $id) {
      ...LightUser
    }
  }

  query MyFullUser($id: Int!) {
    User(id: $id) {
      ...FullUser
    }
  }
}

Not how we above create the queries MyUser and MyFullUser and how we use our constructed directives LightUser and FullUser. We use the mentioned fragments by using the spread syntax .... So typing:

query MyFullUser($id: Int!) {
    User(id: $id) {
      ...FullUser
    }
  }

Is the same thing as typing:

query MyUser($id: Int!) {
    User(id: $id) {
      name,
      password
      address {
        city,
        country
        streetName;
        postalCode;
      }
    }
}

As you can see we save quite a few typed characters by defining our fragment once and then take them in use in whatever query we have.

DRY - don't repeat yourself

We might have a situation where you have taken your fragment in use in several different places. Let's show such a situation:

query MyOrder {
  details {
    createdAt,
    sum,
    user: {
      ...FullUser
    }
  }
}

query BlogPosts {
  content,
  title:
  createdBy {
    ...FullUser    
  }
}

Above we now have the queries MyOrder and BlogPosts and we can see we are using the fragment FullUser in both these queries. Imagine now that we add a column createdAt to the User type and we want to ensure both of our queries pick up on that change. All we have to do is to alter the fragment like so:

fragment FullUser on User {
  name,
  password,
  createdAt
  address {
    city,
    country
    streetName;
    postalCode;
  }
}

Summary

We have talked about fragments, what they are and how to use them. We have also discussed when and how to use them and how it can save quite a few keystrokes

results matching ""

    No results matching ""