A modular Ruby client library for hlquery, designed with a familiar and intuitive API structure.

What is the hlquery Ruby API?

The hlquery Ruby API is the official Ruby client for hlquery. It mirrors the practical endpoint coverage of the other hlquery clients while exposing Ruby-style method names and service objects.

It is intended for scripts, services, internal tools, and apps that want a small Ruby wrapper over hlquery's HTTP interface.

Why use it?

Use it when you want a cleaner Ruby interface than hand-written Net::HTTP calls, with consistent auth, params, parsed response handling, and coverage for collections, documents, search, and custom route access.

Install

Local usage:

$LOAD_PATH.unshift(File.expand_path("lib", __dir__))
require "hlquery"

Client initialization:

client = Hlquery::Client.new(ENV["HLQ_BASE_URL"] || ENV["HLQUERY_BASE_URL"] || "http://localhost:9200")

Quick Start

$LOAD_PATH.unshift(File.expand_path("lib", __dir__))
require "hlquery"

client = Hlquery::Client.new("http://localhost:9200")

health = client.health
puts "status: #{health.body["status"] || "ok"}" if health.success?

collections = client.list_collections(0, 10)
puts collections.body.inspect

Auth

client = Hlquery::Client.new("http://localhost:9200", {
  token: "your_token_here",
  auth_method: "bearer"
})

client.set_auth_token("your_token_here", "bearer")
client.set_auth_token("your_api_key_here", "api-key")

SAM

If your current Ruby client build includes the SAM helper, use it directly. Otherwise use the raw request helper against the SAM endpoints:

SAM is separate from vector search. It performs term and intent-style lookup, not vector similarity search.

status = client.execute_request("GET", "/sam/status", nil, {
  collection: "music"
})

history = client.execute_request("GET", "/sam/history", nil, {
  collection: "music",
  limit: 5
})

results = client.execute_request("GET", "/sam/search", nil, {
  collection: "music",
  q: "queen of pop",
  limit: 10
})

Search

results = client.search("products", {
  "q" => "waterproof jacket",
  "limit" => 10
})

If q is set and query_by is omitted, the client tries to infer query_by from the collection's searchable_fields.

Contributing

We welcome contributions from the community! All contributions must be released under the BSD 3-Clause license.

How to Contribute

• Check existing issues or create new ones
• Contribute to client libraries (Node.js, Go, Java, Python, PHP, Ruby, Rust, Perl, C++)
• Test and report bugs
• Improve documentation

Community

• 📖 Documentation
• 🐦 X (Twitter)
• 📦 GitHub

License

hlquery is licensed under the BSD 3-Clause License.