Skip to main content

Your First Query

If you have not used GraphQL before, this page is the short version: you describe the shape of the response you want, and that is the shape you get.

Ask for one verse​

query {
  verse(translation: "eng-web", book: "JHN", chapter: 3, verse: 16) {
    bookName
    chapter
    verse
    text
  }
}

Note book: "JHN". The canonical three-letter id works in every translation. A localized name such as "Juan" works too, as long as it matches the translation you are querying.

Ask for more fields​

Fields are free to add — nothing comes back unless you request it, and nothing is hidden if you do. Adding bookId to the previous query returns it alongside the rest; removing text stops the verse text being sent at all.

That is the main practical difference from a REST API: response size is your decision, not the server's.

Ask for a whole chapter​

query {
  chapter(translation: "eng-web", book: "JHN", chapter: 3) {
    verse
    text
  }
}

chapter returns a list of verses. Every list field in the schema behaves the same way — you select the fields you want on each element.

Nest through relationships​

Types connect to each other, so one request can cross several levels:

query {
  translation(identifier: "eng-web") {
    name
    books {
      bookId
      name
      chapterCount
    }
  }
}

That returns the translation plus every book with its chapter count, in one round trip.

Nesting has limits

Queries are capped at depth 15 and complexity 300. A deeply nested query — for example every chapter and every verse of every book — will be rejected rather than served slowly. Use bibleIndex for structure, then fetch the text you actually need.

Use variables instead of string interpolation​

Once a query lives in application code, pass values as variables rather than building the document with string concatenation:

query GetPassage($translation: String!, $reference: String!) {
  passage(translation: $translation, reference: $reference) {
    reference
    text
  }
}
{
  "translation": "eng-web",
  "reference": "John 3:16"
}

Send them as the variables key beside query in the POST body. This keeps the document static and cacheable, and avoids quoting bugs.

Name your operations​

query GetPassage(...) above is a named operation. Names cost nothing and make server logs and client tooling far easier to read. Anonymous query { ... } is fine for exploration.

Next​