Document

Similar to how a JSON file or string is called a “JSON document”, a GraphQL file or string is called a GraphQL document. There are two types of GraphQL documents—executable documents and schema documents. In this chapter, we’ll mainly be discussing executable documents, and we’ll cover schema documents in Chapter 3. An executable document is a list of one or more operations or fragments. This document has a single query operation:

query {
  githubStars
}

Our operation has a single root field, githubStars. In this type of document—a single query operation without variables or directives—we can omit query, so the above document is equivalent to:

{
  githubStars
}

A more complex document could be:

query StarsAndChapter {
  githubStars
  chapter(id: 0) {
    title
  }
}

mutation ViewedSectionOne {
  viewedSection(id: "0-1") {
    ...sectionData
  }
}

mutation ViewedSectionTwo {
  viewedSection(id: "0-2") {
    ...sectionData
  }
}

fragment sectionData on Section {
  id
  title
}

subscription StarsSubscription {
  githubStars
}

It has all the operation types as well as a fragment. Note that when we have more than one operation, we need to give each a name—in this case, StarsAndChapter, ViewedSection*, and StarsSubscription.