Ruby ElasticSearch::QueryBuilder

Ruby gem for building complex ElasticSearch queries using clauses as methods. Supports query and function_score builders, as well as clients to fetch results.

Add this line to your application's Gemfile:

gem 'elasticsearch-query-builder'

And then execute:

$ bundle

Or install it yourself as:

$ gem install elasticsearch-query-builder

Instantiate the class

elastic_query = ElasticSearch::QueryBuilder.new(opts: {}, client: nil, function_score: false)

Available methods and paths are:

• must: [ query bool must ],
• must_not: [ query bool must_not ],
• should: [ query bool should ],
• functions: [ functions ],
• ids: [ query terms _id ],
• size: [ size ],
• fields: [ _source ],
• range: [ bool must range ],
• sort: [ sort ],
• aggs: [ aggs ]

Once the class is loaded, each method is defined and path query function_score is appended if class was initialized with function_score: true and original path starts with query.

Each path is initialized if not added previously to the query. If already added, it's appended to existing path preserving all previous clauses.

must and must_not are exclusive paths. The QueryBuilder do its best to recognize if an opposite clauses was previously added and remove it preserving only the last exclusive clause.

Once the path is built and the opposite is excluded, the clause is merged with all the other clauses.

Receives an array of clauses and insert them in query: { bool: { must: [] } } path. If clause was previously added with .must_not() it is replaced.

Example

elastic_query.must([ { range: { sign_in_count: { gte: 3 } } } ])

# elastic_query.send(:opts)
{
    query: {
        bool: {
            must: [
                range: {
                    sign_in_count: { gte: 3 }
                }
            ]
        }
    }
}

Receives an array of clauses and insert them in query: { bool: { must_not: [] } } path. If clause was previously added with .must() it is replaced.

Example

elastic_query.must_not([ { range: { sign_in_count: { gte: 3 } } } ])

# elastic_query.send(:opts)
{
    query: {
        bool: {
            must_not: [
                range: {
                    sign_in_count: { gte: 3 }
                }
            ]
        }
    }
}

Receives an array of clauses and insert them in query: { bool: { should: [] } } path.

Example

elastic_query.should([ { range: { sign_in_count: { gte: 3 } } } ])

# elastic_query.send(:opts)
{
    query: {
        bool: {
            should: [
                range: {
                    sign_in_count: { gte: 3 }
                }
            ]
        }
    }
}

Receives an array of functions to calculate document score. .functions() is overridden if .sort() method is called. Functions are inserted in query: { function_score: { functions: [] } } path.

Example

elastic_query.functions([ { script_score: { script: "1 - ( 1.0 / ( doc['popularity'].value == 0 ? 1 : doc['popularity'].value ))" }, weight: 1 } ])

# elastic_query.send(:opts)
{
    query: {
        function_score: {
            functions: [
                { script_score: { script: "1 - ( 1.0 / ( doc['popularity'].value == 0 ? 1 : doc['popularity'].value ))" }, weight: 1 }
            ]
        }
    }
}

Receives an array of ids to retrieve. Ids are inserted in query: { terms: { _id: [] } } path.

Example

elastic_query.ids([1, 4, 6])

# elastic_query.send(:opts)
{
    query: {
        terms: {
            _id: [
                1,
                4
                6
            ]
        }
    }
}

Receives an integer representing the number of documents to retrieve. Size is a root attribute in size: size path. Each time .size() method is called, size attribute is overridden.

.size(0) returns all metadata but documents.

Example

elastic_query.size(200)

# elastic_query.send(:opts)
{
    query: {
    },
    size: 200
}

Receives an array of fields to retrieve for each document. Each field is appended to _source path.

Example

elastic_query.fields([:name, :category, :created_at])

# elastic_query.send(:opts)
{
    query: {
    },
    _source: [:name, :category, :created_at]
}

Subtype of .must() method. Receives an array of clauses representing ranges of fields. Each clause is appended to query bool must range path.

Example

elastic_query.range([{ sign_in_count: { gte: 3 } }])

# elastic_query.send(:opts)
{
    query: {
        bool: {
            must: [
                range: [
                    {
                        sign_in_count: { gte: 3 }
                    }
                ]
            ]
        }
    }
}

Receives a field to sort query results by. Each time .sort() method is called, sort attribute is overridden. It also disables .functions() score.

Example

elastic_query.sort([popularity: { order: :desc }])

# elastic_query.send(:opts)
{
    query: {
    },
    sort: [
        { popularity: { order: :desc } }
    ]
}

Receives an array of fields to aggregate results count by. If body is not needed, .size(0) will still return aggregated count.

Example

elastic_query.sort([aggs: { ages: { terms: { field: 'median_age' } } }])

# elastic_query.send(:opts)
{
    query: {
    },
    aggs: [
        { ages: { terms: { field: 'median_age' } } }
    ]
}

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests.

Bug reports and pull requests are welcome on Gituhub at https://github.com/goprebo/elasticsearch-query-builder. 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.

The gem is available as open source under the terms of the MIT License.

Everyone interacting in the Elasticsearch::QueryBuilder project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.

You may contact Prebo at support@goprebo.com or in https://www.goprebo.com/