Configuration

To get started, you need to create the configuration file with the elasticsearch/opensearch cluster connection information. You can use the CLI tool to generate the configuration file:

❯ esse install

You should see the following output:

      create  config/esse.rb

The config/esse.rb is the most common place for the esse configuration file. But the gem also recognizes the Essefile and config/initializers/esse.rb files. The priority order is:

1. Essefile
2. config/esse.rb
3. config/initializers/esse.rb

As the esse cli is a framework-agnostic tool, it doesn't know what dependencies are you using in your index classes. So, you should require the dependencies or bootstrap your application manually.

If you are using Rails, you should require the config/environment.rb file: (Note that esse-rails does this automatically plus a better logging and instrumentation)

# config/esse.rb
require_relative '../config/environment' unless defined?(Rails)

Esse.configure do |config|
  # ...
end

Global Configurations

• indices_directory= - The directory where the index classes are located. Default: app/indices
• bulk_wait_interval= - The time to wait before sending the bulk request to the elasticsearch/opensearch cluster. Default: 0.1

Cluster Configurations

Elasticsearch/Opensearch Client

You can use this gem one or more elasticsearch/opensearch clusters. The only limitation is that the version of elasticsearch-ruby or opensearch-ruby gem should be the same for all clusters. This is because the gem uses the Elasticsearch::Client class to send requests to the cluster.

To configure the cluster, you can use the cluster method:

Esse.configure do |config|
  config.cluster do |cluster|
    cluster.client = Elasticsearch::Client.new
  end
end

Note if no argument is provided, the cluster will be identified as :default. Otherwise, you can provide a name to the cluster(s):

Esse.configure do |config|
  config.cluster :sales do |cluster|
    cluster.client = Elasticsearch::Client.new(host: 'http://sales-cluster:9200')
  end

  config.cluster :customers do |cluster|
    cluster.client = Elasticsearch::Client.new(host: 'http://customers-cluster:9200')
  end
end

You should set the default cluster in the index class:

class ProductIndex < Esse::Index
  self.cluster_id = :sales
end

class CustomerIndex < Esse::Index
  self.cluster_id = :customers
end

Other tweaks

There are many other configurations you can set in the cluster:

• client= - The elasticsearch/opensearch client. Default: Elasticsearch::Client.new. (Already covered in the previous section)
• index_prefix= - The prefix to be added to the index name. Default: nil. This is useful when you want to use the same cluster for different environments (e.g. development, staging, production). Or when you want to isolate the indices of different contexts (e.g. sales, customers, products).
• settings= - The index settings. Default: {}. You can use this to set the number of shards, replicas, etc. The value of this setting will be merged with the index settings.
• mappings= - The index mappings. Default: {}. You can use this to set the index mappings. The value of this setting will be merged with the index mappings.
• wait_for_status= - The cluster status to wait before sending some requests like create_index!, delete_index!, refresh_index!, etc. Default is nil that means no wait. Other possible values are green, yellow, red.
• readonly= - If true, the index will be read-only. Any attempt to write to the index will raise an exception. Default: false.

below is a full example of the cluster configuration:

Esse.configure do |config|
  config.cluster do |cluster|
    cluster.client = Elasticsearch::Client.new
    cluster.index_prefix = ENV['RACK_ENV']
    cluster.settings = {
      number_of_shards: 1,
      number_of_replicas: 0
    }
    cluster.mappings = {
      dynamic_templates: [
        {
          strings: {
            match_mapping_type: 'string',
            mapping: {
              type: 'keyword',
              ignore_above: 256,
            },
          },
        },
      ],
      properties: {
        created_at: { type: 'date' },
        updated_at: { type: 'date' },
      }
    }
    cluster.wait_for_status = 'green'
    cluster.readonly = false
  end
end

YAML Configuration

You can also use a YAML file to configure the gem. You can use the load method to load the configuration from a YAML file:

Esse.configure do |config|
  config.load('config/esse.yml')
end

If your YAML file contains multiple environments, I recommend you to pass the parsed YAML with the proper environment node:

settings = YAML.load_file('config/esse.yml')
Esse.configure do |config|
  config.load(settings.fetch(ENV['RACK_ENV']))
end

Below is an example of the YAML configuration file:

development:
  # Global configurations
  indices_directory: app/indices
  bulk_wait_interval: 0.1
  # Per cluster configurations
  clusters:
    default:
      client:
        hosts:
          - http://localhost:9200
      index_prefix: development
      settings:
        number_of_shards: 1
        number_of_replicas: 0
      mappings:
        dynamic_templates:
          - strings:
              match_mapping_type: string
              mapping:
                type: keyword
                ignore_above: 256
        properties:
          created_at:
            type: date
          updated_at:
            type: date
      wait_for_status: green
      readonly: false

Logging

The gem uses the Logger class to log messages. You can set it by calling the Esse.logger= method:

Esse.logger = Logger.new(STDOUT)

Final Notes

The Esse.configure method is a singleton. So, you can call it multiple times in different places of your application. The configurations will be merged.

To access the configuration, you can use the Esse.config method:

Esse.config.indices_directory # => "app/indices"

Esse.config.cluster(:default).client # => #<Elasticsearch::Transport::Client:0x00007f8b1c0b6b58>

Esse.config.cluster(:default).client == Esse.config.cluster.client # => true

Esse.config.cluster.wait_for_status! # => :ok

Esse.config.cluster.readonly? # => false

Esse.config.cluster.index_prefix # => "development"

Esse.config.cluster.info # { ... }

Take a look at the Esse::Config and Esse::Cluster classes to see all available methods.