Added documentation

Signed-off-by: Ajay Gupta <[email protected]>
opensearch-project · Dec 22, 2022 · aa5c3f9 · aa5c3f9
1 parent 8d3018e
commit aa5c3f9
Show file tree

Hide file tree

Showing 6 changed files with 170 additions and 61 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -9,6 +9,7 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 - Added jsdoc for documentation generation ([#335](https://github.com/opensearch-project/opensearch-js/issues/335))
 - Documented Transport#request ([#335](https://github.com/opensearch-project/opensearch-js/issues/335))
 - Documented all API methods ([#335](https://github.com/opensearch-project/opensearch-js/issues/335))
+- Added point in time APIs ([#348](https://github.com/opensearch-project/opensearch-js/pull/348))
 ### Dependencies
 - Bumps `xmlbuilder2` from 2.4.1 to 3.0.2
 - Bumps `minimatch` from 3.0.4 to 3.1.2

diff --git a/USER_GUIDE.md b/USER_GUIDE.md
@@ -12,6 +12,7 @@
   - [Delete the index](#delete-the-index)
 
 ## Initializing a Client
+
 ```javascript
 'use strict';
 
@@ -70,14 +71,14 @@ const client = new Client({
         });
       }),
   }),
-  node: "https://search-xxx.region.es.amazonaws.com", // OpenSearch domain URL
+  node: 'https://search-xxx.region.es.amazonaws.com', // OpenSearch domain URL
 });
 ```
 
 #### Using AWS V3 SDK
 
 ```javascript
-const { defaultProvider } = require("@aws-sdk/credential-provider-node"); // V3 SDK.
+const { defaultProvider } = require('@aws-sdk/credential-provider-node'); // V3 SDK.
 const { Client } = require('@opensearch-project/opensearch');
 const { AwsSigv4Signer } = require('@opensearch-project/opensearch/aws');
 
@@ -97,101 +98,151 @@ const client = new Client({
       return credentialsProvider();
     },
   }),
-  node: "https://search-xxx.region.es.amazonaws.com", // OpenSearch domain URL
+  node: 'https://search-xxx.region.es.amazonaws.com', // OpenSearch domain URL
 });
 ```
 
 ## Create an Index
 
 ```javascript
-  console.log('Creating index:');
-
-  var index_name = 'books';
-  var settings = {
-    settings: {
-      index: {
-        number_of_shards: 4,
-        number_of_replicas: 3,
-      },
+console.log('Creating index:');
+
+var index_name = 'books';
+var settings = {
+  settings: {
+    index: {
+      number_of_shards: 4,
+      number_of_replicas: 3,
     },
-  };
+  },
+};
 
-  var response = await client.indices.create({
-    index: index_name,
-    body: settings,
-  });
+var response = await client.indices.create({
+  index: index_name,
+  body: settings,
+});
 
-  console.log(response.body);
+console.log(response.body);
 ```
 
 ## Add a Document to the Index
 
 ```javascript
-  console.log('Adding document:');
-
-  var document = {
-    title: 'The Outsider',
-    author: 'Stephen King',
-    year: '2018',
-    genre: 'Crime fiction',
-  };
-
-  var id = '1';
-
-  var response = await client.index({
-    id: id,
-    index: index_name,
-    body: document,
-    refresh: true,
-  });
+console.log('Adding document:');
+
+var document = {
+  title: 'The Outsider',
+  author: 'Stephen King',
+  year: '2018',
+  genre: 'Crime fiction',
+};
+
+var id = '1';
+
+var response = await client.index({
+  id: id,
+  index: index_name,
+  body: document,
+  refresh: true,
+});
 
-  console.log(response.body);
+console.log(response.body);
 ```
 
 ## Search for the Document
 
 ```javascript
-  console.log('Search results:');
-
-  var query = {
-    query: {
-      match: {
-        title: {
-          query: 'The Outsider',
-        },
+console.log('Search results:');
+
+var query = {
+  query: {
+    match: {
+      title: {
+        query: 'The Outsider',
       },
     },
-  };
+  },
+};
 
-  var response = await client.search({
-    index: index_name,
-    body: query,
-  });
+var response = await client.search({
+  index: index_name,
+  body: query,
+});
 
-  console.log(response.body.hits);
+console.log(response.body.hits);
 ```
 
 ## Delete the document
 
 ```javascript
-  console.log('Deleting document:');
+console.log('Deleting document:');
 
-  var response = await client.delete({
-    index: index_name,
-    id: id,
-  });
+var response = await client.delete({
+  index: index_name,
+  id: id,
+});
 
-  console.log(response.body);
+console.log(response.body);
 ```
 
 ## Delete the index
 
 ```javascript
-  console.log('Deleting index:');
+console.log('Deleting index:');
+
+var response = await client.indices.delete({
+  index: index_name,
+});
+
+console.log(response.body);
+```
+
+## Create a Point in Time
+
+```javascript
+console.log('Creating a PIT:');
+
+var response = await client.createPit({
+  index: 'books*',
+  keep_alive: '100m',
+  expand_wildcards: 'all',
+});
+
+console.log(response.body);
+```
+
+## Get all PITs
+
+```javascript
+console.log('Getting all PITs:');
+
+var response = await client.getAllPits();
+
+console.log(response.body);
+```
+
+## Delete a Point in Time
+
+```javascript
+console.log('Deleting a PIT:');
+
+var response = await client.deletePit({
+  body: {
+    pit_id: [
+      'o463QQEPbXktaW5kZXgtMDAwMDAxFkhGN09fMVlPUkVPLXh6MUExZ1hpaEEAFjBGbmVEZHdGU1EtaFhhUFc4ZkR5cWcAAAAAAAAAAAEWaXBPNVJtZEhTZDZXTWFFR05waXdWZwEWSEY3T18xWU9SRU8teHoxQTFnWGloQQAA',
+    ],
+  },
+});
+
+console.log(response.body);
+```
+
+## Delete all PITs
+
+```javascript
+console.log('Deleting all PITs:');
 
-  var response = await client.indices.delete({
-    index: index_name,
-  });
+var response = await client.deleteAllPits();
 
-  console.log(response.body);
+console.log(response.body);
 ```
diff --git a/api/api/create_pit.js b/api/api/create_pit.js
@@ -32,6 +32,25 @@ const snakeCase = {
   filterPath: 'filter_path',
 };
 
+/**
+ * Creates a point in time.
+ * <br/> See Also: {@link https://opensearch.org/docs/latest/opensearch/point-in-time-api#create-a-pit|Opensearch - Create a PIT}
+ * @memberOf API-PIT
+ *
+ * @param {Object} params
+ * @param {string} params.index - The name(s) of the target index(es) for the PIT. May contain a comma-separated list or a wildcard index pattern.
+ * @param {string} params.keep_alive - The amount of time to keep the PIT
+ * @param {string} [params.preference=random] - The node or the shard used to perform the search.
+ * @param {string} [params.routing] - Specifies to route search requests to a specific shard.
+ * @param {string} [params.expand_wildcards=open] - The type of index that can match the wildcard pattern. Supports comma-separated values.
+ * @param {string} [params.allow_partial_pit_creation=false] - Specifies whether to create a PIT with partial failures.
+ *
+ * @param {Object} [options] - Options for {@link Transport#request}
+ * @param {function} [callback] - Callback that handles errors and response
+ *
+ * @returns {{abort: function(), then: function(), catch: function()}|Promise<never>|*} {@link https://opensearch.org/docs/latest/opensearch/point-in-time-api#sample-response|Create PIT Response}
+ */
+
 function createPitApi(params, options, callback) {
   [params, options, callback] = normalizeArguments(params, options, callback);
 

diff --git a/api/api/delete_all_pits.js b/api/api/delete_all_pits.js
@@ -17,6 +17,18 @@ const { handleError, snakeCaseKeys, normalizeArguments, kConfigurationError } =
 const acceptedQuerystring = ['pretty', 'human', 'error_trace', 'source', 'filter_path'];
 const snakeCase = { errorTrace: 'error_trace', filterPath: 'filter_path' };
 
+/**
+ * Deletes all PITs in the OpenSearch cluster. The Delete All PITs API deletes only local PITs or mixed PITs (PITs created in both local and remote clusters). It does not delete fully remote PITs.
+ * <br/> See Also: {@link https://opensearch.org/docs/latest/opensearch/point-in-time-api#delete-pits|Opensearch - Delete PITs}
+ * @memberOf API-PIT
+ *
+ * @param {Object} params
+ *
+ * @param {Object} [options] - Options for {@link Transport#request}
+ * @param {function} [callback] - Callback that handles errors and response
+ *
+ * @returns {{abort: function(), then: function(), catch: function()}|Promise<never>|*} {@link https://opensearch.org/docs/latest/opensearch/point-in-time-api#sample-response-2|Delete all PITs Response}
+ */
 function deleteAllPitsApi(params, options, callback) {
   [params, options, callback] = normalizeArguments(params, options, callback);
 

diff --git a/api/api/delete_pit.js b/api/api/delete_pit.js
@@ -17,6 +17,20 @@ const { handleError, snakeCaseKeys, normalizeArguments, kConfigurationError } =
 const acceptedQuerystring = ['pretty', 'human', 'error_trace', 'source', 'filter_path'];
 const snakeCase = { errorTrace: 'error_trace', filterPath: 'filter_path' };
 
+/**
+ * Deletes one or several PITs. PITs are automatically deleted when the keep_alive time period elapses. However, to deallocate resources, you can delete a PIT using the Delete PIT API.
+ * <br/> See Also: {@link https://opensearch.org/docs/latest/opensearch/point-in-time-api#delete-pits|Opensearch - Delete PITs}
+ * @memberOf API-PIT
+ *
+ * @param {Object} params
+ * @param {Object} params.body
+ * @param {string[]} params.body.pit_id - The PIT IDs of the PITs to be deleted.
+ *
+ * @param {Object} [options] - Options for {@link Transport#request}
+ * @param {function} [callback] - Callback that handles errors and response
+ *
+ * @returns {{abort: function(), then: function(), catch: function()}|Promise<never>|*} {@link https://opensearch.org/docs/latest/opensearch/point-in-time-api#sample-response-2|Delete PIT Response}
+ */
 function deletePitApi(params, options, callback) {
   [params, options, callback] = normalizeArguments(params, options, callback);
 

diff --git a/api/api/get_all_pits.js b/api/api/get_all_pits.js
@@ -17,6 +17,18 @@ const { handleError, snakeCaseKeys, normalizeArguments, kConfigurationError } =
 const acceptedQuerystring = ['pretty', 'human', 'error_trace', 'source', 'filter_path'];
 const snakeCase = { errorTrace: 'error_trace', filterPath: 'filter_path' };
 
+/**
+ * Returns all PITs in the OpenSearch cluster.
+ * <br/> See Also: {@link https://opensearch.org/docs/latest/opensearch/point-in-time-api#list-all-pits|Opensearch - List all PITs}
+ * @memberOf API-PIT
+ *
+ * @param {Object} params
+ *
+ * @param {Object} [options] - Options for {@link Transport#request}
+ * @param {function} [callback] - Callback that handles errors and response
+ *
+ * @returns {{abort: function(), then: function(), catch: function()}|Promise<never>|*} {@link https://opensearch.org/docs/latest/opensearch/point-in-time-api#sample-response-1|List all PITs Response}
+ */
 function getAllPitsApi(params, options, callback) {
   [params, options, callback] = normalizeArguments(params, options, callback);