Added PIT actions (#155)

Removed Legacy X-Pack Point-In-Time API

Signed-off-by: Theo Truong <[email protected]>

USER_GUIDE.md

@@ -1,6 +1,8 @@
 - [User Guide](#user-guide)
   - [Setup](#setup)
   - [Sample code](#sample-code)
+    - [Basic Usage](#basic-usage)
+    - [Point in Time](#point-in-time)
   - [Amazon OpenSearch Service](#amazon-opensearch-service)
 
 # User Guide
@@ -24,7 +26,8 @@ Import the client:
 `require 'opensearch'`
 
 ## Sample code
-
+<a name="basic-usage" /></a>
+### Basic Usage
 ```ruby
 require 'opensearch'
 
@@ -106,8 +109,39 @@ response = client.indices.delete(
 puts response   
 ```
 
+### Point in Time
+Refer to OpenSearch [documentation](https://opensearch.org/docs/latest/point-in-time-api/) for more information on point in time.
+```ruby
+require 'opensearch-ruby'
+client = OpenSearch::Client.new({ host: 'localhost' })
+index = :movies
+client.indices.create(index: 'movies')
+
+# CREATE 3 PITS
+client.create_pit index: index, keep_alive: '1m'
+client.create_pit index: index, keep_alive: '1m'
+client.create_pit index: index, keep_alive: '1m'
+
+# GET ALL PITS
+pits = client.get_all_pits
+puts pits
+
+# DELETE FIRST PIT
+client.delete_pit body: { pit_id: [pits.dig('pits', 0, 'pit_id')] }
+
+# ALL PITS SEGMENTS
+puts client.cat.all_pit_segments
+
+# SEGMENTS FOR A SPECIFIC PIT
+puts client.cat.pit_segments body: { pit_id: [pits.dig('pits', 1, 'pit_id')] }
+
+
+# DELETE ALL PITS
+puts client.delete_all_pits
+```
+
 ## 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](opensearch-aws-sigv4/USER_GUIDE.md) of [opensearch-aws-sigv4](opensearch-aws-sigv4).
+For more information, checkout the [USER_GUIDE](opensearch-aws-sigv4/USER_GUIDE.md) of [opensearch-aws-sigv4](opensearch-aws-sigv4).

opensearch-api/.gitignore

@@ -3,6 +3,7 @@
 .bundle
 .config
 .yardoc
+.ruby-version
 Gemfile.lock
 InstalledFiles
 _yardoc

opensearch-api/CHANGELOG.md

@@ -3,9 +3,11 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 
 ## [Unreleased]
 ### Added
+- Added Point-In-Time API ([#136](https://github.com/opensearch-project/opensearch-ruby/issues/136))
 ### Changed
 ### Deprecated
 ### Removed
+- Removed Legacy X-Pack Point-In-Time API ([#136](https://github.com/opensearch-project/opensearch-ruby/issues/136))
 ### Fixed
 ### Security
 

opensearch-api/lib/opensearch/api/actions/cat/all_pit_segments.rb

@@ -0,0 +1,46 @@
+# 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.
+
+module OpenSearch
+  module API
+    module Cat
+      module Actions
+        # Retrieves info of all PIT segments
+        #
+        # @option arguments [String] :format a short version of the Accept header, e.g. json, yaml
+        # @option arguments [List] :h Comma-separated list of column names to display
+        # @option arguments [Boolean] :help Return help information
+        # @option arguments [List] :s Comma-separated list of column names or column aliases to sort by
+        # @option arguments [Boolean] :v Verbose mode. Display column headers
+        # @option arguments [Hash] :headers Custom HTTP headers
+        def all_pit_segments(arguments = {})
+          arguments = arguments.clone
+          headers = arguments.delete(:headers) || {}
+
+
+          method = OpenSearch::API::HTTP_GET
+          path   = '_cat/pit_segments/_all'
+          params = Utils.__validate_and_extract_params arguments, ParamsRegistry.get(__method__)
+          params[:h] = Utils.__listify(params[:h]) if params[:h]
+
+          body = nil
+          perform_request(method, path, params, body, headers).body
+        end
+
+        ParamsRegistry.register(:all_pit_segments, [
+          :format,
+          :h,
+          :help,
+          :s,
+          :v
+        ].freeze)
+      end
+    end
+  end
+end

opensearch-api/lib/opensearch/api/actions/cat/pit_segments.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.
+
+module OpenSearch
+  module API
+    module Cat
+      module Actions
+        # Retrieves info of certain PIT segments
+        #
+        # @option arguments [Hash] body: Must include `pit_id`, which is an array of PIT IDs. (required)
+        # @option arguments [String] :format a short version of the Accept header, e.g. json, yaml
+        # @option arguments [List] :h Comma-separated list of column names to display
+        # @option arguments [Boolean] :help Return help information
+        # @option arguments [List] :s Comma-separated list of column names or column aliases to sort by
+        # @option arguments [Boolean] :v Verbose mode. Display column headers
+        # @option arguments [Hash] :headers Custom HTTP headers
+        def pit_segments(arguments = {})
+          raise ArgumentError, "Required argument 'body' missing" unless arguments[:body]
+
+          arguments = arguments.clone
+          headers = arguments.delete(:headers) || {}
+
+
+          method = OpenSearch::API::HTTP_GET
+          path   = '_cat/pit_segments'
+          params = Utils.__validate_and_extract_params arguments, ParamsRegistry.get(__method__)
+          params[:h] = Utils.__listify(params[:h]) if params[:h]
+
+          body = arguments[:body]
+          perform_request(method, path, params, body, headers).body
+        end
+
+        ParamsRegistry.register(:pit_segments, [
+          :format,
+          :h,
+          :help,
+          :s,
+          :v
+        ].freeze)
+      end
+    end
+  end
+end

opensearch-api/lib/opensearch/api/actions/create_pit.rb

@@ -0,0 +1,45 @@
+# 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.
+
+module OpenSearch
+  module API
+    module Actions
+      # Creates a point in time.
+      #
+      # @option arguments [String] :index The name(s) of the target index(es) for the PIT. May contain a comma-separated list or a wildcard index pattern. (required)
+      # @option arguments [String] :keep_alive The amount of time to keep the PIT. (required)
+      # @option arguments [String] :preference The node or the shard used to perform the search. (default: random)
+      # @option arguments [String] :routing Specifies to route search requests to a specific shard.
+      # @option arguments [String] :expand_wildcards The type of index that can match the wildcard pattern. Supports comma-separated values. (default: open)
+      # @option arguments [String] :allow_partial_pit_creation Specifies whether to create a PIT with partial failures. (default: false)
+      def create_pit(arguments = {})
+        raise ArgumentError, "Required argument 'index' missing" unless arguments[:index]
+        raise ArgumentError, "Required argument 'keep_alive' missing" unless arguments[:keep_alive]
+
+        arguments = arguments.clone
+        _index = arguments.delete(:index)
+
+        method = OpenSearch::API::HTTP_POST
+        path = "#{Utils.__listify(_index)}/_search/point_in_time"
+        params = Utils.__validate_and_extract_params arguments, ParamsRegistry.get(__method__)
+        body = nil
+
+        perform_request(method, path, params, body).body
+      end
+
+      ParamsRegistry.register(:create_pit, [
+        :keep_alive,
+        :preference,
+        :routing,
+        :expand_wildcards,
+        :allow_partial_pit_creation
+      ].freeze)
+    end
+  end
+end

opensearch-api/lib/opensearch/api/actions/delete_all_pits.rb

@@ -0,0 +1,26 @@
+# 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.
+
+module OpenSearch
+  module API
+    module Actions
+      # Deletes all PITs.
+      def delete_all_pits(arguments = {})
+        method = OpenSearch::API::HTTP_DELETE
+        path = "_search/point_in_time/_all"
+        params = Utils.__validate_and_extract_params arguments, ParamsRegistry.get(__method__)
+        body = nil
+
+        perform_request(method, path, params, body).body
+      end
+
+      ParamsRegistry.register(:delete_all_pits, [].freeze)
+    end
+  end
+end

opensearch-api/lib/opensearch/api/actions/delete_pit.rb

@@ -0,0 +1,30 @@
+# 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.
+
+module OpenSearch
+  module API
+    module Actions
+      # Deletes one or several PITs.
+      #
+      # @option arguments [Hash] body: Must include `pit_id`, which is an array of PIT IDs to be deleted. (required)
+      def delete_pit(arguments = {})
+        raise ArgumentError, "Required argument 'body' missing" unless arguments[:body]
+
+        method = OpenSearch::API::HTTP_DELETE
+        path = "_search/point_in_time"
+        params = Utils.__validate_and_extract_params arguments, ParamsRegistry.get(__method__)
+        body = arguments[:body]
+
+        perform_request(method, path, params, body).body
+      end
+
+      ParamsRegistry.register(:delete_pit, [].freeze)
+    end
+  end
+end

opensearch-api/lib/opensearch/api/actions/get_all_pits.rb

@@ -0,0 +1,26 @@
+# 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.
+
+module OpenSearch
+  module API
+    module Actions
+      # Gets all PITs.
+      def get_all_pits(arguments = {})
+        method = OpenSearch::API::HTTP_GET
+        path = "_search/point_in_time/_all"
+        params = Utils.__validate_and_extract_params arguments, ParamsRegistry.get(__method__)
+        body = nil
+
+        perform_request(method, path, params, body).body
+      end
+
+      ParamsRegistry.register(:get_all_pits, [].freeze)
+    end
+  end
+end