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.