README.md

OpenSearch Ruby Client

• Welcome!
• Sample Code
• Project Resources
• Transport Features
• Code of Conduct
• User Guide
• Compatibility with OpenSearch
• Developer Guide
• Security
• License
• Copyright

Welcome!

opensearch-ruby is a community-driven, open source fork of elasticsearch-ruby licensed under the Apache v2.0 License. For more information, see opensearch.org.

Sample Code

Please see the USER_GUIDE for code snippets.

Project Resources

• Project Website
• Documentation
• Ruby Gems.
• Need help? Try Forums
• Project Principles
• Contributing to OpenSearch
• Maintainer Responsibilities
• Release Management
• Admin Responsibilities
• Security

Transport Features

The Transport layer of the client, OpenSearch::Transport, provides the following features:

• Pluggable logging and tracing
• Pluggable connection selection strategies (round-robin, random, custom)
• Pluggable transport implementation, customizable and extendable
• Pluggable serializer implementation
• Request retries and dead connections handling
• Node reloading (based on cluster state) on errors or on demand

For optimal performance, use a HTTP library which supports persistent ("keep-alive") connections, such as Patron or Typhoeus. Most such HTTP libraries are used through the Faraday HTTP library and its adapters.

Include the library's gem and adapter gem, and require the library and adapter in your code, and it will be automatically used. If you don't use Bundler, you may need to require the library explicitly (like require 'faraday/patron').

Currently these libraries will be automatically detected and used:

• Patron through faraday-patron
• Typhoeus through faraday-typhoeus for Faraday 2 or higher, or Faraday's built-in adapter for Faraday 1.
• HTTPClient through faraday-httpclient
• Net::HTTP::Persistent through faraday-net_http_persistent

Note on Typhoeus: You need to use v1.4.0 or up since older versions are not compatible with Faraday 1.0 or higher.

Note on Faraday: If you use Faraday 2.0 or higher, if the adapter is in a separate gem, you will likely need to declare that gem as well. Only the Net::HTTP adapter gem is included by default. Faraday 1.x includes most common adapter gems already.

DSL Features

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

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

Code of Conduct

This project has adopted the Amazon Open Source Code of Conduct. For more information see the Code of Conduct FAQ, or contact [email protected] with any additional questions or comments.

User Guide

See USER_GUIDE.

Compatibility with OpenSearch

See Compatibility.

Upgrading

See UPGRADING.

Developer Guide

See DEVELOPER_GUIDE.

Security

If you discover a potential security issue in this project we ask that you notify AWS/Amazon Security via our vulnerability reporting page or directly via email to [email protected]. Please do not create a public GitHub issue.

License

This project is licensed under the Apache v2.0 License.

Copyright

Copyright OpenSearch Contributors. See NOTICE for details.