Esse Documentation

Esse is a pure Ruby, framework-agnostic ElasticSearch/OpenSearch client gem that provides an ETL (Extract, Transform, Load) architecture for managing search indices.

It is built on top of the official elasticsearch-ruby and opensearch-ruby clients.

Documentation Index

Core Concepts

Ecosystem

See extensions.md for the complete list.

Architecture Overview

Esse is structured around three core components that form an ETL pipeline:

Collection (yields batches of raw objects)
       ↓
Repository (serializes batches → Documents)
       ↓
Import pipeline (builds bulk requests with retries)
       ↓
Transport (sends bulk to ES/OS)

Core Components

• Index (Esse::Index) — defines settings, mappings, aliases, and orchestrates operations.
• Repository (Esse::Repository) — declares collection and document, one index may have many.
• Document (Esse::Document) — a single indexable document with id, type, routing, source, meta.

Supporting Components

• Cluster — ES/OS client connections, index prefix, readonly mode.
• Transport — wraps the official client with consistent error handling.
• Search — query DSL builder with response wrapping and scroll support.
• Events — pub/sub instrumentation for every ES/OS operation.
• CLI — Thor-based CLI (esse install, esse generate, esse index *).
• Plugins — extension system loaded via plugin :name.

Quick Example

Esse.configure do |config|
  config.cluster(:default) do |cluster|
    cluster.client = Elasticsearch::Client.new(url: ENV['ELASTICSEARCH_URL'])
  end
end

# app/indices/users_index.rb
class UsersIndex < Esse::Index
  settings do
    { index: { number_of_shards: 2, number_of_replicas: 1 } }
  end

  mappings do
    { properties: {
        name:  { type: 'text' },
        email: { type: 'keyword' }
      } }
  end

  repository :user do
    collection do |**ctx, &block|
      User.find_in_batches(batch_size: 1000) { |batch| block.call(batch, ctx) }
    end

    document do |user, **|
      { _id: user.id, name: user.name, email: user.email }
    end
  end
end

# Use:
UsersIndex.create_index(alias: true)
UsersIndex.import
UsersIndex.search(q: 'john').results

Version

Current version: 0.4.0

Requires Ruby >= 2.7 and one of:

• elasticsearch (any version from 1.x to 8.x)
• opensearch (any version from 1.x to 2.x)

License

MIT — see LICENSE.txt.