Skip to main content

Ruby

An idiomatic Ruby client for BibleQL.

Install​

Gemfile
gem "bibleql-ruby"
bundle install

Or directly:

gem install bibleql-ruby

Configure​

require "bibleql"

BibleQL.configure do |config|
  config.api_key = ENV.fetch("BIBLEQL_API_KEY")
  config.api_url = "https://bibleql.org/graphql"
  config.default_translation = "eng-web"
end

client = BibleQL.client

Or per instance, which is easier to test:

client = BibleQL::Client.new(
  api_key: ENV.fetch("BIBLEQL_API_KEY"),
  api_url: "https://bibleql.org/graphql",
  default_translation: "spa-rv1909"
)
Set api_url explicitly

The gem's built-in default points at a Render-hosted URL, not https://bibleql.org/graphql. Pin it if you want the canonical endpoint.

For where this belongs in a Rails app, using Rails credentials, and choosing between global and per-instance clients, see Configuring the SDKs.

The examples below all assume a client built as above.

Reading passages​

passage = client.passage("John 3:16")

passage.reference       # => "John 3:16"
passage.text            # => "For God so loved the world..."
passage.translation_id  # => "eng-web"
passage.verses          # => [#<BibleQL::Verse ...>]

Override the translation per call:

client.passage("Juan 3:16", translation: "spa-rv1909")

Verses and chapters​

verse = client.verse("MAT", 5, 3)
verse.book_name  # => "Matthew"
verse.chapter    # => 5
verse.verse      # => 3
verse.text

verses = client.chapter("MAT", 5)
results = client.search("love", limit: 5)

results.each do |verse|
  puts "#{verse.book_name} #{verse.chapter}:#{verse.verse}"
  puts verse.text
end

Remember this is substring matching, not stemming — see Searching the Bible.

Random verse​

client.random_verse
client.random_verse(testament: "NT")
client.random_verse(books: "PSA")

testament takes the strings "OT" and "NT". Passing books makes testament be ignored — see API Behavior.

Verse of the day​

client.verse_of_the_day
client.verse_of_the_day(date: "2026-01-01")

Returns a Passage, which may hold more than one verse.

Discovery​

client.translations           # => [#<BibleQL::Translation ...>]
client.translation("eng-web") # with .books
client.languages              # .code, .translation_count, .translations
client.books                  # canonical 66
client.bible_index            # .chapters => [#<BibleQL::Chapter number= verse_count=>]

Error handling​

begin
  client.passage("Nonexistent 1:1")
rescue BibleQL::NotFoundError => e
  warn "Not found: #{e.message}"
rescue BibleQL::AuthenticationError
  warn "Check BIBLEQL_API_KEY"
rescue BibleQL::RateLimitError
  warn "Rate limited — back off"
rescue BibleQL::TimeoutError, BibleQL::ConnectionError => e
  warn "Transient network problem: #{e.message}"
rescue BibleQL::QueryError => e
  warn "GraphQL error: #{e.message}"
  warn e.errors.inspect # the raw error array
end

BibleQL::ServerError covers 5xx responses. See Errors for what each maps to on the wire.

Not covered by the gem​

semanticSearch, concordance and concordanceIndex have no methods in the current release. Use the GraphQL documents from Semantic Search and Concordance with any HTTP client.