opensearch-ruby 2.0.3 → 3.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '09738ad6dab827d10dd3cff398c186c2b0d12043794ff86250956bf0fa5a0996'
-  data.tar.gz: b3f8194f5e7937e6016c0108da61775cbab21a3ad2e261f464749032731a8b0e
+  metadata.gz: eb87cfb56648460b74a2ae459b729860b515d115b4d801c4607a21ee591e2269
+  data.tar.gz: 8466da7f17c294d4c1c78fd69101c0c809a6e2d3938e7afaa0186f5dd3995fae
 SHA512:
-  metadata.gz: 23b344c1d411061db7684cbbc577441fd057cfb1cfc5311ce36518691fb4fb535451ffc6a4f99dd68df5500858ec1e1c2022a4ad7f552f249274c02086fbaf96
-  data.tar.gz: 5dd14699207563927c7151ffbde2dbe15fdfcaa781fe9f68b95ebde42ffbb87afbadeef6669c24727c6f6a6b27be2a4ad1f542eb1ed8157a25984589bafe550d
+  metadata.gz: cc5ed4d0b4c0bb30dbbd1a1bc0a3dab182158cd1d095c338c213e94ffe33afdbd16212c68b3457a79f05abebbd61a1b2066336b61c1b8cf874f3766b4d26d203
+  data.tar.gz: ca0c548400b58f48b9ec44bfd126186e7be455ee12f8174d9db916504e989a3cd7d974165faebc7f3314f1b416914bc95a321f57472ede7bc61db6937452e20e

data/README.md

@@ -1,8 +1,48 @@
-# OpenSearch
+[![Integration](https://github.com/opensearch-project/opensearch-ruby/actions/workflows/main.yml/badge.svg)](https://github.com/opensearch-project/opensearch-ruby/actions/workflows/main.yml)
+[![Chat](https://img.shields.io/badge/chat-on%20forums-blue)](https://discuss.opendistrocommunity.dev/c/clients/)
+![PRs welcome!](https://img.shields.io/badge/PRs-welcome!-success)
 
-The `opensearch` library provides a Ruby client and API for [OpenSearch](http://opensearch.com).
+![OpenSearch logo](https://raw.githubusercontent.com/opensearch-project/opensearch-ruby/main/OpenSearch.svg)
 
-Features overview:
+OpenSearch Ruby Client
+
+- [Welcome!](#welcome)
+- [Sample Code](#sample-code)
+- [Project Resources](#project-resources)
+- [Transport Features](#transport-features)
+- [Code of Conduct](#code-of-conduct)
+- [User Guide](#user-guide)
+- [Compatibility with OpenSearch](#compatibility-with-opensearch)
+- [Developer Guide](#developer-guide)
+- [Security](#security)
+- [License](#license)
+- [Copyright](#copyright)
+
+## Welcome!
+
+**opensearch-ruby** is [a community-driven, open source fork](https://aws.amazon.com/blogs/opensource/introducing-opensearch/) of elasticsearch-ruby licensed under the [Apache v2.0 License](LICENSE.txt).
+For more information, see [opensearch.org](https://opensearch.org/).
+
+## Sample Code
+
+Please see the [USER_GUIDE](USER_GUIDE.md) for code snippets.
+
+## Project Resources
+
+* [Project Website](https://opensearch.org/)
+* [Documentation](https://opensearch.org/docs/latest/clients/ruby/)
+* [Ruby Gems](https://rubygems.org/gems/opensearch-ruby).
+* Need help? Try [Forums](https://discuss.opendistrocommunity.dev/c/clients/)
+* [Project Principles](https://opensearch.org/#principles)
+* [Contributing to OpenSearch](CONTRIBUTING.md)
+* [Maintainer Responsibilities](MAINTAINERS.md)
+* [Release Management](RELEASING.md)
+* [Admin Responsibilities](ADMINS.md)
+* [Security](SECURITY.md)
+
+## 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)
@@ -10,72 +50,66 @@ Features overview:
 * Pluggable serializer implementation
 * Request retries and dead connections handling
 * Node reloading (based on cluster state) on errors or on demand
-* Consistent API support for the whole OpenSearch API
-* Extensive documentation and examples
-* Emphasis on modularity and extendability of both the client and API libraries
-
-## Compatibility
 
-The OpenSearch client for Ruby is compatible with Ruby 1.9 and higher.
+For optimal performance, use a HTTP library which supports persistent ("keep-alive") connections, such as [Patron](https://github.com/toland/patron) or [Typhoeus](https://github.com/typhoeus/typhoeus).
+Most such HTTP libraries are used through the [Faraday](https://rubygems.org/gems/faraday) HTTP library and its [adapters](https://github.com/lostisland/awesome-faraday/#adapters).
 
-The client's API is compatible with OpenSearch's API versions from 1.0.0 till current.
+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'`).
 
-See [COMPATIBILITY](../COMPATIBILITY.md) for more details.
+Currently these libraries will be automatically detected and used:
+- [Patron](https://github.com/toland/patron) through [faraday-patron](https://github.com/lostisland/faraday-patron)
+- [Typhoeus](https://github.com/typhoeus/typhoeus) through [faraday-typhoeus](https://github.com/dleavitt/faraday-typhoeus) for Faraday 2 or higher, or Faraday's built-in adapter for Faraday 1.
+- [HTTPClient](https://rubygems.org/gems/httpclient) through [faraday-httpclient](https://github.com/lostisland/faraday-httpclient)
+- [Net::HTTP::Persistent](https://rubygems.org/gems/net-http-persistent) through [faraday-net_http_persistent](https://github.com/lostisland/faraday-net_http_persistent)
 
-## Installation
+**Note on [Typhoeus](https://github.com/typhoeus/typhoeus)**: You need to use v1.4.0 or up since older versions are not compatible with Faraday 1.0 or higher.
 
-Install the package from [Rubygems](https://rubygems.org):
+**Note on [Faraday](https://rubygems.org/gems/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.
 
-    gem install opensearch-ruby
+## DSL Features
 
-To use an unreleased version, either add it to your `Gemfile` for [Bundler](http://gembundler.com):
+The `opensearch-dsl` library provides a Ruby API for the `OpenSearch Query DSL`.
 
-    gem 'opensearch-ruby', git: 'git://github.com/opensearch-project/opensearch-ruby.git'
+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.
 
-or install it from a source code checkout:
+All OpenSearch DSL features are supported, namely:
 
-    git clone https://github.com/opensearch-project/opensearch-ruby
-    cd opensearch-ruby/opensearch
-    bundle install
-    rake install
+* Queries and Filter context
+* Aggregations
+* Suggestions
+* Sorting
+* Pagination
+* Options
 
-## Usage
+## Code of Conduct
 
-This library is a wrapper for two separate libraries:
+This project has adopted the [Amazon Open Source Code of Conduct](CODE_OF_CONDUCT.md). For more information see the [Code of Conduct FAQ](https://aws.github.io/code-of-conduct-faq), or contact [opensource-codeofconduct@amazon.com](mailto:opensource-codeofconduct@amazon.com) with any additional questions or comments.
 
-* [`opensearch-transport`](https://github.com/opensearch-project/opensearch-ruby/tree/main/opensearch-transport),
-  which provides a low-level Ruby client for connecting to an [OpenSearch](http://opensearch.com) cluster
-* [`opensearch-api`](https://github.com/opensearch-project/opensearch-ruby/tree/main/opensearch-api),
-  which provides a Ruby API for the OpenSearch RESTful API
+## User Guide
 
-Install the `opensearch` package and use the API directly:
+See [USER_GUIDE](USER_GUIDE.md).
 
-```ruby
-require 'opensearch'
+## Compatibility with OpenSearch
 
-client = OpenSearch::Client.new log: true
+See [Compatibility](COMPATIBILITY.md).
 
-client.cluster.health
+## Upgrading
 
-client.transport.reload_connections!
+See [UPGRADING](UPGRADING.md).
 
-client.search q: 'test'
+## Developer Guide
 
-# etc.
-```
+See [DEVELOPER_GUIDE](DEVELOPER_GUIDE.md).
 
-Please refer to the specific library documentation for details:
+## Security
 
-* **Transport**:
-   [[README]](https://github.com/opensearch-project/opensearch-ruby/blob/main/opensearch-transport/README.md)
+If you discover a potential security issue in this project we ask that you notify AWS/Amazon Security via our [vulnerability reporting page](http://aws.amazon.com/security/vulnerability-reporting/) or directly via email to aws-security@amazon.com. Please do **not** create a public GitHub issue.
 
-* **API**:
-   [[README]](https://github.com/opensearch-project/opensearch-ruby/blob/main/opensearch-api/README.md)
-
-## Development
+## License
 
-You can run `rake -T` to check the test tasks. Use `COVERAGE=true` before running a test task to check the coverage with Simplecov.
+This project is licensed under the [Apache v2.0 License](LICENSE.txt).
 
-## License
+## Copyright
 
-This software is licensed under the [Apache 2 license](./LICENSE).
+Copyright OpenSearch Contributors. See [NOTICE](NOTICE.txt) for details.

data/USER_GUIDE.md

@@ -0,0 +1,149 @@
+- [User Guide](#user-guide)
+  - [Setup](#setup)
+  - [Basic Usage](#basic-usage)
+  - [OpenSearch DSL](#opensearch-dsl)
+  - [Guides by Topics](#guides-by-topics)
+  - [Amazon OpenSearch Service](#amazon-opensearch-service)
+
+# User Guide
+## Setup
+
+To add the client to your project, install it using [RubyGems](https://rubygems.org/):
+
+`gem install opensearch-ruby`
+
+or add it to your Gemfile:
+```ruby
+gem 'opensearch-ruby'
+```
+and run:
+```
+bundle install
+```
+
+Import the client:
+
+```ruby
+require 'opensearch'
+```
+
+## Basic Usage
+```ruby
+require 'opensearch'
+
+client = OpenSearch::Client.new(
+  host: 'https://localhost:9200',
+  user: 'admin',
+  password: 'admin',
+  transport_options: { ssl: { verify: false } }  # For testing only. Use certificate for validation.
+)
+
+# Create an index with non-default settings
+index_name = 'ruby-test-index'
+index_body = {
+  'settings': {
+    'index': {
+      'number_of_shards': 4
+    }
+  }
+}
+
+puts 'Creating index'
+response = client.indices.create(
+  index: index_name,
+  body: index_body
+)
+puts response
+
+
+# Add a document to the index
+document = {
+  'title': 'Moneyball',
+  'director': 'Bennett Miller',
+  'year': '2011'
+}
+id = '1'
+
+puts 'Adding document'
+response = client.index(
+  index: index_name,
+  body: document,
+  id: id,
+  refresh: true
+)
+puts response
+
+# Search for the document
+q = 'miller'
+query = {
+  'size': 5,
+  'query': {
+    'multi_match': {
+      'query': q,
+      'fields': ['title^2', 'director']
+    }
+  }
+}
+
+puts 'Search results'
+response = client.search(
+  body: query,
+  index: index_name
+)
+puts response
+
+
+# Delete the document
+puts 'Deleting document'
+response = client.delete(
+  index: index_name,
+  id: id
+)
+puts response
+
+# Delete the index
+puts 'Deleting index'
+response = client.indices.delete(
+  index: index_name
+)
+puts response   
+```
+
+## OpenSearch DSL
+
+The `opensearch-dsl` library is designed as a group of standalone Ruby modules, classes and DSL methods, which provide an idiomatic way to build complex search definitions
+
+```ruby
+require 'opensearch'
+require 'opensearch/dsl'
+include OpenSearch::DSL
+
+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
+```
+
+## Guides by Topics
+- [Index Lifecycle](guides/index_lifecycle.md)
+- [Document Lifecycle](guides/document_lifecycle.md)
+- [Search](guides/search.md)
+- [Bulk](guides/bulk.md)
+- [Advanced Index Actions](guides/advanced_index_actions.md)
+- [Index Templates](guides/index_template.md)
+- [Transport Options](guides/transport_options.md)
+- [Custom HTTP Requests](guides/json.md)
+
+## Amazon OpenSearch Service
+
+Requests to [OpenSearch Service and OpenSearch Serverless](https://docs.aws.amazon.com/opensearch-service/index.html) must be signed using the AWS signing protocol. Use `opensearch-aws-sigv4` gem in place of `opensearch-ruby` gem.
+
+For more information, checkout the [USER_GUIDE](https://github.com/opensearch-project/opensearch-ruby-aws-sigv4/blob/main/USER_GUIDE.md) of [opensearch-aws-sigv4 gem](https://github.com/opensearch-project/opensearch-ruby-aws-sigv4).

data/bin/opensearch_ruby_console

@@ -1,44 +1,14 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
-$LOAD_PATH.unshift(File.expand_path('../../opensearch/lib', __dir__))
-$LOAD_PATH.unshift(File.expand_path('../../opensearch-transport/lib', __dir__))
-$LOAD_PATH.unshift(File.expand_path('../../opensearch-dsl/lib', __dir__))
-$LOAD_PATH.unshift(File.expand_path('../../opensearch-api/lib', __dir__))
+$LOAD_PATH.unshift(File.expand_path('../lib', __dir__))
 
-require 'opensearch'
-require 'opensearch-transport'
-require 'opensearch-api'
-
-gems_not_loaded = ['opensearch-dsl'].reject do |gem|
-  begin
-    (require gem) || true
-  rescue LoadError
-    false
-  end
-end
-
-unless gems_not_loaded.empty?
-  warn "The following gems were not loaded: [#{gems_not_loaded.join(', ')}]. Please install and require them explicitly."
-end
-
-include OpenSearch
-include OpenSearch::DSL if defined?(OpenSearch::DSL)
+require 'opensearch-ruby'
 
 begin
   require 'pry'
+  Pry.start
 rescue LoadError
-end
-
-begin
   require 'irb'
-rescue LoadError
-end
-
-if defined?(Pry)
-  Pry.config.prompt_name = 'opensearch_ruby'
-  Pry.start
-elsif defined?(IRB)
   IRB.start
-else
-  abort 'LoadError: opensearch_ruby_console requires Pry or IRB'
 end

data/lib/opensearch/api/actions/abort_benchmark.rb

@@ -0,0 +1,49 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# The OpenSearch Contributors require contributions made to
+# this file be licensed under the Apache-2.0 license or a
+# compatible open source license.
+#
+# Modifications Copyright OpenSearch Contributors. See
+# GitHub history for details.
+#
+# Licensed to Elasticsearch B.V. under one or more contributor
+# license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright
+# ownership. Elasticsearch B.V. licenses this file to you under
+# the Apache License, Version 2.0 (the "License"); you may
+# not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+module OpenSearch
+  module API
+    module Actions
+      # Abort a running benchmark
+      #
+      # @example
+      #
+      #     client.abort_benchmark name: 'my_benchmark'
+      #
+      # @option arguments [String] :name A benchmark name
+      #
+      #
+      def abort_benchmark(arguments = {})
+        method = HTTP_POST
+        path   = "_bench/abort/#{arguments[:name]}"
+        params = {}
+        body   = nil
+
+        perform_request(method, path, params, body).body
+      end
+    end
+  end
+end

data/lib/opensearch/api/actions/benchmark.rb

@@ -0,0 +1,88 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# The OpenSearch Contributors require contributions made to
+# this file be licensed under the Apache-2.0 license or a
+# compatible open source license.
+#
+# Modifications Copyright OpenSearch Contributors. See
+# GitHub history for details.
+#
+# Licensed to Elasticsearch B.V. under one or more contributor
+# license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright
+# ownership. Elasticsearch B.V. licenses this file to you under
+# the Apache License, Version 2.0 (the "License"); you may
+# not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+module OpenSearch
+  module API
+    module Actions
+      # Run a single query, or a set of queries, and return statistics on their performance
+      #
+      # @example Return statistics for a single query
+      #
+      #     client.benchmark body: {
+      #       name: 'my_benchmark',
+      #       competitors: [
+      #         {
+      #           name: 'query_1',
+      #           requests: [
+      #             { query: { match: { _all: 'a*' } } }
+      #           ]
+      #         }
+      #       ]
+      #     }
+      #
+      # @example Return statistics for a set of "competing" queries
+      #
+      #     client.benchmark body: {
+      #       name: 'my_benchmark',
+      #       competitors: [
+      #         {
+      #           name: 'query_a',
+      #           requests: [
+      #             { query: { match: { _all: 'a*' } } }
+      #           ]
+      #         },
+      #         {
+      #           name: 'query_b',
+      #           requests: [
+      #             { query: { match: { _all: 'b*' } } }
+      #           ]
+      #         }
+      #       ]
+      #     }
+      #
+      # @option arguments [List] :index A comma-separated list of index names; use `_all` or empty string
+      #                                 to perform the operation on all indices
+      # @option arguments [Hash] :body The search definition using the Query DSL
+      # @option arguments [Boolean] :verbose Specify whether to return verbose statistics about each iteration
+      #                                      (default: false)
+      #
+      #
+      def benchmark(arguments = {})
+        method = HTTP_PUT
+        path   = '_bench'
+        params = Utils.__validate_and_extract_params arguments, ParamsRegistry.get(__method__)
+        body   = arguments[:body]
+
+        perform_request(method, path, params, body).body
+      end
+
+      # Register this action with its valid params when the module is loaded.
+      #
+      # @since 6.1.1
+      ParamsRegistry.register(:benchmark, [:verbose].freeze)
+    end
+  end
+end

data/lib/opensearch/api/actions/bulk.rb

@@ -0,0 +1,91 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# The OpenSearch Contributors require contributions made to
+# this file be licensed under the Apache-2.0 license or a
+# compatible open source license.
+#
+# Modifications Copyright OpenSearch Contributors. See
+# GitHub history for details.
+#
+# Licensed to Elasticsearch B.V. under one or more contributor
+# license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright
+# ownership. Elasticsearch B.V. licenses this file to you under
+# the Apache License, Version 2.0 (the "License"); you may
+# not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+module OpenSearch
+  module API
+    module Actions
+      # Allows to perform multiple index/update/delete operations in a single request.
+      #
+      # @option arguments [String] :index Default index for items which don't provide one
+      # @option arguments [String] :wait_for_active_shards Sets the number of shard copies that must be active before proceeding with the bulk operation. Defaults to 1, meaning the primary shard only. Set to `all` for all shard copies, otherwise set to any non-negative value less than or equal to the total number of copies for the shard (number of replicas + 1)
+      # @option arguments [String] :refresh If `true` then refresh the affected shards to make this operation visible to search, if `wait_for` then wait for a refresh to make this operation visible to search, if `false` (the default) then do nothing with refreshes. (options: true, false, wait_for)
+      # @option arguments [String] :routing Specific routing value
+      # @option arguments [Time] :timeout Explicit operation timeout
+      # @option arguments [List] :_source True or false to return the _source field or not, or default list of fields to return, can be overridden on each sub-request
+      # @option arguments [List] :_source_excludes Default list of fields to exclude from the returned _source field, can be overridden on each sub-request
+      # @option arguments [List] :_source_includes Default list of fields to extract and return from the _source field, can be overridden on each sub-request
+      # @option arguments [String] :pipeline The pipeline id to preprocess incoming documents with
+      # @option arguments [Boolean] :require_alias Sets require_alias for all incoming documents. Defaults to unset (false)
+      # @option arguments [Hash] :headers Custom HTTP headers
+      # @option arguments [String|Array] :body The operation definition and data (action-data pairs), separated by newlines. Array of Strings, Header/Data pairs,
+      # or the conveniency "combined" format can be passed, refer to OpenSearch::API::Utils.__bulkify documentation.
+      #
+      #
+      def bulk(arguments = {})
+        raise ArgumentError, "Required argument 'body' missing" unless arguments[:body]
+
+        headers = arguments.delete(:headers) || {}
+
+        arguments = arguments.clone
+
+        _index = arguments.delete(:index)
+
+        method = OpenSearch::API::HTTP_POST
+        path   = if _index
+                   "#{Utils.__listify(_index)}/_bulk"
+                 else
+                   '_bulk'
+                 end
+        params = Utils.__validate_and_extract_params arguments, ParamsRegistry.get(__method__)
+
+        body = arguments[:body]
+        payload = if body.is_a? Array
+                    OpenSearch::API::Utils.__bulkify(body)
+                  else
+                    body
+                  end
+
+        headers.merge!('Content-Type' => 'application/x-ndjson')
+        perform_request(method, path, params, payload, headers).body
+      end
+
+      # Register this action with its valid params when the module is loaded.
+      #
+      # @since 6.2.0
+      ParamsRegistry.register(:bulk, %i[
+        wait_for_active_shards
+        refresh
+        routing
+        timeout
+        _source
+        _source_excludes
+        _source_includes
+        pipeline
+        require_alias
+      ].freeze)
+    end
+  end
+end