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:

“by 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:

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

Use the Rake tasks to run the test suites:

“undle 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.