Elasticsearch Ruby Client

The elasticsearch-rails gem provides specialized features for integrating Elasticsearch into Ruby on Rails applications. Key capabilities include:

• Data Import: Rake tasks to facilitate importing data directly from your Rails application models into Elasticsearch.
• Instrumentation: Integration with the Rails instrumentation framework for monitoring and observability.
• Scaffolding: Templates for generating fully working example Rails applications to help you get started with the integration.

If you are using a 7.x client with an 8.x Elasticsearch server, you can enable compatibility mode to ensure a smoother upgrade.

For 7.x clients, set the environment variable ELASTIC_CLIENT_APIVERSIONING to true.

For all 8.0+ clients, compatibility mode is enabled by default.

By default, the client uses a round-robin strategy. You can implement your own strategy by including Elastic::Transport::Transport::Connections::Selector::Base and defining a select method. This allows for advanced logic like rack-awareness.

class RackIdSelector
  include Elastic::Transport::Transport::Connections::Selector::Base

  def select(options={})
    connections.select do |c|
      # Try selecting the nodes with a `rack_id:x1` attribute first
      c.host[:attributes] && c.host[:attributes][:rack_id] == 'x1'
    end.sample || connections.to_a.sample
  end
end

Elasticsearch::Client.new hosts: ['x1.search.org', 'x2.search.org'], selector_class: RackIdSelector

The elasticsearch-persistence RubyGem provides a persistence layer for Ruby domain objects using the repository design pattern. By including the Elasticsearch::Persistence::Repository module in a class, you can implement a repository that handles saving, deleting, finding, and searching objects in Elasticsearch.

Key capabilities include:

• Accessing the underlying Elasticsearch client.
• Configuring index names, document types, and object classes for deserialization.
• Managing index mappings and settings.
• Performing CRUD operations (create, delete, find) and searches.
• Accessing both domain objects and raw Elasticsearch hits/responses.
• Defining custom serialization and deserialization logic.

The elasticsearch-api library is a specialized component that provides a Ruby implementation of the Elasticsearch REST API.

Important distinctions:

• elasticsearch-api: Provides the API definitions/implementation but does not provide an Elasticsearch client.
• elasticsearch: The full Elasticsearch client package (which includes elasticsearch-api).
• elastic-transport: The HTTP transport layer used by the client.

If you want a functional Elasticsearch client to interact with a cluster, you should use the elasticsearch gem rather than using elasticsearch-api standalone.

The elasticsearch gem includes several advanced capabilities for managing cluster communication:

• Pluggable components: You can customize logging, tracing, connection selection strategies (such as round-robin or random), transport implementations, and serializer implementations.
• Resilience: Supports request retries, dead connection handling, and node reloading (based on cluster state) triggered by errors or on demand.
• API Coverage: Features a modular API implementation with 100% coverage of the Elasticsearch REST API.

The Elasticsearch Ruby client follows these compatibility rules:

• Ruby Versions: The client is compatible with all currently maintained Ruby versions.
• Forward Compatibility: Clients are forward compatible, meaning a client can communicate with greater or equal minor versions of Elasticsearch (e.g., an 8.12 client can talk to an 8.13 server). However, the client will not automatically support new features introduced in newer server versions; you must upgrade the client to access them.
• Backward Compatibility: Clients are only backwards compatible with default distributions, and there are no guarantees for other configurations.

Version Mapping Reference

The client follows Ruby's maintenance policy, supporting all currently maintained Ruby versions.

Version Compatibility:

• Forward Compatibility: The client supports communicating with greater minor versions of Elasticsearch.
• Backward Compatibility: The client is backward compatible with lesser supported minor versions of Elasticsearch.

The test runner processes YAML files by loading them into TestFile objects. Each file contains multiple TaskGroup objects.

• TaskGroup: A block of actions consisting of a do action (the request) and subsequent match actions (the verifications).
• Action: The component that executes the client method defined in the do block and saves the response for verification.
• Lifecycle: Before each test, the runner calls clear_data (clearing indices, templates, etc.). After each test, it runs the file's teardown and clear_data again.

Example TaskGroup structure:

 - do:
      index:
          index:  test-index
          id:     1
          body:   { foo: bar }

 - match:   { _index:   test-index }
 - match:   { _id:      "1"}
 - match:   { _version: 1}