Project Overview

Flex is the ultimate ruby client for elasticsearch. It is powerful, fast and efficient, easy to use and customize.

It covers ALL the elasticsearch API, and transparently integrates it with your app and its components, like Rails, ActiveRecord, Mongoid, ActiveModel, will_paginate, kaminari, elasticsearch-mapper-attachments, …

It also implements and integrates very advanced features like chainable scopes, live-reindex, cross-model syncing, query fragment reuse, parent/child relationships, templating, self-documenting tools, detailed debugging, …

• Easy to use even for beginners
  If you have almost no elasticsearch knowledge, fear not! You can populate and search the elasticsearch index as it were an ActiveRecord DB, using very familiar chainable scopes and finders, validation and callbacks that you are used to master in your models (see flex-scopes and ActiveModel Integration)

• Powerful for experts
  Flex provides 6 different ways to interact with elasticsearch, useful in different contexts. From a fully automatic integration, to a very low-level manual interaction; a clever and powerful templating system that covers all the elaticsearch API (see Templating); all the standard elasticsearch API as ready to use methods; very detailed debugging info, high configurable logging, etc. (see Usage Overview), very easy to use live-reindexing (see Live Reindex)

• Easy to learn
  Flex doesn’t try to create any “powerful DSL” on top of the elasticsearch API: it just transparently uses the elasticsearch API, so you will never have to learn anything twice or adapt any elasticsearch query to use with ruby, a very common practice needed with other clients (see Why you should use Flex rather than Tire).

• DRY
  You can reuse full queries, or part of them to build other queries, interpolate variables into queries at request time, or define and use smart cascading defaults to reduce clutter and duplications. Flex creates the needed methods in your classes for you, so 99% of the times you will have just to use them in your code, and for the other 1% you will just need to define a simple wrapper method.

• Self Documenting
  Flex creates the documentation of your custom templates complete with usage examples. You can get it by simply calling a method… also very handy in the console (see Self Documentation).

• Fast and Efficient
  Flex uses a fast libcurl HTTP client that is at least twice as fast as a pure ruby client (but you can fallback to pure ruby if you need to). It reuses the same HTTP session between different requests saving time and resources. It extends the elasticsearch result objects instead of duplicating new structures, saving memory. It compiles the YAML templates into ruby code at startup time and just calls it at render time for faster execution.

• Clean separation of the elasticsearch logic from the application logic
  Flex uses simple YAML documents (templates that you define) to encapsulate the whole request/response cycle with the elasticsearch server, relegating the elasticsearch logic away from the application logic. Your code will be clean, easy to write and read, and very short: “poetic-short”.

• Easily Extendable
  Flex provides a simple mechanism to extend all or just specific elasticsearch results with your own methods. That is a lot cleaner and self contained than extending the results in the application code (see Result Extenders).

• Fully Integrated
  (see Out Of The Box Integrations)

Quick Start

The Flex documentation is very complete and detailed, so starting from the right topic for you will save you time. Please, pick the starting point that better describes you below:

For Tire Users

1. You may be interested to start from Why you should use Flex rather than Tire that is a direct comparison between the two projects.

2. Depending on your elasticsearch knowledge you can read below the “Elasticsearch Beginner” or the “Elasticsearch Expert” starting point sections.

For Flex 0.x Users

1. If you used an old flex version, please start with How to migrate from flex 0.x.

2. Depending on your elasticsearch knowledge you can read below the “Elasticsearch Beginner” or the “Elasticsearch Expert” sections.

For Elasticsearch Beginners

1. You may want to start with the Index and Search External Data tutorial, since it practically doesn’t require any elasticsearch knowledge. It will show you how to build your own search application with just a few lines of code. You will crawl a site, extract its content and build a simple user interface to search it with elasticsearch.

2. Then you may want to read the Usage Overview page. Follow the links from there in order to dig into the topics that interest you.

3. You will probably like the flex-scopes that allows you to easy search, chain toghether and reuse searching scopes in pure ruby.

For Elasticsearch Experts

1. Flex provides the full elasticsearch APIs as ready to use methods. Just take a look at the API Metods page to appreciate its completeness.

2. Then you may want to read the Usage Overview page. Follow the links from there in order to dig into the topics that interest you.

3. If you are used to create complex searching logic, you will certainly appreciate the Templating System that gives you real power with great simplicity.

4. As an elasticsearch expert, you will certainly appreciate the Live-Reindex feature: it encapsulates the solution to a quite complex problem in just one method call.

Gems

The functionality of flex are conveniently organized and integrated by a few gems. You can use them together or separately, depending on your needs.

flex	Provides the core infrastructure and the lower level functionality: HTTP clients elasticsearch API methods Templating System Cascading Variables Management Result Extenders Logging & Debugging Self-documenting tool Rake Tasks (see flex)
flex-scopes	very cool option for most common needs and for beginners Provides ActiveRecord-like chainable scopes allowing to use pure ruby to search your indices. It simplifies your code and make it very reusable. (see flex-scopes)
flex-models	Transparently integrates your models with one or more elasticsearch indices: Automatic integration with your ActiveRecord and Mongoid models Direct management of indices throught ActiveModel Validations and callbacks Typecasting Attribute defaults Persistent storage with optimistic lock update integration with the elasticsearch-mapper-attachment plugin finders, chainable scopes etc. (see ActiveModel Integration) Automatic generation of elasticsearch mappings based on your models Parent/Child Relationships Bulk import Real-time indexing and search capabilities (see flex-models)
flex-rails	Integrates all the flex gems with Rails, providing also specific tasks, generators, logger options, etc. (see flex-rails)
flex-admin	Provides an executable and a few tasks to dump, load (optionally rename) and stat any elasticsearch index. Live-reindex with hot-swap of old code/index with new code/index (see Live Reindex) (see flex-admin)

Tech Specs

Requirements

• ruby >= 1.8.7
• elasticsearch >= 0.19.2

Installation

1. Install the gem patron (faster, libcurl C based) or rest-client (pure ruby)
2. Install the flex gem(s) (see Gems)

Temporary Note: The patron gem currently available on rubygem (v0.4.18) is missing the support for sending data with delete queries. As the result it fails with the delete_by_query elasticsearch API, when the query is the request body and not the param. If you want full support until a new version will be pushed to rubygems, you should use gem 'patron', '0.4.18', :git => 'https://github.com/ddnexus/patron.git' or download patron-0.4.18.flex.gem, install it with gem install /path/to/patron-0.4.18.flex.gem --local and be sure your app will use that version, or switch to the rest-client gem.

Out Of The Box Integrations

• ActiveRecord 2, 3 and 4 (see ActiveRecord And Mongoid Integration)
• ActiveModel 2, 3 and 4 (see ActiveModel Integration)
• Mongoid 2 and 3 (see ActiveRecord And Mongoid Integration)
• Rails 2, 3 and 4 (see flex-rails)
• elasticsearch-mapper-attachments plugin (see Attribute Attachment)
• will_paginate and kaminari recent versions

Configuration

Flex needs just a few lines of configuration. However you can use more configuration settings to fine-tune its behavior and/or defining smart defaults that will reduce the need to pass variables explicitly (see Configuration).