OpenSearch::DSL

The opensearch-dsl library provides a Ruby API for the OpenSearch Query DSL

The library is compatible with Ruby 1.9 or higher and OpenSearch 1.0.0 and higher.

Installation

Install the package from Rubygems:

gem install opensearch-dsl

To use an unreleased version, either add it to your Gemfile for Bundler:

gem 'opensearch-dsl', git: 'git://github.com/opensearch-project/opensearch-ruby.git'

or install it from a source code checkout:

git clone https://github.com/opensearch-project/opensearch-ruby
cd opensearch-ruby/opensearch-dsl
bundle install
rake install

Usage

The library is designed as a group of standalone Ruby modules, classes and DSL methods, which provide an idiomatic way to build complex search definitions

Let's have a simple example using the declarative variant:

require 'opensearch'
require 'opensearch/dsl'
include OpenSearch::DSL

# If you want to use authentication credentials
client = OpenSearch::Client.new url: 'https://admin:admin@localhost:9200', log: true

# If you don't want to use authentication credentials
# client = OpenSearch::Client.new url: 'http://localhost:9200', log: true

index_name = 'my-dsl-index'
index_body = {
  'settings': {
    'index': {
      'number_of_shards': 4
    }
  }
}
response = client.indices.create(
        index: index_name,
        body: index_body
)

puts 'Creating index:'
puts response

# Add a document to the index.
document = {
        'title': 'ruby',
        'description': 'beta',
        'category': 'search'
}
id = '1'

response = client.index(
        index: index_name,
        body: document,
        id: id,
        refresh: true
)

puts 'Adding document:'
puts response

response = client.search index: index_name, body: search {
      query do
            bool do
                  filter do
                        term category: "search"
                  end
                  must do
                        match title: "ruby"
                  end
            end
      end
}.to_hash

puts 'Search results:'
puts response


# Delete the document.
response = client.delete(
        index: index_name,
        id: id
)

puts 'Deleting document:'
puts response

# Delete the index.
response = client.indices.delete(
        index: index_name
)

puts 'Deleting index:'
puts response

Features Overview

The library allows to programatically build complex search definitions for OpenSearch in Ruby, which are translated to Hashes, and ultimately, JSON, the language of OpenSearch.

All OpenSearch DSL features are supported, namely:

• Queries and Filter context
• Aggregations
• Suggestions
• Sorting
• Pagination
• Options

Development

To work on the code, clone the repository and install the dependencies:

git clone https://github.com/opensearch-project/opensearch-ruby
cd opensearch-ruby/opensearch-dsl/
bundle install

Use the Rake tasks to run the test suites:

bundle exec rake test:unit
bundle exec rake test:integration

To launch a separate OpenSearch server for integration tests, see instructions in the main README.

License

This software is licensed under the Apache 2 license.