Elastic Search Framework

Welcome to Elastic Search Framework, this is a light weight framework that provides managers to help with interacting with Elastic Search.

Installation

Add this line to your application's Gemfile:

gem 'elastic_search_framework'

And then execute:

$ bundle

Or install it yourself as:

$ gem install elasticsearch_framework

Usage

Global Config

#namespace

The namespace is used to set the prefix applied to all table and index names.

Optional.

elasticsearchFramework.namespace = 'uat'

With a namespace of 'uat' and a table name of 'people', the resulting table name would be 'uat.people'

#namespace_delimiter

This is the delimiter used to join the namespace prefix to table/index names.

DEFAULT = '.'

elasticsearchFramework.namespace_delimiter = '-'

#host

This is used to set the host that should be used for all connection actions.

ElasticSearchFramework.host = 'http://elasticsearch'

#port

This is used to set the port that should be used for all connection actions.

ElasticSearchFramework.port = 9200

DEFAULT = 9200

IndexAlias

To define an index alias within elasticsearch, create an index alias class that extends from the ElasticSearchFramework::IndexAlias module.

Example:

class ExampleIndexAlias
  extend ElasticSearchFramework::IndexAlias

  index ExampleIndex, active: true
  index ExampleIndex2, active: false

  name :example
end

attributes

• index [Hash] [Required] [Multi] This is used to specify the indexes associated with this alias and which index is the current active index for the alias to point to.
• name [Hash] [Required] [Single] This is used to specify the unique name of the index alias.

---

Index Aliases are required to decouple your application from a specific index and allow you to handle index updates without downtime.

To change the mapping of an existing index Create a new version of the index, then associate the new index with the index alias as an inactive index active: false. This will allow index writes and deletes to be performed on both indexes so no new data is lost while you perform a _reindex operation to move existing data from the old index into the new index.

Once you have _reindexed into your new index you can then de-activate the old index active: false and activate the new index active: true in your index alias. This will swap all requests to the new index.

Doing the above steps should enable you to seamlessly transition between 1 index and another when mapping/analyzer changes are required.

#create

This method is called to create the index alias within an elastic search instance.

This method is idempotent and will modify the index alias if it already exists.

All associated indexes must exist before this method is called.

ExampleIndexAlias.create

Index operation methods

The following index operation methods are available for an index alias:

• #get_item
• #put_item
• #delete_item
• #query

#put_item calls will be performed against all indexes associated with the alias.

#delete_item calls will be performed against all indexes associated with the alias.

Details for how to use the above index operation methods can be found below.

Index

To define an index within elasticsearch, create an index definition class that extends from the ElasticSearchFramework::Index module.

class ExampleIndex
  extend ElasticSearchFramework::Index

  index name: 'example_index', shards: 1

  id :example_id

  mapping name: 'default', field: :name, type: :keyword, index: true
end

attributes

• index [Hash] [Required] This is used to specify the name of the index, and the number of shards the index should use.
• mapping [Hash] [Optional] This is used to specify field mappings to control the analyzer used for a given field.
• id [Hash] [Optional] [Default=id] This is used to specify the id field of the index document. (By default this is :id)

#create

This method is called to create the index definition within an elastic search instance.

ExampleIndex.create

#drop

This method is called to drop the index from an elastic search instance.

ExampleIndex.drop

#exists?

This method is called to determine if an index exists in a elastic search instance.

ExampleIndex.exists?

#put_item

This method is called to store a document/entity within the index.

ExampleIndex.put_item(item: document)

Params

• item [Object] [Required] This is the document/entity you want to store in the index.
• type [String] [Optional] [Default='default'] This is used to specify the type of the document within the index.

#get_item

This method is called to fetch a document from within the index.

ExampleIndex.get_item(id: document_id)

Params

• id [String/Integer] [Required] This is the unique identifier of the document/entity you want to fetch from the index.
• type [String] [Optional] [Default='default'] This is used to specify the type of the document within the index.

#delete_item

This method is called to delete a document from within the index.

ExampleIndex.delete_item(id: document_id)

Params

• id [String/Integer] [Required] This is the unique identifier of the document/entity you want to delete from the index.
• type [String] [Optional] [Default='default'] This is used to specify the type of the document within the index.

#query

This method is called to query the index for a collection of items.

The query is then built up using method chaining e.g:

query = ExampleIndex.query.gender.eq('male').and.age.gt(18)

The above query chain translates into:

FROM ExampleIndex WHERE gender == 'male' AND age > 18

To execute the query you can then call #execute on the query:

query.execute

Due to method chaining, the #execute method can also be chained to the end of a query directly.

#execute

This method is called to execute a query.

Params

• limit [Integer] [Optional] This is used to specify a limit to the number of items returned by the query.
• count [Boolean] [Optional] This is used to specify if the query should just return a count of results.

Query expressions

#eq(value)

This method is used to specify the == operator within a query.

#not_eq(value)

This method is called to specify the != operator within a query.

#gt(value)

This method is called to specify the > operator within a query.

#gt_eq(vaue)

This method is called to specify the >= operator within a query.

#lt(value)

This method is called to specify the < operator within a query.

#lt_eq(value)

This method is called to specify the <= operator within a query.

#contains(value)

This method is called to check if a field contains a value within a query.

#exists?

This method is called to check if a field exists within a query.

#and

This method is called to combine conditions together in a traditional && method within a query.

#or

This method is called to combine conditions together in a traditional || method within a query.

Testing

To run the tests locally, we use Docker to provide both a Ruby and JRuby environment along with a reliable Redis container.

Setup Images:

This builds the Ruby docker image.

./script/setup.sh

Run Tests:

This executes the test suite.

./script/test.sh

Cleanup

This is used to clean down docker image created in the setup script.

./script/cleanup.sh

Development

After checking out the repo, run bin/setup to install dependencies. 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.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/sage/elasticsearch_framework. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

This gem is available as open source under the terms of the MIT licence.

Copyright (c) 2018 Sage Group Plc. All rights reserved.