Added Gradle dependency

OpenSearch High-Level REST Client

README.md

@@ -196,17 +196,17 @@ If you're making major changes to the documentation and need to see the rendered
 ## New releases
 
 1. Branch.
-1. Change the `opensearch_version` and `opensearch_major_minor_version` variables in `_config.yml`.
+1. Change the `opensearch_version`, `opensearch_major_minor_version`, and `lucene_version` variables in `_config.yml`.
 1. Start up a new cluster using the updated Docker Compose file in `docs/install/docker.md`.
 1. Update the version table in `version-history.md`.
 
-   Use `curl -XGET https://localhost:9200 -u admin:admin -k` to verify the OpenSearch version.
+   Use `curl -XGET https://localhost:9200 -u admin:admin -k` to verify the OpenSearch and Lucene versions.
 
-1. Update the plugin compatibility table in `docs/install/plugin.md`.
+1. Update the plugin compatibility table in `_opensearch/install/plugin.md`.
 
    Use `curl -XGET https://localhost:9200/_cat/plugins -u admin:admin -k` to get the correct version strings.
 
-1. Update the plugin compatibility table in `docs/opensearch-dashboards/plugins.md`.
+1. Update the plugin compatibility table in `_dashboards/install/plugins.md`.
 
    Use `docker ps` to find the ID for the OpenSearch Dashboards node. Then use `docker exec -it <opensearch-dashboards-node-id> /bin/bash` to get shell access. Finally, run `./bin/opensearch-dashboards-plugin list` to get the plugins and version strings.
 

_clients/go.md

@@ -0,0 +1,145 @@
+---
+layout: default
+title: Go client
+nav_order: 80
+---
+
+# Go client
+
+The OpenSearch Go client lets you connect your Go application with the data in your OpenSearch cluster.
+
+
+## Setup
+
+If you're creating a new project:
+
+```go
+go mod init
+```
+
+To add the client to your project, import it like any other module:
+
+```go
+go get github.com/opensearch-project/opensearch-go
+```
+
+## Sample code
+
+This sample code creates a client, adds an index with non-default settings, inserts a document, searches for the document, deletes the document, and finally deletes the index:
+
+```go
+package main
+import (
+    "os"
+    "context"
+    "crypto/tls"
+    "fmt"
+    opensearch "github.com/opensearch-project/opensearch-go"
+    opensearchapi "github.com/opensearch-project/opensearch-go/opensearchapi"
+    "net/http"
+    "strings"
+)
+const IndexName = "go-test-index1"
+func main() {
+    // Initialize the client with SSL/TLS enabled.
+    client, err := opensearch.NewClient(opensearch.Config{
+        Transport: &http.Transport{
+            TLSClientConfig: &tls.Config{InsecureSkipVerify: true},
+        },
+        Addresses: []string{"https://localhost:9200"},
+        Username:  "admin", // For testing only. Don't store credentials in code.
+        Password:  "admin",
+    })
+    if err != nil {
+        fmt.Println("cannot initialize", err)
+        os.Exit(1)
+    }
+
+    // Print OpenSearch version information on console.
+    fmt.Println(client.Info())
+
+    // Define index mapping.
+    mapping := strings.NewReader(`{
+     'settings': {
+       'index': {
+            'number_of_shards': 4
+            }
+          }
+     }`)
+
+    // Create an index with non-default settings.
+    res := opensearchapi.CreateRequest{
+        Index: IndexName,
+        Body:  mapping,
+    }
+    fmt.Println("creating index", res)
+
+    // Add a document to the index.
+    document := strings.NewReader(`{
+        "title": "Moneyball",
+        "director": "Bennett Miller",
+        "year": "2011"
+    }`)
+
+    docId := "1"
+    req := opensearchapi.IndexRequest{
+        Index:      IndexName,
+        DocumentID: docId,
+        Body:       document,
+    }
+    insertResponse, err := req.Do(context.Background(), client)
+    if err != nil {
+        fmt.Println("failed to insert document ", err)
+        os.Exit(1)
+    }
+    fmt.Println(insertResponse)
+
+    // Search for the document.
+    content := strings.NewReader(`{
+       "size": 5,
+       "query": {
+           "multi_match": {
+           "query": "miller",
+           "fields": ["title^2", "director"]
+           }
+      }
+    }`)
+
+    search := opensearchapi.SearchRequest{
+        Body: content,
+    }
+
+    searchResponse, err := search.Do(context.Background(), client)
+    if err != nil {
+        fmt.Println("failed to search document ", err)
+        os.Exit(1)
+    }
+    fmt.Println(searchResponse)
+
+    // Delete the document.
+    delete := opensearchapi.DeleteRequest{
+        Index:      IndexName,
+        DocumentID: docId,
+    }
+
+    deleteResponse, err := delete.Do(context.Background(), client)
+    if err != nil {
+        fmt.Println("failed to delete document ", err)
+        os.Exit(1)
+    }
+    fmt.Println("deleting document")
+    fmt.Println(deleteResponse)
+
+    // Delete previously created index.
+    deleteIndex := opensearchapi.IndicesDeleteRequest{
+        Index: []string{IndexName},
+    }
+
+    deleteIndexResponse, err := deleteIndex.Do(context.Background(), client)
+    if err != nil {
+        fmt.Println("failed to delete index ", err)
+        os.Exit(1)
+    }
+    fmt.Println("deleting index", deleteIndexResponse)
+}
+```

_clients/grafana.md

@@ -0,0 +1,10 @@
+---
+layout: default
+title: Grafana
+nav_order: 150
+has_children: false
+---
+
+# Grafana support
+
+Grafana has a data source plugin that lets you explore and visualize your OpenSearch data. For information on getting started with the plugin, see the [Grafana overview page](https://grafana.com/grafana/plugins/grafana-opensearch-datasource/).

_clients/index.md

@@ -9,6 +9,20 @@ redirect_from:
 
 # OpenSearch client compatibility
 
+OpenSearch provides clients for several popular programming languages, with more coming. In general, clients are compatible with clusters running the same major version of OpenSearch (`major.minor.patch`).
+
+For example, a 1.0.0 client works with an OpenSearch 1.1.0 cluster, but might not support any non-breaking API changes in OpenSearch 1.1.0. A 1.2.0 client works with the same cluster, but might allow you to pass unsupported options in certain functions. We recommend using the same version for both, but if your tests pass after a cluster upgrade, you don't necessarily need to upgrade your clients immediately.
+
+{% comment %}
+* [OpenSearch Java client]({{site.url}}{{site.baseurl}}/clients/java/)
+{% endcomment %}
+* [OpenSearch Python client]({{site.url}}{{site.baseurl}}/clients/python/)
+* [OpenSearch JavaScript (Node.js) client]({{site.url}}{{site.baseurl}}/clients/javascript/)
+* [OpenSearch Go client]({{site.url}}{{site.baseurl}}/clients/go/)
+
+
+## Legacy clients
+
 Most clients that work with Elasticsearch OSS 7.10.2 *should* work with OpenSearch, but the latest versions of those clients might include license or version checks that artificially break compatibility. This page includes recommendations around which versions of those clients to use for best compatibility with OpenSearch.
 
 Client | Recommended version
@@ -18,7 +32,7 @@ Client | Recommended version
 [Python Elasticsearch client](https://pypi.org/project/elasticsearch/7.13.4/) | 7.13.4
 [Elasticsearch Node.js client](https://www.npmjs.com/package/@elastic/elasticsearch/v/7.13.0) | 7.13.0
 
-Clients exist for a wide variety of languages, so if you test a client and verify that it works, please [submit a PR](https://github.com/opensearch-project/documentation-website/pulls) and add it to this table.
+If you test a legacy client and verify that it works, please [submit a PR](https://github.com/opensearch-project/documentation-website/pulls) and add it to this table.
 
 
 {% comment %}

_clients/java-rest-high-level.md

@@ -1,28 +1,29 @@
 ---
 layout: default
-title: Java high-level REST client
+title: OpenSearch Java high-level REST client
-nav_order: 97
+nav_order: 60
 ---
 
-# Java high-level REST client
+# OpenSearch Java high-level REST client
 
-The Elasticsearch OSS Java high-level REST client allows you to interact with your OpenSearch clusters and indices through Java methods and data structures rather than HTTP methods and JSON.
+Although the OpenSearch Java high-level REST client is still usable, we recommend that you use the [OpenSearch Java client]({{site.url}}{{site.baseurl}}/clients/java/), which replaces the existing Java high-level REST client.
+{: .note}
 
-You submit requests to your cluster using request objects, which allows you to create indices, add data to documents, or complete other operations with your cluster. In return, you get back response objects that have all of the available information, such as the associated index or ID, from your cluster.
+The OpenSearch Java high-level REST client lets you interact with your OpenSearch clusters and indices through Java methods and data structures rather than HTTP methods and JSON.
 
 ## Setup
 
-To start using the Elasticsearch OSS Java high-level REST client, ensure that you have the following dependency in your project's `pom.xml` file:
+To start using the OpenSearch Java high-level REST client, ensure that you have the following dependency in your project's `pom.xml` file:
 
 ```
 <dependency>
-  <groupId>org.elasticsearch.client</groupId>
+  <groupId>org.opensearch.client</groupId>
-  <artifactId>elasticsearch-rest-high-level-client</artifactId>
+  <artifactId>opensearch-rest-high-level-client</artifactId>
-  <version>7.10.2</version>
+  <version>{{site.opensearch_version}}</version>
 </dependency>
 ```
 
-You can now start your OpenSearch cluster. The 7.10.2 high-level REST client works with the 1.x versions of OpenSearch.
+You can now start your OpenSearch cluster. The OpenSearch 1.x high-level REST client works with the 1.x versions of OpenSearch.
 
 ## Sample code
 
@@ -33,22 +34,21 @@ import org.apache.http.auth.UsernamePasswordCredentials;
 import org.apache.http.client.CredentialsProvider;
 import org.apache.http.impl.client.BasicCredentialsProvider;
 import org.apache.http.impl.nio.client.HttpAsyncClientBuilder;
-import org.elasticsearch.action.admin.indices.delete.DeleteIndexRequest;
+import org.opensearch.action.admin.indices.delete.DeleteIndexRequest;
-import org.elasticsearch.action.delete.DeleteRequest;
+import org.opensearch.action.delete.DeleteRequest;
-import org.elasticsearch.action.delete.DeleteResponse;
+import org.opensearch.action.delete.DeleteResponse;
-import org.elasticsearch.action.get.GetRequest;
+import org.opensearch.action.get.GetRequest;
-import org.elasticsearch.action.get.GetResponse;
+import org.opensearch.action.get.GetResponse;
-import org.elasticsearch.action.index.IndexRequest;
+import org.opensearch.action.index.IndexRequest;
-import org.elasticsearch.action.index.IndexResponse;
+import org.opensearch.action.index.IndexResponse;
-import org.elasticsearch.action.support.master.AcknowledgedResponse;
+import org.opensearch.action.support.master.AcknowledgedResponse;
-import org.elasticsearch.client.RequestOptions;
+import org.opensearch.client.RequestOptions;
-import org.elasticsearch.client.RestClient;
+import org.opensearch.client.RestClient;
-import org.elasticsearch.client.RestClientBuilder;
+import org.opensearch.client.RestClientBuilder;
-import org.elasticsearch.client.RestHighLevelClient;
+import org.opensearch.client.RestHighLevelClient;
-import org.elasticsearch.client.indices.CreateIndexRequest;
+import org.opensearch.client.indices.CreateIndexRequest;
-import org.elasticsearch.client.indices.CreateIndexResponse;
+import org.opensearch.client.indices.CreateIndexResponse;
-import org.elasticsearch.common.settings.Settings;
+import org.opensearch.common.settings.Settings;
-import org.elasticsearch.common.xcontent.XContentType;
 
 import java.io.IOException;
 import java.util.HashMap;
@@ -59,7 +59,7 @@ public class RESTClientSample {
 
     //Point to keystore with appropriate certificates for security.
     System.setProperty("javax.net.ssl.trustStore", "/full/path/to/keystore");
-    System.setProperty("javax.net.ssl.trustStorePassword", password-to-keystore);
+    System.setProperty("javax.net.ssl.trustStorePassword", "password-to-keystore");
 
     //Establish credentials to use basic authentication.
     //Only for demo purposes. Do not specify your credentials in code.
@@ -93,7 +93,7 @@ public class RESTClientSample {
     HashMap<String, Object> mapping = new HashMap<String, Object>();
     mapping.put("properties", ageMapping);
     createIndexRequest.mapping(mapping);
-    CreateIndexResponse createIndexResponse = client.indices().create(createIndexRequest, RequestOptions.DEFAULT
+    CreateIndexResponse createIndexResponse = client.indices().create(createIndexRequest, RequestOptions.DEFAULT);
 
     //Adding data to the index.
     IndexRequest request = new IndexRequest("custom-index"); //Add a document to the custom-index we created.
@@ -122,3 +122,13 @@ public class RESTClientSample {
   }
 }
 ```
+
+## Elasticsearch OSS Java high-level REST client
+
+We recommend using the OpenSearch client to connect to OpenSearch clusters, but if you must use the Elasticsearch OSS Java high-level REST client, version 7.10.2 of the Elasticsearch OSS client also works with the 1.x versions of OpenSearch.
+
+### Migrating to the OpenSearch Java high-level REST client
+
+Migrating from the Elasticsearch OSS client to the OpenSearch high-level REST client is as simple as changing your Maven dependency to one that references [OpenSearch's dependency](#setup).
+
+Afterward, change all references of `org.elasticsearch` to `org.opensearch`, and you're ready to start submitting requests to your OpenSearch cluster.

_clients/java.md

@@ -0,0 +1,165 @@
+---
+layout: default
+title: OpenSearch Java client
+nav_order: 65
+---
+
+# Java client
+
+The OpenSearch Java client allows you to interact with your OpenSearch clusters through Java methods and data structures rather than HTTP methods and raw JSON.
+
+For example, you can submit requests to your cluster using objects to create indices, add data to documents, or complete some other operation using the client's built-in methods.
+
+## Setup
+
+To start using the OpenSearch Java client, ensure that you have the following dependency in your project's `pom.xml` file:
+
+```
+<dependency>
+  <groupId>org.opensearch.client</groupId>
+  <artifactId>opensearch-java</artifactId>
+  <version>0.1.0</version>
+</dependency>
+```
+
+If you're using Gradle, add the following dependencies to your project.
+
+```
+dependencies {
+    implementation 'org.opensearch.client:opensearch-rest-client: {{site.opensearch_version}}'
+    implementation 'org.opensearch.client:opensearch-java:0.1.0'
+}
+```
+
+You can now start your OpenSearch cluster.
+
+The following example uses credentials that come with the default OpenSearch configuration. If you're using the OpenSearch Java client with your own OpenSearch cluster, be sure to change the code to use your own credentials.
+
+## Sample code
+
+This section uses a class called `IndexData`, which is a simple Java class that stores basic data and methods. For your own OpenSearch cluster, you might find that you need a more robust class to store your data.
+
+### IndexData class
+
+```java
+static class IndexData {
+  private String firstName;
+  private String lastName;
+
+  public IndexData(String firstName, String lastName) {
+    this.firstName = firstName;
+    this.lastName = lastName;
+  }
+
+  public String getFirstName() {
+    return firstName;
+  }
+
+  public void setFirstName(String firstName) {
+    this.firstName = firstName;
+  }
+
+  public String getLastName() {
+    return lastName;
+  }
+
+  public void setLastName(String lastName) {
+    this.lastName = lastName;
+  }
+
+  @Override
+  public String toString() {
+    return String.format("IndexData{first name='%s', last name='%s'}", firstName, lastName);
+  }
+}
+```
+
+### OpenSearch client example
+
+```java
+import org.apache.http.HttpHost;
+import org.apache.http.auth.AuthScope;
+import org.apache.http.auth.UsernamePasswordCredentials;
+import org.apache.http.client.CredentialsProvider;
+import org.apache.http.impl.client.BasicCredentialsProvider;
+import org.apache.http.impl.nio.client.HttpAsyncClientBuilder;
+import org.opensearch.client.RestClient;
+import org.opensearch.client.RestClientBuilder;
+import org.opensearch.clients.base.RestClientTransport;
+import org.opensearch.clients.base.Transport;
+import org.opensearch.clients.json.jackson.JacksonJsonpMapper;
+import org.opensearch.clients.opensearch.OpenSearchClient;
+import org.opensearch.clients.opensearch._global.IndexRequest;
+import org.opensearch.clients.opensearch._global.IndexResponse;
+import org.opensearch.clients.opensearch._global.SearchResponse;
+import org.opensearch.clients.opensearch.indices.*;
+import org.opensearch.clients.opensearch.indices.put_settings.IndexSettingsBody;
+
+import java.io.IOException;
+
+public class OpenSearchClientExample {
+  public static void main(String[] args) {
+    try{
+    System.setProperty("javax.net.ssl.trustStore", "/full/path/to/keystore");
+    System.setProperty("javax.net.ssl.trustStorePassword", "password-to-keystore");
+
+    //Only for demo purposes. Don't specify your credentials in code.
+    final CredentialsProvider credentialsProvider = new BasicCredentialsProvider();
+    credentialsProvider.setCredentials(AuthScope.ANY,
+      new UsernamePasswordCredentials("admin", "admin"));
+
+    //Initialize the client with SSL and TLS enabled
+    RestClient restClient = RestClient.builder(new HttpHost("localhost", 9200, "https")).
+      setHttpClientConfigCallback(new RestClientBuilder.HttpClientConfigCallback() {
+        @Override
+        public HttpAsyncClientBuilder customizeHttpClient(HttpAsyncClientBuilder httpClientBuilder) {
+        return httpClientBuilder.setDefaultCredentialsProvider(credentialsProvider);
+        }
+      }).build();
+    Transport transport = new RestClientTransport(restClient, new JacksonJsonpMapper());
+    OpenSearchClient client = new OpenSearchClient(transport);
+
+    //Create the index
+    String index = "sample-index";
+    CreateRequest createIndexRequest = new CreateRequest.Builder().index(index).build();
+    client.indices().create(createIndexRequest);
+
+    //Add some settings to the index
+    IndexSettings indexSettings = new IndexSettings.Builder().autoExpandReplicas("0-all").build();
+    IndexSettingsBody settingsBody = new IndexSettingsBody.Builder().settings(indexSettings).build();
+    PutSettingsRequest putSettingsRequest = new PutSettingsRequest.Builder().index(index).value(settingsBody).build();
+    client.indices().putSettings(putSettingsRequest);
+
+    //Index some data
+    IndexData indexData = new IndexData("first_name", "Bruce");
+    IndexRequest<IndexData> indexRequest = new IndexRequest.Builder<IndexData>().index(index).id("1").value(indexData).build();
+    client.index(indexRequest);
+
+    //Search for the document
+    SearchResponse<IndexData> searchResponse = client.search(s -> s.index(index), IndexData.class);
+    for (int i = 0; i< searchResponse.hits().hits().size(); i++) {
+      System.out.println(searchResponse.hits().hits().get(i).source());
+    }
+
+    //Delete the document
+    client.delete(b -> b.index(index).id("1"));
+
+    // Delete the index
+    DeleteRequest deleteRequest = new DeleteRequest.Builder().index(index).build();
+    DeleteResponse deleteResponse = client.indices().delete(deleteRequest);
+
+    restClient.close();
+    } catch (IOException e){
+      System.out.println(e.toString());
+    } finally {
+			try {
+				if (client != null) {
+					client.close();
+				}
+			} catch (IOException e) {
+				System.out.println(e.toString());
+			}
+		}
+  }
+}
+```

_clients/javascript.md

@@ -0,0 +1,141 @@
+---
+layout: default
+title: JavaScript client
+nav_order: 90
+---
+
+# JavaScript client
+
+The OpenSearch JavaScript client provides a safer and easier way to interact with your OpenSearch cluster. Rather than using OpenSearch from the browser and potentially exposing your data to the public, you can build an OpenSearch client that takes care of sending requests to your cluster.
+
+The client contains a library of APIs that let you perform different operations on your cluster and return a standard response body. The example here demonstrates some basic operations like creating an index, adding documents, and searching your data.
+
+## Setup
+
+To add the client to your project, install it from [npm](https://www.npmjs.com):
+
+```bash
+npm install @opensearch-project/opensearch
+```
+
+To install a specific major version of the client, run the following command:
+
+```bash
+npm install @opensearch-project/opensearch@<version>
+```
+
+If you prefer to add the client manually or just want to examine the source code, see [opensearch-js](https://github.com/opensearch-project/opensearch-js) on GitHub.
+
+Then require the client:
+
+```javascript
+const { Client } = require("@opensearch-project/opensearch");
+```
+
+## Sample code
+
+```javascript
+"use strict";
+
+var host = "localhost";
+var protocol = "https";
+var port = 9200;
+var auth = "admin:admin"; // For testing only. Don't store credentials in code.
+var ca_certs_path = "/full/path/to/root-ca.pem";
+
+// Optional client certificates if you don't want to use HTTP basic authentication.
+// var client_cert_path = '/full/path/to/client.pem'
+// var client_key_path = '/full/path/to/client-key.pem'
+
+// Create a client with SSL/TLS enabled.
+var { Client } = require("@opensearch-project/opensearch");
+var fs = require("fs");
+var client = new Client({
+  node: protocol + "://" + auth + "@" + host + ":" + port,
+  ssl: {
+    ca: fs.readFileSync(ca_certs_path),
+    // You can turn off certificate verification (rejectUnauthorized: false) if you're using self-signed certificates with a hostname mismatch.
+    // cert: fs.readFileSync(client_cert_path),
+    // key: fs.readFileSync(client_key_path)
+  },
+});
+
+async function search() {
+  // Create an index with non-default settings.
+  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,
+  });
+
+  console.log("Creating index:");
+  console.log(response.body);
+
+  // Add a document to the index.
+  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:");
+  console.log(response.body);
+
+  // Search for the document.
+  var query = {
+    query: {
+      match: {
+        title: {
+          query: "The Outsider",
+        },
+      },
+    },
+  };
+
+  var response = await client.search({
+    index: index_name,
+    body: query,
+  });
+
+  console.log("Search results:");
+  console.log(response.body.hits);
+
+  // Delete the document.
+  var response = await client.delete({
+    index: index_name,
+    id: id,
+  });
+
+  console.log("Deleting document:");
+  console.log(response.body);
+
+  // Delete the index.
+  var response = await client.indices.delete({
+    index: index_name,
+  });
+
+  console.log("Deleting index:");
+  console.log(response.body);
+}
+
+search().catch(console.log);
+```

_clients/logstash/index.md

@@ -57,6 +57,9 @@ The OpenSearch Logstash plugin has two installation options at this time: Linux
 
 Make sure you have [Java Development Kit (JDK)](https://www.oracle.com/java/technologies/javase-downloads.html) version 8 or 11 installed.
 
+If you're migrating from an existing Logstash installation, you can install the [OpenSearch output plugin](https://rubygems.org/gems/logstash-output-opensearch/) manually and [update pipeline.conf](https://opensearch.org/docs/latest/clients/logstash/ship-to-opensearch/). We include this plugin by default in our tarball and Docker downloads.
+{: .note }
+
 ### Tarball
 
 1. Download the Logstash tarball from [OpenSearch downloads](https://opensearch.org/downloads.html).

_clients/python.md

@@ -0,0 +1,128 @@
+---
+layout: default
+title: Python client
+nav_order: 70
+---
+
+# Python client
+
+The OpenSearch Python client provides a more natural syntax for interacting with your cluster. Rather than sending HTTP requests to a given URL, you can create an OpenSearch client for your cluster and call the client's built-in functions.
+
+{% comment %}
+`opensearch-py` is the lower-level of the two Python clients. If you want a general client for assorted operations, it's a great choice. If you want a higher-level client strictly for indexing and search operations, consider [opensearch-dsl-py]({{site.url}}{{site.baseurl}}/clients/python-dsl/).
+{% endcomment %}
+
+
+## Setup
+
+To add the client to your project, install it using [pip](https://pip.pypa.io/):
+
+```bash
+pip install opensearch-py
+```
+
+Then import it like any other module:
+
+```python
+from opensearchpy import OpenSearch
+```
+
+If you prefer to add the client manually or just want to examine the source code, see [opensearch-py on GitHub](https://github.com/opensearch-project/opensearch-py).
+
+
+## Sample code
+
+```python
+from opensearchpy import OpenSearch
+
+host = 'localhost'
+port = 9200
+auth = ('admin', 'admin') # For testing only. Don't store credentials in code.
+ca_certs_path = '/full/path/to/root-ca.pem' # Provide a CA bundle if you use intermediate CAs with your root CA.
+
+# Optional client certificates if you don't want to use HTTP basic authentication.
+# client_cert_path = '/full/path/to/client.pem'
+# client_key_path = '/full/path/to/client-key.pem'
+
+# Create the client with SSL/TLS enabled, but hostname verification disabled.
+client = OpenSearch(
+    hosts = [{'host': host, 'port': port}],
+    http_compress = True, # enables gzip compression for request bodies
+    http_auth = auth,
+    # client_cert = client_cert_path,
+    # client_key = client_key_path,
+    use_ssl = True,
+    verify_certs = True,
+    ssl_assert_hostname = False,
+    ssl_show_warn = False,
+    ca_certs = ca_certs_path
+)
+
+# Create an index with non-default settings.
+index_name = 'python-test-index'
+index_body = {
+  'settings': {
+    'index': {
+      'number_of_shards': 4
+    }
+  }
+}
+
+response = client.indices.create(index_name, body=index_body)
+print('\nCreating index:')
+print(response)
+
+# Add a document to the index.
+document = {
+  'title': 'Moneyball',
+  'director': 'Bennett Miller',
+  'year': '2011'
+}
+id = '1'
+
+response = client.index(
+    index = index_name,
+    body = document,
+    id = id,
+    refresh = True
+)
+
+print('\nAdding document:')
+print(response)
+
+# Search for the document.
+q = 'miller'
+query = {
+  'size': 5,
+  'query': {
+    'multi_match': {
+      'query': q,
+      'fields': ['title^2', 'director']
+    }
+  }
+}
+
+response = client.search(
+    body = query,
+    index = index_name
+)
+print('\nSearch results:')
+print(response)
+
+# Delete the document.
+response = client.delete(
+    index = index_name,
+    id = id
+)
+
+print('\nDeleting document:')
+print(response)
+
+# Delete the index.
+response = client.indices.delete(
+    index = index_name
+)
+
+print('\nDeleting index:')
+print(response)
+```

_config.yml

@@ -1,13 +1,13 @@
 title: OpenSearch documentation
 description: >- # this means to ignore newlines until "baseurl:"
   Documentation for OpenSearch, the Apache 2.0 search, analytics, and visualization suite with advanced security, alerting, SQL support, automated index management, deep performance analysis, and more.
-baseurl: "/docs" # the subpath of your site, e.g. /blog
+baseurl: "/docs/latest" # the subpath of your site, e.g. /blog
 url: "https://opensearch.org" # the base hostname & protocol for your site, e.g. http://example.com
 permalink: /:path/
 
-opensearch_version: 1.0.1
+opensearch_version: 1.1.0
-opensearch_major_minor_version: 1.0
+opensearch_major_minor_version: 1.1
-lucene_version: 8_8_2
+lucene_version: 8_9_0
 
 # Build settings
 markdown: kramdown
@@ -45,6 +45,9 @@ collections:
   im-plugin:
     permalink: /:collection/:path/
     output: true
+  replication-plugin:
+    permalink: /:collection/:path/
+    output: true
   monitoring-plugins:
     permalink: /:collection/:path/
     output: true
@@ -81,6 +84,9 @@ just_the_docs:
     im-plugin:
       name: Index management plugin
       nav_fold: true
+    replication-plugin:
+      name: Replication plugin
+      nav_fold: true
     monitoring-plugins:
       name: Monitoring plugins
       nav_fold: true

_dashboards/dql.md

@@ -0,0 +1,142 @@
+---
+layout: default
+title: Dashboards query language
+nav_order: 99
+---
+
+# Dashboards Query Language
+
+Similar to the [Query DSL]({{site.url}}{{site.baseurl}}/opensearch/query-dsl/index) that lets you use the HTTP request body to search for data, you can use the Dashbaords Query Language (DQL) in OpenSearch Dashboards to search for data and visualizations.
+
+For example, if you want to see all visualizations of visits to a host based in the US, enter `geo.dest:US` into the search field, and Dashboards refreshes to display all related data.
+
+Just like the query DSL, DQL has a handful of query types, so use whichever best fits your use case.
+
+This section uses the OpenSearch Dashboards sample web log data. To add sample data in Dashboards, log in to OpenSearch Dashboards, choose **Home**, **Add sample data**, and then **Add data**.
+
+---
+
+#### Table of contents
+1. TOC
+{:toc}
+
+---
+
+## Terms query
+
+The most basic query is to just specify the term you're searching for.
+
+```
+host:www.example.com
+```
+
+To access an object's nested field, list the complete path to the field separated by periods. For example, to retrieve the `lat` field in the `coordinates` object:
+
+```
+coordinates.lat:43.7102
+```
+
+DQL also supports leading and trailing wildcards, so you can search for any terms that match your pattern.
+
+```
+host.keyword:*.example.com/*
+```
+
+To check if a field exists or has any data, use a wildcard to see if Dashboards returns any results.
+
+```
+host.keyword:*
+```
+
+## Boolean query
+
+To mix and match, or even combine, multiple queries for more refined results, you can use the boolean operators `and`, `or`, and `not`. DQL is not case sensitive, so `AND` and `and` are the same.
+
+```
+host.keyword:www.example.com and response.keyword:200
+```
+
+The following example demonstrates how to use multiple operators in one query.
+
+```
+geo.dest:US or response.keyword:200 and host.keyword:www.example.com
+```
+
+Remember that boolean operators follow the logical precedence order of `not`, `and`, and `or`, so if you have an expression like the previous example, `response.keyword:200 and host.keyword:www.example.com` gets evaluated first, and then Dashboards uses that result to compare with `geo.dest:US`.
+
+To avoid confusion, we recommend using parentheses to dictate the order you want to evaluate in. If you want to evaluate `geo.dest:US or response.keyword:200` first, your expression becomes:
+
+```
+(geo.dest:US or response.keyword:200) and host.keyword:www.example.com
+```
+
+## Date and range queries
+
+DQL also supports inequalities if you're using numeric inequalities.
+
+```
+bytes >= 15 and memory < 15
+```
+
+Similarly, you can use the same method to find a date before or after your query. `>` indicates a search for a date after your specified date, and `<` returns dates before.
+
+```
+@timestamp > "2020-12-14T09:35:33"
+```
+
+## Nested field query
+
+If you have a document with nested fields, you have to specify which parts of the document you want to retrieve.
+
+Suppose that you have the following document:
+
+```json
+{
+  "superheroes":[
+    {
+      "hero-name": "Superman",
+      "real-identity": "Clark Kent",
+      "age": 28
+    },
+    {
+      "hero-name": "Batman",
+      "real-identity": "Bruce Wayne",
+      "age": 26
+    },
+    {
+      "hero-name": "Flash",
+      "real-identity": "Barry Allen",
+      "age": 28
+    },
+    {
+      "hero-name": "Robin",
+      "real-identity": "Dick Grayson",
+      "age": 15
+    }
+  ]
+}
+```
+
+The following example demonstrates how to use DQL to retrieve a specific field.
+
+```
+superheroes: {hero-name: Superman}
+```
+
+If you want to retrieve multiple objects from your document, just specify all of the fields you want to retrieve.
+
+```
+superheroes: {hero-name: Superman} and superheroes: {hero-name: Batman}
+```
+
+The previous boolean and range queries still work, so you can submit a more refined query.
+
+```
+superheroes: {hero-name: Superman and age < 50}
+```
+
+If your document has an object nested within another object, you can still retrieve data by specifying all of the levels.
+
+```
+justice-league.superheroes: {hero-name:Superman}
+```

_dashboards/install/helm.md

@@ -20,7 +20,7 @@ Resource | Description
 The specification in the default Helm chart supports many standard use cases and setups. You can modify the default chart to configure your desired specifications and set Transport Layer Security (TLS) and role-based access control (RBAC).
 
 For information about the default configuration, steps to configure security, and configurable parameters, see the
-[README](https://github.com/opensearch-project/opensearch-devops/blob/main/Helm/README.md).
+[README](https://github.com/opensearch-project/helm-charts/tree/main/charts).
 
 The instructions here assume you have a Kubernetes cluster with Helm preinstalled. See the [Kubernetes documentation](https://kubernetes.io/docs/setup/) for steps to configure a Kubernetes cluster and the [Helm documentation](https://helm.sh/docs/intro/install/) to install Helm.
 {: .note }

_dashboards/install/plugins.md

@@ -28,6 +28,21 @@ If you don't want to use the all-in-one installation options, you can install th
     </tr>
   </thead>
   <tbody>
+  <tr>
+    <td>1.1.0</td>
+    <td>
+      <pre>alertingDashboards          1.1.0.0
+anomalyDetectionDashboards  1.1.0.0
+ganttChartDashboards        1.1.0.0
+indexManagementDashboards   1.1.0.0
+notebooksDashboards         1.1.0.0
+queryWorkbenchDashboards    1.1.0.0
+reportsDashboards           1.1.0.0
+securityDashboards          1.1.0.0
+traceAnalyticsDashboards    1.1.0.0
+</pre>
+    </td>
+  </tr>
   <tr>
     <td>1.0.1</td>
     <td>

_dashboards/install/tar.md

@@ -14,9 +14,10 @@ nav_order: 30
    ```bash
    # x64
    tar -zxf opensearch-dashboards-{{site.opensearch_version}}-linux-x64.tar.gz
-   cd opensearch-dashboards{% comment %}# ARM64
+   cd opensearch-dashboards
+   # ARM64
    tar -zxf opensearch-dashboards-{{site.opensearch_version}}-linux-arm64.tar.gz
-   cd opensearch-dashboards{% endcomment %}
+   cd opensearch-dashboards
    ```
 
 1. If desired, modify `config/opensearch_dashboards.yml`.
@@ -26,5 +27,3 @@ nav_order: 30
    ```bash
    ./bin/opensearch-dashboards
    ```
-
-1. See the [OpenSearch Dashboards documentation]({{site.url}}{{site.baseurl}}/dashboards/index/).

_data/_alert.yml

@@ -1 +0,0 @@
-message: "🔥 [OpenSearch 1.0 released on July 12th! Get it now!](/downloads.html)"

_data/alert.yml

@@ -0,0 +1 @@
+message: "🌡️ [OpenSearch 1.1.0 arrived October 5 with cross-cluster replication, bucket-level alerting, and much, much more. Grab it here!](/downloads.html)"

_data/versions.json

@@ -0,0 +1,6 @@
+{
+  "current": "1.1",
+  "past": [
+    "1.0"
+  ]
+}

_im-plugin/index-rollups/rollup-api.md

@@ -90,36 +90,36 @@ You can specify the following options.
 
 Options | Description | Type | Required
 :--- | :--- |:--- |:--- |
-`source_index` |  The name of the detector. | `string` | Yes
+`source_index` |  The name of the detector. | String | Yes
-`target_index` |  Specify the target index that the rolled up data is ingested into. You could either create a new target index or use an existing index. The target index cannot be a combination of raw and rolled up data. | `string` | Yes
+`target_index` |  Specify the target index that the rolled up data is ingested into. You could either create a new target index or use an existing index. The target index cannot be a combination of raw and rolled up data. | String | Yes
-`schedule` |  Schedule of the index rollup job which can be an interval or a cron expression. | `object` | Yes
+`schedule` |  Schedule of the index rollup job which can be an interval or a cron expression. | Object | Yes
-`schedule.interval`  |  Specify the frequency of execution of the rollup job. | `object` | No
+`schedule.interval`  |  Specify the frequency of execution of the rollup job. | Object | No
-`schedule.interval.start_time` | Start time of the interval. | `timestamp` | Yes
+`schedule.interval.start_time` | Start time of the interval. | Timestamp | Yes
-`schedule.interval.period` |  Define the interval period. | `string` | Yes
+`schedule.interval.period` |  Define the interval period. | String | Yes
-`schedule.interval.unit` | Specify the time unit of the interval. | `string` | Yes
+`schedule.interval.unit` | Specify the time unit of the interval. | String | Yes
-`schedule.interval.cron` | Optionally, specify a cron expression to define therollup frequency. | `list` | No
+`schedule.interval.cron` | Optionally, specify a cron expression to define therollup frequency. | List | No
-`schedule.interval.cron.expression` | Specify a Unix cron expression. | `string` | Yes
+`schedule.interval.cron.expression` | Specify a Unix cron expression. | String | Yes
-`schedule.interval.cron.timezone` | Specify timezones as defined by the IANA Time Zone Database. Defaults to UTC. | `string` | No
+`schedule.interval.cron.timezone` | Specify timezones as defined by the IANA Time Zone Database. Defaults to UTC. | String | No
-`description` | Optionally, describe the rollup job. | `string` | No
+`description` | Optionally, describe the rollup job. | String | No
-`enabled` | When true, the index rollup job is scheduled. Default is true. | `boolean` | Yes
+`enabled` | When true, the index rollup job is scheduled. Default is true. | Boolean | Yes
-`continuous` | Specify whether or not the index rollup job continuously rolls up data forever or just executes over the current data set once and stops. Default is false. | `boolean` | Yes
+`continuous` | Specify whether or not the index rollup job continuously rolls up data forever or just executes over the current data set once and stops. Default is false. | Boolean | Yes
-`error_notification` | Set up a Mustache message template sent for error notifications. For example, if an index rollup job fails, the system sends a message to a Slack channel. | `object` | No
+`error_notification` | Set up a Mustache message template sent for error notifications. For example, if an index rollup job fails, the system sends a message to a Slack channel. | Object | No
-`page_size` | Specify the number of buckets to paginate through at a time while rolling up. | `number` | Yes
+`page_size` | Specify the number of buckets to paginate through at a time while rolling up. | Number | Yes
-`delay` | Specify time value to delay execution of the index rollup job. | `time_unit` | No
+`delay` | The number of milliseconds to delay execution of the index rollup job. | Long | No
-`dimensions` | Specify aggregations to create dimensions for the roll up time window. | `object` | Yes
+`dimensions` | Specify aggregations to create dimensions for the roll up time window. | Object | Yes
-`dimensions.date_histogram` | Specify either fixed_interval or calendar_interval, but not both. Either one limits what you can query in the target index. | `object` | No
+`dimensions.date_histogram` | Specify either fixed_interval or calendar_interval, but not both. Either one limits what you can query in the target index. | Object | No
-`dimensions.date_histogram.fixed_interval` | Specify the fixed interval for aggregations in milliseconds, seconds, minutes, hours, or days. | `string` | No
+`dimensions.date_histogram.fixed_interval` | Specify the fixed interval for aggregations in milliseconds, seconds, minutes, hours, or days. | String | No
-`dimensions.date_histogram.calendar_interval` | Specify the calendar interval for aggregations in minutes, hours, days, weeks, months, quarters, or years. | `string` | No
+`dimensions.date_histogram.calendar_interval` | Specify the calendar interval for aggregations in minutes, hours, days, weeks, months, quarters, or years. | String | No
-`dimensions.date_histogram.field` | Specify the date field used in date histogram aggregation. | `string` | No
+`dimensions.date_histogram.field` | Specify the date field used in date histogram aggregation. | String | No
-`dimensions.date_histogram.timezone` | Specify the timezones as defined by the IANA Time Zone Database. The default is UTC. | `string` | No
+`dimensions.date_histogram.timezone` | Specify the timezones as defined by the IANA Time Zone Database. The default is UTC. | String | No
-`dimensions.terms` | Specify the term aggregations that you want to roll up. | `object` | No
+`dimensions.terms` | Specify the term aggregations that you want to roll up. | Object | No
-`dimensions.terms.fields` | Specify terms aggregation for compatible fields. | `object` | No
+`dimensions.terms.fields` | Specify terms aggregation for compatible fields. | Object | No
-`dimensions.histogram` | Specify the histogram aggregations that you want to roll up. | `object` | No
+`dimensions.histogram` | Specify the histogram aggregations that you want to roll up. | Object | No
-`dimensions.histogram.field` | Add a field for histogram aggregations. | `string` | Yes
+`dimensions.histogram.field` | Add a field for histogram aggregations. | String | Yes
-`dimensions.histogram.interval` | Specify the histogram aggregation interval for the field. | `long` | Yes
+`dimensions.histogram.interval` | Specify the histogram aggregation interval for the field. | Long | Yes
-`dimensions.metrics` | Specify a list of objects that represent the fields and metrics that you want to calculate. | `nested object` | No
+`dimensions.metrics` | Specify a list of objects that represent the fields and metrics that you want to calculate. | Nested object | No
-`dimensions.metrics.field` | Specify the field that you want to perform metric aggregations on. | `string` | No
+`dimensions.metrics.field` | Specify the field that you want to perform metric aggregations on. | String | No
-`dimensions.metrics.field.metrics` | Specify the metric aggregations you want to calculate for the field. | `multiple strings` | No
+`dimensions.metrics.field.metrics` | Specify the metric aggregations you want to calculate for the field. | Multiple strings | No
 
 
 #### Sample response

_im-plugin/index-transforms/index.md

@@ -29,7 +29,7 @@ If you don't have any data in your cluster, you can use the sample flight data w
 ### Step 1: Choose indices
 
 1. In the **Job name and description** section, specify a name and an optional description for your job.
-2. In the **Indices** section, select the source and target index. You can either select an existing target index or create a new one by entering a name for your new index. If you want to transform just a subset of your source index, choose **Add Data Filter**, and use the OpenSearch query DSL to specify a subset of your source index. For more information about the OpenSearch query DSL, see [query DSL]({{site.url}}{{site.baseurl}}/opensearch/query-dsl/).
+2. In the **Indices** section, select the source and target index. You can either select an existing target index or create a new one by entering a name for your new index. If you want to transform just a subset of your source index, choose **Edit data filter**, and use the OpenSearch query DSL to specify a subset of your source index. For more information about the OpenSearch query DSL, see [query DSL]({{site.url}}{{site.baseurl}}/opensearch/query-dsl/).
 3. Choose **Next**.
 
 ### Step 2: Select fields to transform

_im-plugin/ism/api.md

@@ -2,7 +2,7 @@
 layout: default
 title: ISM API
 parent: Index State Management
-nav_order: 5
+nav_order: 20
 ---
 
 # ISM API

_im-plugin/ism/index.md

@@ -31,14 +31,21 @@ To get started, choose **Index Management** in OpenSearch Dashboards.
 
 A policy is a set of rules that describes how an index should be managed. For information about creating a policy, see [Policies]({{site.url}}{{site.baseurl}}/im-plugin/ism/policies/).
 
+You can use the JSON editor or visual editor to create policies. Compared to the JSON editor, the visual editor offers a more structured way of defining policies by separating the process into creating error notifications, defining ISM templates, and adding states. We recommend using the visual editor if you want to see pre-defined fields, such as which actions you can assign to a state or under what conditions a state can transition into a destination state.
+
+#### JSON editor
+
 1. Choose the **Index Policies** tab.
 2. Choose **Create policy**.
-3. In the **Name policy** section, enter a policy ID.
+3. Choose **JSON editor**.
-4. In the **Define policy** section, enter your policy.
+4. In the **Name policy** section, enter a policy ID.
-5. Choose **Create**.
+5. In the **Define policy** section, enter your policy.
+6. Choose **Create**.
 
-After you create a policy, your next step is to attach this policy to an index or indices.
+After you create a policy, your next step is to attach it to an index or indices.
-You can set up an `ism_template` in the policy so when you create an index that matches the ISM template pattern, the index will have this policy attached to it:
+You can set up an `ism_template` in the policy so when an index that matches the ISM template pattern is created, the plugin automatically attaches the policy to the index.
+
+The following example demonstrates how to create a policy that automatically gets attached to all indices whose names start with `index_name-`.
 
 ```json
 PUT _plugins/_ism/policies/policy_id
@@ -55,6 +62,8 @@ PUT _plugins/_ism/policies/policy_id
 }
 ```
 
+If you have more than one template that matches an index pattern, ISM uses the priority value to determine which template to apply.
+
 For an example ISM template policy, see [Sample policy with ISM template]({{site.url}}{{site.baseurl}}/im-plugin/ism/policies#sample-policy-with-ism-template).
 
 Older versions of the plugin include the `policy_id` in an index template, so when an index is created that matches the index template pattern, the index will have the policy attached to it:

_im-plugin/ism/policies.md

@@ -558,10 +558,12 @@ The following sample template policy is for a rollover use case.
    PUT _index_template/ism_rollover
    {
      "index_patterns": ["log*"],
+     "template": {
       "settings": {
        "plugins.index_state_management.rollover_alias": "log"
       }
     }
+   }
    ```
 
 3. Create an index with the `log` alias:
@@ -586,6 +588,12 @@ The following sample template policy is for a rollover use case.
    }
    ```
 
+5. Verify if the policy is attached to the `log-000001` index:
+
+   ```json
+   GET _plugins/_ism/explain/log-000001?pretty
+   ```
+
 ## Example policy
 
 The following example policy implements a `hot`, `warm`, and `delete` workflow. You can use this policy as a template to prioritize resources to your indices based on their levels of activity.

_im-plugin/refresh-analyzer/index.md

@@ -1,7 +1,7 @@
 ---
 layout: default
 title: Refresh search analyzer
-nav_order: 40
+nav_order: 50
 has_children: false
 redirect_from: /im-plugin/refresh-analyzer/
 has_toc: false

_im-plugin/security.md

@@ -0,0 +1,41 @@
+---
+layout: default
+title: Index management security
+nav_order: 40
+has_children: false
+---
+
+# Index management security
+
+Using the security plugin with index management lets you limit non-admin users to certain actions. For example, you might want to set up your security such that a group of users can only read ISM policies, while others can create, delete, or change policies.
+
+All index management data are protected as system indices, and only a super admin or an admin with a Transport Layer Security (TLS) certificate can access system indices. For more information, see [System indices]({{site.url}}{{site.baseurl}}/security-plugin/configuration/system-indices).
+
+## Basic permissions
+
+The security plugin comes with one role that offers full access to index management: `index_management_full_access`. For a description of the role's permissions, see [Predefined roles]({{site.url}}{{site.baseurl}}/security-plugin/access-control/users-roles#predefined-roles).
+
+With security enabled, users not only need the correct index management permissions, but they also need permissions to execute actions to involved indices. For example, if a user wants to use the REST API to attach a policy that executes a rollup job to an index named `system-logs`, they would need the permissions to attach a policy and execute a rollup job, as well as access to `system-logs`.
+
+Finally, with the exceptions of Create Policy, Get Policy, and Delete Policy, users also need the `indices:admin/opensearch/ism/managedindex` permission to execute [ISM APIs]({{site.url}}{{site.baseurl}}/im-plugin/ism/api).
+
+## (Advanced) Limit access by backend role
+
+You can use backend roles to configure fine-grained access to index management policies and actions. For example, users of different departments in an organization might view different policies depending on what roles and permissions they are assigned.
+
+First, ensure your users have the appropriate [backend roles]({{site.url}}{{site.baseurl}}/security-plugin/access-control/index/). Backend roles usually come from an [LDAP server]({{site.url}}{{site.baseurl}}/security-plugin/configuration/ldap/) or [SAML provider]({{site.url}}{{site.baseurl}}/security-plugin/configuration/saml/). However, if you use the internal user database, you can use the REST API to [add them manually]({{site.url}}{{site.baseurl}}/security-plugin/access-control/api#create-user).
+
+Use the REST API to enable the following setting:
+
+```json
+PUT _cluster/settings
+{
+  "transient": {
+    "plugins.index_management.filter_by_backend_roles": "true"
+  }
+}
+```
+
+With security enabled, only users who share at least one backend role can see and execute the policies and actions relevant to their roles.
+
+For example, consider a scenario with three users: `John` and `Jill`, who have the backend role `helpdesk_staff`, and `Jane`, who has the backend role `phone_operator`. `John` wants to create a policy that performs a rollup job on an index named `airline_data`, so `John` would need a backend role that has permissions to access that index, create relevant policies, and execute relevant actions, and `Jill` would be able to access the same index, policy, and job. However, `Jane` cannot access or edit those resources or actions.

_includes/head_custom.html

@@ -6,3 +6,9 @@
   <script src="https://polyfill.io/v3/polyfill.min.js?features=es6"></script>
   <script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/[email protected]/es5/tex-mml-chtml.js"></script>
 {% endif %}
+
+{% if jekyll.environment == "development" %}
+  <script src="{{ '/assets/js/version-selector.js' | relative_url }}"></script>
+{% else %}
+  <script src="{{ '/docs/latest/assets/js/version-selector.js' }}"></script>
+{% endif %}

_layouts/default.html

@@ -57,6 +57,10 @@ layout: table_wrappers
         </a>
       </div>
       <nav role="navigation" aria-label="Main" id="site-nav" class="site-nav">
+        {% assign past_versions = site.data.versions.past | join: ";" %}
+        <div class="version-wrapper">
+          <version-selector selected="{{ site.data.versions.current }}"></version-selector>
+        </div>
         {% assign pages_top_size = site.html_pages
             | where_exp:"item", "item.title != nil"
             | where_exp:"item", "item.parent == nil"

_monitoring-plugins/ad/index.md

@@ -17,24 +17,19 @@ Anomaly detection  automatically detects anomalies in your OpenSearch data in ne
 
 You can pair the anomaly detection plugin with the [alerting plugin]({{site.url}}{{site.baseurl}}/monitoring-plugins/alerting/) to notify you as soon as an anomaly is detected.
 
-To use the anomaly detection plugin, your computer needs to have more than one CPU core.
-{: .note }
-
-## Get started with Anomaly Detection
-
 To get started, choose **Anomaly Detection** in OpenSearch Dashboards.
-To first test with sample streaming data, choose **Sample Detectors** and try out one of the preconfigured detectors.
+To first test with sample streaming data, you can try out one of the preconfigured detectors with one of the sample datasets.
 
-### Step 1: Create a detector
+## Step 1: Define a detector
 
-A detector is an individual anomaly detection task. You can create multiple detectors, and all the detectors can run simultaneously, with each analyzing data from different sources.
+A detector is an individual anomaly detection task. You can define multiple detectors, and all the detectors can run simultaneously, with each analyzing data from different sources.
 
-1. Choose **Create Detector**.
+1. Choose **Create detector**.
 1. Enter a name and brief description. Make sure the name is unique and descriptive enough to help you to identify the purpose of the detector.
 1. For **Data source**, choose the index you want to use as the data source. You can optionally use index patterns to choose multiple indices.
+1. (Optional) For **Data filter**, filter the index you chose as the data source. From the **Data filter** menu, choose **Add data filter**, and then design your filter query by selecting **Field**, **Operator**, and **Value**, or choose **Use query DSL** and add your own JSON filter query.
 1. Select the **Timestamp field** in your index.
-1. (Optional) For **Data filter**, filter the index you chose as the data source. From the **Filter type** menu, choose  **Visual filter**, and then design your filter query by selecting **Fields**, **Operator**, and **Value**, or choose **Custom Expression** and add your own JSON filter query.
+1. For **Operation settings**, define the **Detector interval**, which is the time interval at which the detector collects data.
-1. For **Detector operation settings**, define the **Detector interval**, which is the time interval at which the detector collects data.
 - The detector aggregates the data in this interval, then feeds the aggregated result into the anomaly detection model.
 The shorter you set this interval, the fewer data points the detector aggregates.
 The anomaly detection model uses a shingling process, a technique that uses consecutive data points to create a sample for the model. This process needs a certain number of aggregated data points from contiguous intervals.
@@ -44,42 +39,49 @@ Set the window delay to shift the detector interval to account for this delay.
 - For example, say the detector interval is 10 minutes and data is ingested into your cluster with a general delay of 1 minute.
 Assume the detector runs at 2:00. The detector attempts to get the last 10 minutes of data from 1:50 to 2:00, but because of the 1-minute delay, it only gets 9 minutes of data and misses the data from 1:59 to 2:00.
 Setting the window delay to 1 minute shifts the interval window to 1:49 - 1:59, so the detector accounts for all 10 minutes of the detector interval time.
-1. Choose **Create**.
+1. Choose **Next**.
 
-After you create the detector, the next step is to add features to it.
+After you define the detector, the next step is to configure the model.
 
-### Step 2: Add features to your detector
+## Step 2: Configure the model
+
+#### Add features to your detector
 
 A feature is the field in your index that you want to check for anomalies. A detector can discover anomalies across one or more features. You must choose an aggregation method for each feature: `average()`, `count()`, `sum()`, `min()`, or `max()`. The aggregation method determines what constitutes an anomaly.
 
 For example, if you choose `min()`, the detector focuses on finding anomalies based on the minimum values of your feature. If you choose `average()`, the detector finds anomalies based on the average values of your feature.
 
-A multi-feature model correlates anomalies across all its features. The [curse of dimensionality](https://en.wikipedia.org/wiki/Curse_of_dimensionality) makes it less likely for multi-feature models to identify smaller anomalies as compared to a single-feature model. Adding more features might negatively impact the [precision and recall](https://en.wikipedia.org/wiki/Precision_and_recall) of a model. A higher proportion of noise in your data might further amplify this negative impact. Selecting the optimal feature set is usually an iterative process. We recommend experimenting with a historical detector with different feature sets and checking the precision before moving on to real-time detectors. By default, the maximum number of features for a detector is 5. You can adjust this limit with the `plugins.anomaly_detection.max_anomaly_features` setting.
+A multi-feature model correlates anomalies across all its features. The [curse of dimensionality](https://en.wikipedia.org/wiki/Curse_of_dimensionality) makes it less likely for multi-feature models to identify smaller anomalies as compared to a single-feature model. Adding more features might negatively impact the [precision and recall](https://en.wikipedia.org/wiki/Precision_and_recall) of a model. A higher proportion of noise in your data might further amplify this negative impact. Selecting the optimal feature set is usually an iterative process. By default, the maximum number of features for a detector is 5. You can adjust this limit with the `plugins.anomaly_detection.max_anomaly_features` setting.
 {: .note }
 
-1. On the **Model configuration** page, enter the **Feature name**.
+1. On the **Configure Model** page, enter the **Feature name** and check **Enable feature**.
-1. For **Find anomalies based on**, choose the method to find anomalies. For **Field Value** menu, choose the **field** and the **aggregation method**. Or choose **Custom expression**, and add your own JSON aggregation query.
+1. For **Find anomalies based on**, choose the method to find anomalies. For **Field Value**, choose the **aggregation method**. Or choose **Custom expression**, and add your own JSON aggregation query.
+1. Select a field.
 
-#### (Optional) Set a category field for high cardinality
+#### (Optional) Set category fields for high cardinality
 
 You can categorize anomalies based on a keyword or IP field type.
 
 The category field categorizes or slices the source time series with a dimension like IP addresses, product IDs, country codes, and so on. This helps to see a granular view of anomalies within each entity of the category field to isolate and debug issues.
 
-To set a category field, choose **Enable a category field** and select a field.
+To set a category field, choose **Enable a category field** and select a field. You can’t change the category fields after you create the detector.
 
 Only a certain number of unique entities are supported in the category field. Use the following equation to calculate the recommended total number of entities supported in a cluster:
 
 ```
-(data nodes * heap size * anomaly detection maximum memory percentage) / (entity size of a detector)
+(data nodes * heap size * anomaly detection maximum memory percentage) / (entity model size of a detector)
 ```
 
+To get the entity model size of a detector, use the [profile detector API]({{site.url}}{{site.baseurl}}/monitoring-plugins/ad/api/#profile-detector). You can adjust the maximum memory percentage with the `plugins.anomaly_detection.model_max_size_percent` setting.
+
 This formula provides a good starting point, but make sure to test with a representative workload.
 {: .note }
 
-For example, for a cluster with 3 data nodes, each with 8G of JVM heap size, a maximum memory percentage of 10% (default), and the entity size of the detector as 1MB: the total number of unique entities supported is (8.096 * 10^9 * 0.1 / 1M ) * 3 = 2429.
+For example, for a cluster with three data nodes, each with 8 GB of JVM heap size, a maximum memory percentage of 10% (default), and the entity model size of the detector as 1MB: the total number of unique entities supported is (8.096 * 10^9 * 0.1 / 1 MB ) * 3 = 2429.
 
-#### Set a shingle size
+If the actual total number of unique entities higher than this number that you calculate (in this case: 2429), the anomaly detector makes its best effort to model the extra entities. The detector prioritizes entities that occur more often and are more recent.
+
+#### (Advanced settings) Set a shingle size
 
 Set the number of aggregation intervals from your data stream to consider in a detection window. It’s best to choose this value based on your actual data to see which one leads to the best results for your use case.
 
@@ -92,12 +94,27 @@ For sample previews, the anomaly detection plugin selects a small number of data
 
 Examine the sample preview and use it to fine-tune your feature configurations (for example, enable or disable features) to get more accurate results.
 
-1. Choose **Save and start detector**.
+1. Choose **Preview sample anomalies**.
-1. Choose between automatically starting the detector (recommended) or manually starting the detector at a later time.
+    - If you don't see any sample anomaly result, check the detector interval and make sure you have more than 400 data points for some entities during the preview date range.
+1. Choose **Next**.
 
-### Step 3: Observe the results
+## Step 3: Set up detector jobs
 
-Choose the **Anomaly results** tab. You need to wait for some time to see the anomaly results. If the detector interval is 10 minutes, the detector might take more than an hour to start, as it's waiting for sufficient data to generate anomalies.
+To start a real-time detector to find anomalies in your data in near real-time, check **Start real-time detector automatically (recommended)**.
+
+Alternatively, if you want to perform historical analysis and find patterns in long historical data windows (weeks or months), check **Run historical analysis detection** and select a date range (at least 128 detection intervals).
+
+Analyzing historical data helps you get familiar with the anomaly detection plugin. You can also evaluate the performance of a detector with historical data to further fine-tune it.
+
+We recommend experimenting with historical analysis with different feature sets and checking the precision before moving on to real-time detectors.
+
+## Step 4: Review and create
+
+Review your model configuration and select **Create detector**.
+
+## Step 5: Observe the results
+
+Choose the **Real-time results** or **Historical analysis** tab. For real-time results, you need to wait for some time to see the anomaly results. If the detector interval is 10 minutes, the detector might take more than an hour to start, as it's waiting for sufficient data to generate anomalies.
 
 A shorter interval means the model passes the shingle process more quickly and starts to generate the anomaly results sooner.
 Use the [profile detector]({{site.url}}{{site.baseurl}}/monitoring-plugins/ad/api#profile-detector) operation to make sure you have sufficient data points.
@@ -106,12 +123,12 @@ If you see the detector pending in "initialization" for longer than a day, aggre
 
 ![Anomaly detection results]({{site.url}}{{site.baseurl}}/images/ad.png)
 
-Analize anomalies with the following visualizations:
+Analyze anomalies with the following visualizations:
 
 - **Live anomalies** - displays live anomaly results for the last 60 intervals. For example, if the interval is 10, it shows results for the last 600 minutes. The chart refreshes every 30 seconds.
-- **Anomaly history** - plots the anomaly grade with the corresponding measure of confidence.
+- **Anomaly history** (for historical analysis) / **Anomaly overview** (for real-time results) - plots the anomaly grade with the corresponding measure of confidence.
-- **Feature breakdown** - plots the features based on the aggregation method. You can vary the date-time range of the detector.
 - **Anomaly occurrence** - shows the `Start time`, `End time`, `Data confidence`, and `Anomaly grade` for each detected anomaly.
+- **Feature breakdown** - plots the features based on the aggregation method. You can vary the date-time range of the detector.
 
 `Anomaly grade` is a number between 0 and 1 that indicates how anomalous a data point is. An anomaly grade of 0 represents “not an anomaly,” and a non-zero value represents the relative severity of the anomaly.
 
@@ -119,47 +136,26 @@ Analize anomalies with the following visualizations:
 
 If you set the category field, you see an additional **Heat map** chart. The heat map correlates results for anomalous entities. This chart is empty until you select an anomalous entity. You also see the anomaly and feature line chart for the time period of the anomaly (`anomaly_grade` > 0).
 
-Choose a filled rectangle to see a more detailed view of the anomaly.
+Choose and drag over the anomaly line chart to zoom in and see a more detailed view of an anomaly.
 {: .note }
 
-### Step 4: Set up alerts
+## Step 6: Set up alerts
 
-Choose **Set up alerts** and configure a monitor to notify you when anomalies are detected. For steps to create a monitor and set up notifications based on your anomaly detector, see [Monitors]({{site.url}}{{site.baseurl}}/monitoring-plugins/alerting/monitors/).
+Under **Real-time results**, choose **Set up alerts** and configure a monitor to notify you when anomalies are detected. For steps to create a monitor and set up notifications based on your anomaly detector, see [Monitors]({{site.url}}{{site.baseurl}}/monitoring-plugins/alerting/monitors/).
 
 If you stop or delete a detector, make sure to delete any monitors associated with it.
 
-### Step 5: Adjust the model
+## Step 7: Adjust the model
 
 To see all the configuration settings for a detector, choose the **Detector configuration** tab.
 
 1. To make any changes to the detector configuration, or fine tune the time interval to minimize any false positives, go to the **Detector configuration** section and choose **Edit**.
-- You need to stop the detector to change its configuration. Confirm that you want to stop the detector and proceed.
+- You need to stop real-time and historical analysis to change its configuration. Confirm that you want to stop the detector and proceed.
 1. To enable or disable features, in the **Features** section, choose **Edit** and adjust the feature settings as needed. After you make your changes, choose **Save and start detector**.
-- Choose between automatically starting the detector (recommended) or manually starting the detector at a later time.
 
-### Step 6: Analyze historical data
+## Step 8: Manage your detectors
 
-Analyzing historical data helps you get familiar with the anomaly detection plugin. You can also evaluate the performance of a detector with historical data to further fine-tune it.
+To start, stop, or delete a detector, go to the **Detectors** page.
 
-To use a historical detector, you need to specify a date range that has data present in at least 1,000 detection intervals.
+1. Choose the detector name.
-{: .note }
+2. Choose **Actions** and select **Start real-time detectors**, **Stop real-time detectors**, or **Delete detectors**.
-
-1. Choose **Historical detectors** and **Create historical detector**.
-1. Enter the **Name** of the detector and a brief **Description**.
-1. For **Data source**, choose the index to use as the data source. You can optionally use index patterns to choose multiple indices.
-1. For **Time range**, select a time range for historical analysis.
-1. For **Detector settings**, choose to use the settings of an existing detector. Or choose the **Timestamp field** in your index, add individual features to the detector, and set the detector interval.
-1. (Optional) Choose to run the historical detector automatically after creating it.
-1. Choose **Create**.
-   - You can stop the historical detector even before it completes.
-
-### Step 7: Manage your detectors
-
-To change or delete a detector, go to the **Detector details** page.
-
-1. To make changes to your detector, choose the detector name.
-1. Choose **Actions** and **Edit detector**.
-   - You need to stop the detector to change its configuration. Confirm that you want to stop the detector and proceed.
-1. Make your changes and choose **Save changes**.
-
-To delete your detector, choose **Actions** and **Delete detector**. In the pop-up box, type `delete` to confirm and choose **Delete**.

_monitoring-plugins/ad/settings.md

@@ -24,19 +24,24 @@ PUT _cluster/settings
 
 Setting | Default | Description
 :--- | :--- | :---
-`plugins.anomaly_detection.enabled` | True | Whether the anomaly detection plugin is enabled or not. If disabled, all detectors immediately stop running.
+plugins.anomaly_detection.enabled | True | Whether the anomaly detection plugin is enabled or not. If disabled, all detectors immediately stop running.
-`plugins.anomaly_detection.max_anomaly_detectors` | 1,000 | The maximum number of non-high cardinality detectors (no category field) users can create.
+plugins.anomaly_detection.max_anomaly_detectors | 1,000 | The maximum number of non-high cardinality detectors (no category field) users can create.
-`plugins.anomaly_detection.max_multi_entity_anomaly_detectors` | 10 | The maximum number of high cardinality detectors (with category field) in a cluster.
+plugins.anomaly_detection.max_multi_entity_anomaly_detectors | 10 | The maximum number of high cardinality detectors (with category field) in a cluster.
-`plugins.anomaly_detection.max_anomaly_features` | 5 | The maximum number of features for a detector.
+plugins.anomaly_detection.max_anomaly_features | 5 | The maximum number of features for a detector.
-`plugins.anomaly_detection.ad_result_history_rollover_period` | 12h | How often the rollover condition is checked. If `true`, the plugin rolls over the result index to a new index.
+plugins.anomaly_detection.ad_result_history_rollover_period | 12h | How often the rollover condition is checked. If `true`, the anomaly detection plugin rolls over the result index to a new index.
-`plugins.anomaly_detection.ad_result_history_max_docs` | 250000000 | The maximum number of documents in one result index. The plugin only counts refreshed documents in the primary shards.
+plugins.anomaly_detection.ad_result_history_max_docs_per_shard | 1,350,000,000 | The maximum number of documents in a single shard of the result index. The anomaly detection plugin only counts the refreshed documents in the primary shards.
-`plugins.anomaly_detection.ad_result_history_retention_period` | 30d | The maximum age of the result index.  If its age exceeds the threshold, the plugin deletes the rolled over result index. If the cluster has only one result index, the plugin keeps the index even if it's older than its configured retention period.
+plugins.anomaly_detection.max_entities_per_query | 1,000,000 | The maximum unique values per detection interval for high cardinality detectors. By default, if the category field(s) have more than the configured unique values in a detector interval, the anomaly detection plugin orders them by the natural ordering of categorical values (for example, entity `ab` comes before `bc`) and then selects the top values.
-`plugins.anomaly_detection.max_entities_per_query` | 1,000 | The maximum unique values per detection interval for high cardinality detectors. By default, if the category field has more than 1,000 unique values in a detector interval, the plugin selects the top 1,000 values and orders them by `doc_count`.
+plugins.anomaly_detection.max_entities_for_preview | 5 | The maximum unique category field values displayed with the preview operation for high cardinality detectors. By default, if the category field(s) have more than the configured unique values in a detector interval, the anomaly detection plugin orders them by the natural ordering of categorical values (for example, entity `ab` comes before `bc`) and then selects the top values.
-`plugins.anomaly_detection.max_entities_for_preview` | 30 | The maximum unique category field values displayed with the preview operation for high cardinality detectors. If the category field has more than 30 unique values, the plugin selects the top 30 values and orders them by `doc_count`.
+plugins.anomaly_detection.max_primary_shards | 10 | The maximum number of primary shards an anomaly detection index can have.
-`plugins.anomaly_detection.max_primary_shards` | 10 | The maximum number of primary shards an anomaly detection index can have.
+plugins.anomaly_detection.filter_by_backend_roles | False | When you enable the security plugin and set this to `true`, the anomaly detection plugin filters results based on the user's backend role(s).
-`plugins.anomaly_detection.filter_by_backend_roles` | False | When you enable the security plugin and set this to `true`, the plugin filters results based on the user's backend role(s).
+plugins.anomaly_detection.max_batch_task_per_node | 10 | Starting a historical analysis triggers a batch task. This setting is the number of batch tasks that you can run per data node. You can tune this setting from 1 to 1,000. If the data nodes can’t support all batch tasks and you’re not sure if the data nodes are capable of running more historical analysis, add more data nodes instead of changing this setting to a higher value. Increasing this value might bring more load on each data node.
-`plugins.anomaly_detection.max_cache_miss_handling_per_second` | 100 | High cardinality detectors use a cache to store active models. In the event of a cache miss, the cache gets the models from the model checkpoint index. Use this setting to limit the rate of fetching models. Because the thread pool for a GET operation has a queue of 1,000, we recommend setting this value below 1,000.
+plugins.anomaly_detection.max_old_ad_task_docs_per_detector | 1 | You can run historical analysis for the same detector many times. For each run, the anomaly detection plugin creates a new task. This setting is the number of previous tasks the plugin keeps. Set this value to at least 1 to track its last run. You can keep a maximum of 1,000 old tasks to avoid overwhelming the cluster.
-`plugins.anomaly_detection.max_batch_task_per_node` | 2 | Starting a historical detector triggers a batch task. This setting is the number of batch tasks that you can run per data node. You can tune this setting from 1 to 1000. If the data nodes can't support all batch tasks and you're not sure if the data nodes are capable of running more historical detectors, add more data nodes instead of changing this setting to a higher value.
+plugins.anomaly_detection.batch_task_piece_size | 1,000 | The date range for a historical task is split into smaller pieces and the anomaly detection plugin runs the task piece by piece. Each piece contains 1,000 detection intervals by default. For example, if detector interval is 1 minute and one piece is 1,000 minutes, the feature data is queried every 1,000 minutes. You can change this setting from 1 to 10,000.
-`plugins.anomaly_detection.max_old_ad_task_docs_per_detector` | 10 | You can run the same historical detector many times. For each run, the anomaly detection plugin creates a new task. This setting is the number of previous tasks the plugin keeps. Set this value to at least 1 to track its last run. You can keep a maximum of 1,000 old tasks to avoid overwhelming the cluster.
+plugins.anomaly_detection.batch_task_piece_interval_seconds | 5 | Add a time interval between two pieces of the same historical analysis task. This interval prevents the task from consuming too much of the available resources and starving other operations like search and bulk index. You can change this setting from 1 to 600 seconds.
-`plugins.anomaly_detection.batch_task_piece_size` | 1000 | The date range for a historical task is split into smaller pieces and the anomaly detection plugin runs the task piece by piece. Each piece contains 1,000 detection intervals by default. For example, if detector interval is 1 minute and one piece is 1000 minutes, the feature data is queried every 1,000 minutes. You can change this setting from 1 to 10,000.
+plugins.anomaly_detection.max_top_entities_for_historical_analysis | 1,000 | The maximum number of top entities that you run for a high cardinality detector historical analysis. The range is from 1 to 10,000.
-`plugins.anomaly_detection.batch_task_piece_interval_seconds` | 5 | Add a time interval between historical detector tasks. This interval prevents the task from consuming too much of the available resources and starving other operations like search and bulk index. You can change this setting from 1 to 600 seconds.
+plugins.anomaly_detection.max_running_entities_per_detector_for_historical_analysis | 10 | The number of entity tasks that you can run in parallel for a high cardinality detector analysis. The task slots available on your cluster also impact how many entities run in parallel. If a cluster has 3 data nodes, each data node has 10 task slots by default. Say you already have two high cardinality detectors and each of them run 10 entities. If you start a single-entity detector that takes 1 task slot, the number of task slots available is 10 * 3 - 10 * 2 - 1 = 9. If you now start a new high cardinality detector, the detector can only run 9 entities in parallel and not 10. You can tune this value from 1 to 1,000 based on your cluster's capability. If you set a higher value, the anomaly detection plugin runs historical analysis faster but also consumes more resources.
+plugins.anomaly_detection.max_cached_deleted_tasks | 1,000 | You can rerun historical analysis for a single detector as many times as you like. The anomaly detection plugin only keeps a limited number of old tasks, by default 1 old task. If you run historical analysis three times for a detector, the oldest task is deleted. Because historical analysis generates a number of anomaly results in a short span of time, it's necessary to clean up anomaly results for a deleted task. With this field, you can configure how many deleted tasks you can cache at most. The plugin cleans up a task's results when it's deleted. If the plugin fails to do this cleanup, it adds the task's results into a cache and an hourly cron job performs the cleanup. You can use this setting to limit how many old tasks are put into cache to avoid a DDoS attack. After an hour, if still you find an old task result in the cache, use the [delete detector results API]({{site.url}}{{site.baseurl}}/monitoring-plugins/ad/api/#delete-detector-results) to delete the task result manually. You can tune this setting from 1 to 10,000.
+plugins.anomaly_detection.delete_anomaly_result_when_delete_detector | False | Whether the anomaly detection plugin deletes the anomaly result when you delete a detector. If you want to save some disk space, especially if you've high cardinality detectors generating a lot of results, set this field to true. Alternatively, you can use the [delete detector results API]({{site.url}}{{site.baseurl}}/monitoring-plugins/ad/api/#delete-detector-results) to manually delete the results.
+plugins.anomaly_detection.dedicated_cache_size | 10 | If the real-time analysis of a high cardinality detector starts successfully, the anomaly detection plugin guarantees keeping 10 (dynamically adjustable via this setting) entities' models in memory per node. If the number of entities exceeds this limit, the plugin puts the extra entities' models in a memory space shared by all detectors. The actual number of entities varies based on the memory that you've available and the frequencies of the entities. If you'd like the plugin to guarantee keeping more entities' models in memory and if you're cluster has sufficient memory, you can increase this setting value.
+plugins.anomaly_detection.max_concurrent_preview | 2 | The maximum number of concurrent previews. You can use this setting to limit resource usage.
+plugins.anomaly_detection.model_max_size_percent | 0.1 | The upper bound of the memory percentage for a model.