Ruby client library for accessing the Typesense HTTP API.

Follows the API spec here.

Add this line to your application's Gemfile:

gem 'typesense'

And then execute:

$ bundle

Or install it yourself as:

$ gem install typesense

You'll find detailed documentation here: https://typesense.org/api/

Here are some examples with inline comments that walk you through how to use the Ruby client: examples

Tests are also a good place to know how the the library works internally: spec

Error responses from Typesense raise a subclass of Typesense::Error. The exception's message is the message from the API response, and the underlying Faraday response is available as e.data[:response] if you need the HTTP status, headers, or raw body:

begin
  client.collections['unknown'].retrieve
rescue Typesense::Error::ObjectNotFound => e
  e.message                 # => "Not Found"
  e.data[:response].status  # => 404
  e.data[:response].body    # => raw response body
end

Status codes map to these classes: RequestMalformed (400), RequestUnauthorized (401), ObjectNotFound (404), ObjectAlreadyExists (409), ObjectUnprocessable (422), ServerError (5xx), HTTPStatus0Error (status 0), and HTTPError (any other non-2xx status).

5xx responses and network errors are retried first. Once retries run out, the last error is re-raised, so a network failure surfaces as the original Faraday or Errno exception rather than a Typesense::Error.

By default, the client opens a fresh HTTP connection (and TLS handshake) for every request. For high-traffic applications this can dominate request latency. Setting keep_alive_connections: true enables persistent connections via the :net_http_persistent Faraday adapter:

Typesense::Client.new(
  api_key: ENV['TYPESENSE_API_KEY'],
  nodes: [{ host: 'localhost', port: 8108, protocol: 'https' }],
  connection_timeout_seconds: 3,
  num_retries: 1,
  keep_alive_connections: true
)

Notes:

• Connections are cached per (thread, node). Net::HTTP is not thread-safe, so each thread maintains its own keep-alive socket to each Typesense node, and the existing node round-robin still works.
• A cached connection is dropped automatically when a network error occurs, so retries open a fresh socket. We recommend setting num_retries to at least 1 so the gem can recover from a server- or load-balancer-side idle timeout transparently.
• Idle sockets are closed after 30 seconds by default. Override with keep_alive_idle_timeout_seconds to match or stay under your load balancer's idle timeout.
• The underlying net_http_persistent adapter holds at most keep_alive_pool_size sockets per origin (default 1, which matches the per-(thread, node) cache above). The default of 1 is the safe choice for the vast majority of users — because we already cache one Faraday connection per (thread, node) and Net::HTTP is not thread-safe, a single socket per pool is all the adapter needs. Only raise this if you have a specific reason to keep additional sockets warm per origin (e.g. a non-standard concurrency model layered on top of this client); a larger pool will not increase request throughput on its own.
• keep_alive_idle_timeout_seconds and keep_alive_pool_size are only valid when keep_alive_connections: true; setting them otherwise raises Typesense::Error::MissingConfiguration.
• The option defaults to false, so upgrading the gem does not change behaviour until you opt in.

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install.

To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Bug reports and pull requests are welcome on GitHub at typesense/typesense-ruby.