Compare commits
1 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 keithhc2
|
7c892e1057 |
@@ -3,5 +3,3 @@ _site
|
||||
.jekyll-metadata
|
||||
.DS_Store
|
||||
Gemfile.lock
|
||||
.idea
|
||||
.jekyll-cache
|
||||
|
||||
@@ -8,22 +8,22 @@ source "https://rubygems.org"
|
||||
#
|
||||
# This will help ensure the proper Jekyll version is running.
|
||||
# Happy Jekylling!
|
||||
gem "jekyll", "~> 4.2.0"
|
||||
# gem "jekyll", "~> 3.9.0"
|
||||
|
||||
# This is the default theme for new Jekyll sites. You may change this to anything you like.
|
||||
gem "just-the-docs", "~> 0.3.3"
|
||||
gem "jekyll-remote-theme", "~> 0.4"
|
||||
gem "jekyll-redirect-from", "~> 0.16"
|
||||
|
||||
# If you want to use GitHub Pages, remove the "gem "jekyll"" above and
|
||||
# uncomment the line below. To upgrade, run `bundle update github-pages`.
|
||||
|
||||
# gem 'github-pages', group: :jekyll_plugins
|
||||
gem 'github-pages', group: :jekyll_plugins
|
||||
|
||||
# If you have any plugins, put them here!
|
||||
group :jekyll_plugins do
|
||||
gem "jekyll-sitemap"
|
||||
end
|
||||
# group :jekyll_plugins do
|
||||
# # gem "jekyll-feed", "~> 0.6"
|
||||
# gem "jekyll-remote-theme"
|
||||
# gem "jekyll-redirect-from"
|
||||
# end
|
||||
|
||||
# Windows does not include zoneinfo files, so bundle the tzinfo-data gem
|
||||
gem "tzinfo-data", platforms: [:mingw, :mswin, :x64_mingw, :jruby]
|
||||
|
||||
@@ -1 +1 @@
|
||||
Copyright OpenSearch contributors.
|
||||
Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
|
||||
|
||||
@@ -1,8 +1,6 @@
|
||||
<img src="https://opensearch.org/assets/img/opensearch-logo-themed.svg" height="64px">
|
||||
|
||||
# OpenSearch documentation
|
||||
|
||||
This repository contains the documentation for OpenSearch, the search, analytics, and visualization suite with advanced security, alerting, SQL support, automated index management, deep performance analysis, and more. You can find the rendered documentation at [opensearch.org/docs](https://opensearch.org/docs).
|
||||
This repository contains the documentation for OpenSearch, the search, analytics, and visualization suite with advanced security, alerting, SQL support, automated index management, deep performance analysis, and more. You can find the rendered documentation at [docs-beta.opensearch.org](https://docs-beta.opensearch.org).
|
||||
|
||||
Community contributions remain essential in keeping this documentation comprehensive, useful, well-organized, and up-to-date.
|
||||
|
||||
@@ -13,9 +11,9 @@ Community contributions remain essential in keeping this documentation comprehen
|
||||
|
||||
Often, engineering teams can keep existing documentation up-to-date with minimal effort, thus freeing up the documentation team to focus on larger projects.
|
||||
|
||||
- Do you have expertise in a particular area of OpenSearch? Cluster sizing? The query DSL? Painless scripting? Aggregations? JVM settings? Take a look at the [current content](https://opensearch.org/docs/opensearch/) and see where you can add value. The [documentation team](#points-of-contact) is happy to help you polish and organize your drafts.
|
||||
- Do you have expertise in a particular area of OpenSearch? Cluster sizing? The query DSL? Painless scripting? Aggregations? JVM settings? Take a look at the [current content](https://docs-beta.opensearch.org/docs/opensearch/) and see where you can add value. The [documentation team](#points-of-contact) is happy to help you polish and organize your drafts.
|
||||
|
||||
- Are you an OpenSearch Dashboards expert? How did you set up your visualizations? Why is a particular dashboard so valuable to your organization? We have [very little](https://opensearch.org/docs/opensearch-dashboards/) on how to use OpenSearch Dashboards, only how to install it.
|
||||
- Are you an OpenSearch Dashboards expert? How did you set up your visualizations? Why is a particular dashboard so valuable to your organization? We have [very little](https://docs-beta.opensearch.org/docs/opensearch-dashboards/) on how to use OpenSearch Dashboards, only how to install it.
|
||||
|
||||
- Are you a web developer? Do you want to add an optional dark mode to the documentation? A "copy to clipboard" button for our code samples? Other improvements to the design or usability? See [major changes](#major-changes) for information on building the website locally.
|
||||
|
||||
@@ -32,9 +30,11 @@ If you encounter problems or have questions when contributing to the documentati
|
||||
- [snyder114](https://github.com/snyder114)
|
||||
|
||||
|
||||
## How the website works
|
||||
## How we build the website
|
||||
|
||||
This repository contains many [Markdown](https://guides.github.com/features/mastering-markdown/) files organized into Jekyll "collections" (e.g. `_search-plugins`, `_opensearch`, etc.). Each Markdown file correlates with one page on the website.
|
||||
After each commit to this repository, GitHub Pages automatically uses [Jekyll](https://jekyllrb.com) to rebuild the [website](https://docs-beta.opensearch.org). The whole process takes around 30 seconds.
|
||||
|
||||
This repository contains many [Markdown](https://guides.github.com/features/mastering-markdown/) files in the `/docs` directory. Each Markdown file correlates with one page on the website. For example, the Markdown file for [this page](https://docs-beta.opensearch.org/docs/opensearch/) is [here](https://github.com/opensearch-project/documentation-website/blob/master/docs/opensearch/index.md).
|
||||
|
||||
Using plain text on GitHub has many advantages:
|
||||
|
||||
@@ -133,15 +133,15 @@ If you're making major changes to the documentation and need to see the rendered
|
||||
sh build.sh
|
||||
```
|
||||
|
||||
1. If the build script doesn't automatically open your web browser (it should), open [http://localhost:4000/docs/](http://localhost:4000/docs/).
|
||||
1. If the build script doesn't automatically open your web browser (it should), open [http://localhost:4000/](http://localhost:4000/).
|
||||
|
||||
1. Create a new branch.
|
||||
|
||||
1. Edit the Markdown files in each collection (e.g. `_security-plugin/`).
|
||||
1. Edit the Markdown files in `/docs`.
|
||||
|
||||
If you're a web developer, you can customize `_layouts/default.html` and `_sass/custom/custom.scss`.
|
||||
|
||||
1. When you save a file, marvel as Jekyll automatically rebuilds the site and refreshes your web browser. This process can take anywhere from 10-30 seconds.
|
||||
1. When you save a file, marvel as Jekyll automatically rebuilds the site and refreshes your web browser. This process takes roughly 30 seconds.
|
||||
|
||||
1. When you're happy with how everything looks, commit, push your changes to your fork, and submit a pull request.
|
||||
|
||||
@@ -196,7 +196,7 @@ 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` and `opensearch_major_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`.
|
||||
|
||||
@@ -225,7 +225,7 @@ This documentation uses a modified version of the [just-the-docs](https://github
|
||||
|
||||
## Get started
|
||||
New
|
||||
{: .label .label-green }
|
||||
{: .label .label-green :}
|
||||
```
|
||||
|
||||
* Labels come in default (blue), green, purple, yellow, and red.
|
||||
@@ -238,27 +238,6 @@ These classes can help with readability, but should be used *sparingly*. Each ad
|
||||
Besides, standard Markdown elements suffice for most documentation.
|
||||
|
||||
|
||||
## Labels for APIs
|
||||
|
||||
Each API operation has a label indicating when it was introduced. For most operations, this label is 1.0:
|
||||
|
||||
```
|
||||
## Get roles
|
||||
Introduced 1.0
|
||||
{: .label .label-purple }
|
||||
```
|
||||
|
||||
If we introduce a breaking change to an operation, add an additional label with a link to the release note for that breaking change:
|
||||
|
||||
```
|
||||
## Get roles
|
||||
Introduced 1.0
|
||||
{: .label .label-purple }
|
||||
[Last breaking change 2.0](https://example.com)
|
||||
{: .label .label-red }
|
||||
```
|
||||
|
||||
|
||||
## Math
|
||||
|
||||
If you want to use the sorts of pretty formulas that [MathJax](https://www.mathjax.org) allows, add `has_math: true` to the Jekyll page metadata. Then insert LaTeX math into HTML tags with the rest of your Markdown content:
|
||||
@@ -294,4 +273,4 @@ This project is licensed under the Apache-2.0 License.
|
||||
|
||||
## Copyright
|
||||
|
||||
Copyright OpenSearch contributors.
|
||||
Copyright Amazon.com, Inc. or its affiliates. All rights reserved.
|
||||
|
||||
@@ -1,87 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Agents and ingestion tools
|
||||
nav_order: 100
|
||||
has_children: false
|
||||
has_toc: false
|
||||
redirect_from:
|
||||
- /clients/agents-and-ingestion-tools/
|
||||
---
|
||||
|
||||
# Agents and ingestion tools
|
||||
|
||||
Historically, many multiple popular agents and ingestion tools have worked with Elasticsearch OSS, such as Beats, Logstash, Fluentd, FluentBit, and OpenTelemetry. OpenSearch aims to continue to support a broad set of agents and ingestion tools, but not all have been tested or have explicitly added OpenSearch compatibility.
|
||||
|
||||
As an intermediate compatibility solution, OpenSearch has a setting that instructs the cluster to return version 7.10.2 rather than its actual version.
|
||||
|
||||
If you use clients that include a version check, such as recent versions of Logstash OSS or Filebeat OSS, enable the setting:
|
||||
|
||||
```json
|
||||
PUT _cluster/settings
|
||||
{
|
||||
"persistent": {
|
||||
"compatibility": {
|
||||
"override_main_response_version": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
[Just like any other setting]({{site.url}}{{site.baseurl}}/opensearch/configuration/), the alternative is to add the following line to `opensearch.yml` on each node and then restart the node:
|
||||
|
||||
```yml
|
||||
compatibility.override_main_response_version: true
|
||||
```
|
||||
|
||||
|
||||
## Downloads
|
||||
|
||||
You can download the OpenSearch output plugin for Logstash from [OpenSearch downloads](https://opensearch.org/downloads.html). The Logstash output plugin is compatible with OpenSearch and Elasticsearch OSS (7.10.2 or lower).
|
||||
|
||||
These are the latest versions of Beats OSS with OpenSearch compatibility. For more information, see the [compatibility matrices](#compatibility-matrices).
|
||||
|
||||
- [Filebeat OSS 7.12.1](https://www.elastic.co/downloads/past-releases/filebeat-oss-7-12-1)
|
||||
- [Metricbeat OSS 7.12.1](https://www.elastic.co/downloads/past-releases/metricbeat-oss-7-12-1)
|
||||
- [Packetbeat OSS 7.12.1](https://www.elastic.co/downloads/past-releases/packetbeat-oss-7-12-1)
|
||||
- [Heartbeat OSS 7.12.1](https://elastic.co/downloads/past-releases/heartbeat-oss-7-12-1)
|
||||
- [Winlogbeat OSS 7.12.1](https://www.elastic.co/downloads/past-releases/winlogbeat-oss-7-12-1)
|
||||
- [Auditbeat OSS 7.12.1](https://elastic.co/downloads/past-releases/auditbeat-oss-7-12-1)
|
||||
|
||||
Some users report compatibility issues with ingest pipelines on these versions of Beats. If you use ingest pipelines with OpenSearch, consider using the 7.10.2 versions of Beats instead.
|
||||
{: .note }
|
||||
|
||||
|
||||
## Compatibility Matrices
|
||||
|
||||
*Italicized* cells are untested, but indicate what a value theoretically should be based on existing information.
|
||||
|
||||
|
||||
### Compatibility Matrix for Logstash
|
||||
|
||||
| | Logstash OSS 7.x to 7.11.x | Logstash OSS 7.12.x\* | Logstash 7.13.x without OpenSearch output plugin | Logstash 7.13.x with OpenSearch output plugin |
|
||||
| :---| :--- | :--- | :--- | :--- |
|
||||
| Elasticsearch OSS 7.x to 7.9.x | *Yes* | *Yes* | *No* | *Yes* |
|
||||
| Elasticsearch OSS 7.10.2 | *Yes* | *Yes* | *No* | *Yes* |
|
||||
| ODFE 1.x to 1.12 | *Yes* | *Yes* | *No* | *Yes* |
|
||||
| ODFE 1.13 | *Yes* | *Yes* | *No* | *Yes* |
|
||||
| OpenSearch 1.0 | Yes via version setting | Yes via version setting | *No* | *Yes* |
|
||||
|
||||
\* Most current compatible version with Elasticsearch OSS.
|
||||
|
||||
|
||||
### Compatibility Matrix for Beats
|
||||
|
||||
| | Beats OSS 7.x to 7.11.x\*\* | Beats OSS 7.12.x\* | Beats 7.13.x |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| Elasticsearch OSS 7.x to 7.9.x | *Yes* | *Yes* | No |
|
||||
| Elasticsearch OSS 7.10.2 | *Yes* | *Yes* | No |
|
||||
| ODFE 1.x to 1.12 | *Yes* | *Yes* | No |
|
||||
| ODFE 1.13 | *Yes* | *Yes* | No |
|
||||
| OpenSearch 1.0 | Yes via version setting | Yes via version setting | No |
|
||||
| Logstash OSS 7.x to 7.11.x | *Yes* | *Yes* | *Yes* |
|
||||
| Logstash OSS 7.12.x\* | *Yes* | *Yes* | *Yes* |
|
||||
| Logstash 7.13.x with OpenSearch output plugin | *Yes* | *Yes* | *Yes* |
|
||||
|
||||
\* Most current compatible version with Elasticsearch OSS.
|
||||
|
||||
\*\* Beats OSS includes all Apache 2.0 Beats agents (i.e. Filebeat, Metricbeat, Auditbeat, Heartbeat, Winlogbeat, Packetbeat).
|
||||
-145
@@ -1,145 +0,0 @@
|
||||
---
|
||||
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)
|
||||
}
|
||||
```
|
||||
@@ -1,96 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Compatibility
|
||||
nav_order: 1
|
||||
has_children: false
|
||||
redirect_from:
|
||||
- /clients/
|
||||
---
|
||||
|
||||
# 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
|
||||
:--- | :---
|
||||
[Java low-level REST client](https://search.maven.org/artifact/org.elasticsearch.client/elasticsearch-rest-client/7.13.4/jar) | 7.13.4
|
||||
[Java high-level REST client](https://search.maven.org/artifact/org.elasticsearch.client/elasticsearch-rest-high-level-client/7.13.4/jar) | 7.13.4
|
||||
[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
|
||||
|
||||
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 %}
|
||||
## Python 3 test code
|
||||
|
||||
This code indexes a single document and is equivalent to `PUT /python-test-index1/_doc/1`.
|
||||
|
||||
```python
|
||||
from elasticsearch import Elasticsearch
|
||||
|
||||
host = 'localhost'
|
||||
port = 9200
|
||||
# For testing only. Do not store credentials in code.
|
||||
auth = ('admin', 'admin')
|
||||
|
||||
es = Elasticsearch(
|
||||
hosts = [{'host': host, 'port': port}],
|
||||
http_auth = auth,
|
||||
use_ssl = True,
|
||||
verify_certs = False
|
||||
)
|
||||
|
||||
document = {
|
||||
"title": "Moneyball",
|
||||
"director": "Bennett Miller",
|
||||
"year": "2011"
|
||||
}
|
||||
|
||||
response = es.index(index='python-test-index1', id='1', body=document, refresh=True)
|
||||
|
||||
print(response)
|
||||
```
|
||||
|
||||
|
||||
## Node.js test code
|
||||
|
||||
This code is equivalent to `GET /`.
|
||||
|
||||
```js
|
||||
const { Client } = require('@elastic/elasticsearch')
|
||||
const client = new Client({
|
||||
node: 'https://localhost:9200',
|
||||
auth: {
|
||||
// For testing only. Don't store credentials in code.
|
||||
username: 'admin',
|
||||
password: 'admin'
|
||||
},
|
||||
ssl: {
|
||||
// ca: fs.readFileSync('./cacert.pem'),
|
||||
rejectUnauthorized: false
|
||||
}
|
||||
})
|
||||
|
||||
async function run () {
|
||||
const { body } = await client.info();
|
||||
console.log(body);
|
||||
}
|
||||
|
||||
run().catch(console.log)
|
||||
```
|
||||
{% endcomment %}
|
||||
@@ -1,124 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Elasticsearch OSS Java high-level REST client
|
||||
nav_order: 60
|
||||
---
|
||||
|
||||
# Elasticsearch OSS 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.
|
||||
|
||||
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.
|
||||
|
||||
## 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:
|
||||
|
||||
```
|
||||
<dependency>
|
||||
<groupId>org.elasticsearch.client</groupId>
|
||||
<artifactId>elasticsearch-rest-high-level-client</artifactId>
|
||||
<version>7.10.2</version>
|
||||
</dependency>
|
||||
```
|
||||
|
||||
You can now start your OpenSearch cluster. The 7.10.2 Elasticsearch OSS high-level REST client works with the 1.x versions of OpenSearch.
|
||||
|
||||
## Sample code
|
||||
|
||||
```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.elasticsearch.action.admin.indices.delete.DeleteIndexRequest;
|
||||
import org.elasticsearch.action.delete.DeleteRequest;
|
||||
import org.elasticsearch.action.delete.DeleteResponse;
|
||||
import org.elasticsearch.action.get.GetRequest;
|
||||
import org.elasticsearch.action.get.GetResponse;
|
||||
import org.elasticsearch.action.index.IndexRequest;
|
||||
import org.elasticsearch.action.index.IndexResponse;
|
||||
import org.elasticsearch.action.support.master.AcknowledgedResponse;
|
||||
import org.elasticsearch.client.RequestOptions;
|
||||
import org.elasticsearch.client.RestClient;
|
||||
import org.elasticsearch.client.RestClientBuilder;
|
||||
import org.elasticsearch.client.RestHighLevelClient;
|
||||
import org.elasticsearch.client.indices.CreateIndexRequest;
|
||||
import org.elasticsearch.client.indices.CreateIndexResponse;
|
||||
import org.elasticsearch.common.settings.Settings;
|
||||
import org.elasticsearch.common.xcontent.XContentType;
|
||||
|
||||
import java.io.IOException;
|
||||
import java.util.HashMap;
|
||||
|
||||
public class RESTClientSample {
|
||||
|
||||
public static void main(String[] args) throws IOException {
|
||||
|
||||
//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);
|
||||
|
||||
//Establish credentials to use basic authentication.
|
||||
//Only for demo purposes. Do not specify your credentials in code.
|
||||
final CredentialsProvider credentialsProvider = new BasicCredentialsProvider();
|
||||
|
||||
credentialsProvider.setCredentials(AuthScope.ANY,
|
||||
new UsernamePasswordCredentials("admin", "admin"));
|
||||
|
||||
//Create a client.
|
||||
RestClientBuilder builder = RestClient.builder(new HttpHost("localhost", 9200, "https"))
|
||||
.setHttpClientConfigCallback(new RestClientBuilder.HttpClientConfigCallback() {
|
||||
@Override
|
||||
public HttpAsyncClientBuilder customizeHttpClient(HttpAsyncClientBuilder httpClientBuilder) {
|
||||
return httpClientBuilder.setDefaultCredentialsProvider(credentialsProvider);
|
||||
}
|
||||
});
|
||||
RestHighLevelClient client = new RestHighLevelClient(builder);
|
||||
|
||||
//Create a non-default index with custom settings and mappings.
|
||||
CreateIndexRequest createIndexRequest = new CreateIndexRequest("custom-index");
|
||||
|
||||
createIndexRequest.settings(Settings.builder() //Specify in the settings how many shards you want in the index.
|
||||
.put("index.number_of_shards", 4)
|
||||
.put("index.number_of_replicas", 3)
|
||||
);
|
||||
//Create a set of maps for the index's mappings.
|
||||
HashMap<String, String> typeMapping = new HashMap<String,String>();
|
||||
typeMapping.put("type", "integer");
|
||||
HashMap<String, Object> ageMapping = new HashMap<String, Object>();
|
||||
ageMapping.put("age", typeMapping);
|
||||
HashMap<String, Object> mapping = new HashMap<String, Object>();
|
||||
mapping.put("properties", ageMapping);
|
||||
createIndexRequest.mapping(mapping);
|
||||
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.
|
||||
request.id("1"); //Assign an ID to the document.
|
||||
|
||||
HashMap<String, String> stringMapping = new HashMap<String, String>();
|
||||
stringMapping.put("message:", "Testing Java REST client");
|
||||
request.source(stringMapping); //Place your content into the index's source.
|
||||
IndexResponse indexResponse = client.index(request, RequestOptions.DEFAULT);
|
||||
|
||||
//Getting back the document
|
||||
GetRequest getRequest = new GetRequest("custom-index", "1");
|
||||
GetResponse response = client.get(getRequest, RequestOptions.DEFAULT);
|
||||
|
||||
System.out.println(response.getSourceAsString());
|
||||
|
||||
//Delete the document
|
||||
DeleteRequest deleteDocumentRequest = new DeleteRequest("custom-index", "1"); //Index name followed by the ID.
|
||||
DeleteResponse deleteResponse = client.delete(deleteDocumentRequest, RequestOptions.DEFAULT);
|
||||
|
||||
//Delete the index
|
||||
DeleteIndexRequest deleteIndexRequest = new DeleteIndexRequest("custom-index"); //Index name.
|
||||
AcknowledgedResponse deleteIndexResponse = client.indices().delete(deleteIndexRequest, RequestOptions.DEFAULT);
|
||||
|
||||
client.close();
|
||||
}
|
||||
}
|
||||
```
|
||||
@@ -1,141 +0,0 @@
|
||||
---
|
||||
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);
|
||||
```
|
||||
@@ -1,246 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Advanced configurations
|
||||
parent: Logstash
|
||||
nav_order: 230
|
||||
---
|
||||
|
||||
# Advanced configurations
|
||||
|
||||
This section describes how to set up advanced configuration options, like referencing field values and conditional statements, for Logstash.
|
||||
|
||||
## Referencing field values
|
||||
|
||||
To get access to a field, use the `- field` syntax.
|
||||
You can also surround the field name by square brackets `- [field]` which makes it more explicit that you're referring to a field.
|
||||
|
||||
|
||||
For example, if you have the following event:
|
||||
|
||||
```bash
|
||||
{
|
||||
"request": "/products/view/123",
|
||||
"verb": "GET",
|
||||
"response": 200,
|
||||
"headers": {
|
||||
"request_path" => "/"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
To access the `request` field, use `- request` or `- [request]`.
|
||||
|
||||
If you want to reference nested fields, use the square brackets syntax and specify the path to the field. With each level being enclosed within square brackets: `- [headers][request_path]`.
|
||||
|
||||
You can reference fields using the `sprintf` format. This is also called string expansion. You need to add a % sign and then wrap the field reference within curly brackets.
|
||||
|
||||
You need to reference field values when using conditional statements.
|
||||
|
||||
For example, you can make the file name dynamic and contain the type of the processed events - either `access` or `error`. The `type` option is mainly used for conditionally applying filter plugins based on the type of events being processed.
|
||||
|
||||
Let's add a `type` option and specify a value of `access`.
|
||||
|
||||
|
||||
```yml
|
||||
input {
|
||||
file {
|
||||
path => ""
|
||||
start_position => "beginning"
|
||||
type => "access"
|
||||
}
|
||||
http {
|
||||
type => "access"
|
||||
}
|
||||
}
|
||||
|
||||
filter {
|
||||
mutate {
|
||||
remove_field => {"host"}
|
||||
}
|
||||
}
|
||||
|
||||
output {
|
||||
stdout {
|
||||
codec => rubydebug
|
||||
}
|
||||
file {
|
||||
path => "%{[type]}.log"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Start Logstash and send an HTTP request. The processed event is output in the terminal. The event now includes a field named `type`.
|
||||
|
||||
You'll see the `access.log` file created within the Logstash directory.
|
||||
|
||||
## Conditional statements
|
||||
|
||||
You can use conditional statements to control the flow of code execution based on some conditions.
|
||||
|
||||
Syntax:
|
||||
|
||||
```yml
|
||||
if EXPR {
|
||||
...
|
||||
} else if EXPR {
|
||||
...
|
||||
} else {
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
`EXPR` is any valid Logstash syntax that evaluates to a boolean value.
|
||||
For example, you can check if an event type is set to `access` or `error` and perform some action based on that:
|
||||
|
||||
```yml
|
||||
if [type] == "access" {
|
||||
...
|
||||
} else if [type] == "error" {
|
||||
file { .. }
|
||||
} else {
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
You can compare a field value to some arbitrary value:
|
||||
|
||||
```yml
|
||||
if [headers][content_length] >= 1000 {
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
You can regex:
|
||||
|
||||
```yml
|
||||
if [some_field =~ /[0-9]+/ {
|
||||
//some field only contains digits
|
||||
}
|
||||
```
|
||||
|
||||
You can use arrays:
|
||||
|
||||
```yml
|
||||
if [some_field] in ["one", "two", "three"] {
|
||||
some field is either "one", "two", or "three"
|
||||
}
|
||||
```
|
||||
|
||||
You can use boolean operators:
|
||||
|
||||
```yml
|
||||
if [type] == "access" or [type] == "error" {
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
## Formatting dates
|
||||
|
||||
You can use the `sprintf` format or string expansion to format dates.
|
||||
For example, you might want the current date to be part of the filename.
|
||||
|
||||
To format the date, add a plus sign in curly brackets followed by the date format - `%{+yyyy-MM-dd}`.
|
||||
|
||||
```yml
|
||||
file {
|
||||
path => "%{[type]}_%{+yyyy_MM_dd}.log"
|
||||
}
|
||||
```
|
||||
|
||||
This is the date stored within the @timestamp fields, which is the time and date of the event.
|
||||
Send a request to the pipeline and verify that a filename is outputted that contains the events date.
|
||||
|
||||
You can embed the date in other outputs as well, for example into the index name in OpenSearch.
|
||||
|
||||
## Sending time information
|
||||
|
||||
You can set the time of events.
|
||||
|
||||
Logstash already sets the time when the event is received by the input plugin within the @timestamp field.
|
||||
In some scenarios, you might need to use a different timestamp.
|
||||
For example, if you have an eCommerce store and you process the orders daily at midnight. When Logstash receives the events at midnight, it sets the timestamp to the current time.
|
||||
But you want it to be the time when the order is placed and not when Logstash received the event.
|
||||
|
||||
Let's change the event timestamp to the date the request is received by the web server. You can do this using a filter plugin named `dates`.
|
||||
The `dates` filter passes a `date` or `datetime` value from a field and uses the results as the event timestamp.
|
||||
|
||||
Add the `date` plugin at the bottom of the `filter` block:
|
||||
|
||||
```yml
|
||||
date {
|
||||
match => [ "timestamp", "dd/MMM/yyyy:HH:mm:ss Z" ]
|
||||
}
|
||||
```
|
||||
|
||||
timestamp is the field that the `grok` pattern creates.
|
||||
`Z` is the timezone. i.e., UTC offsets.
|
||||
|
||||
Start Logstash and send an HTTP request.
|
||||
|
||||
You can see that the filename contains the date of the request instead of the present date.
|
||||
|
||||
If the passing of the date fails, the `filter` plugin adds a tag named `_datepassfailure` to the text field.
|
||||
|
||||
After you have set the @timestamp field to a new value, you don't really need the other `timestamp` field anymore. You can remove it with the `remove_field` option.
|
||||
|
||||
```yml
|
||||
date {
|
||||
match => [ "timestamp", "dd/MMM/yyyy:HH:mm:ss Z" ]
|
||||
remove_field => [ "timestamp" ]
|
||||
}
|
||||
```
|
||||
|
||||
## Parsing user agents
|
||||
|
||||
The user agent is the last part of a log entry that consists of the name of the browser, the browser version, and the OS of the device.
|
||||
|
||||
Users might be using a wide range of browsers, devices, and OS's. Doing this manually is hard.
|
||||
|
||||
You can't use `grok` patterns because the `grok` pattern only matches the usage in the string as whole and doesn't figure out which browser the visitor used for instance.
|
||||
|
||||
Logstash ships with a file containing regular expressions for this purpose. This makes it really easy to extract user agent information, which you could send to OpenSearch and run aggregations on.
|
||||
|
||||
To do this, add a `source` option that contains the name of the field. In this case, that's the `agent` field.
|
||||
By default the user agent plugin, adds a number of fields at the top-level of the event.
|
||||
Since that can get pretty confusing, we can add an option named `target` with a value of `ua`, short for user agent. What this does is that it nests the fields within an object named `ua`, making things more organized.
|
||||
|
||||
```yml
|
||||
useragent {
|
||||
source => "agent"
|
||||
target => "ua"
|
||||
}
|
||||
```
|
||||
|
||||
Start Logstah and send an HTTP request.
|
||||
|
||||
You can see a field named `ua` with a number of keys including the browser name and version, the OS, and the device.
|
||||
|
||||
You could OpenSearch Dashboards to create a pie chart that shows how many visitors are from mobile devices and how many are desktop users. Or, you could get statistics on which browser versions are popular.
|
||||
|
||||
## Enriching geographical data
|
||||
|
||||
You can take an IP address and perform geographical lookup to resolve the geographical location of the user using the `geoip` filter.
|
||||
|
||||
The `geoip` filter plugin ships with a database called `geolite 2`, which is provided by a company named MaxMind. `geolite 2` is a popular source of geographical data and it's available for free.
|
||||
Add the `geoip` plugin at the bottom of the `else` block.
|
||||
|
||||
The value of the `source` option is the name of the field containing the IP address, in this case that's `clientip`. You can make this field available using the `grok` pattern.
|
||||
|
||||
```yml
|
||||
geoip {
|
||||
source => "clientip"
|
||||
}
|
||||
```
|
||||
|
||||
Start Logstash and send an HTTP request.
|
||||
|
||||
Within the terminal, you see a new field named `geoip` that contains information such as the timezone, country, continent, city, postal code, and the latitude / longitude pair.
|
||||
|
||||
If you only need the country name for instance, include an option named `fields` with an array of the field names that you want the `geoip` plugin to return.
|
||||
|
||||
Some of the fields are not always available such as city name and region because translating IP addresses into geographical locations is generally not that accurate. If the `geoip` plugin fails to look up the geographical location, it adds a tag named `geoip_lookup_failure`.
|
||||
|
||||
You can use the `geoip` plugin with the OpenSearch output because `location` object within the `geoip` object, is a standard format for representing geospatial data in JSON. This is the same format as OpenSearch uses for its `geo_point` data type.
|
||||
|
||||
You can use the powerful geospatial queries of OpenSearch for working with geographical data.
|
||||
@@ -1,157 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Common filter plugins
|
||||
parent: Logstash
|
||||
nav_order: 220
|
||||
---
|
||||
|
||||
# Common filter plugins
|
||||
|
||||
This page contains a list of common filter plugins.
|
||||
|
||||
## mutate
|
||||
|
||||
You can use the `mutate` filter to change the data type of a field. For example, you can use the `mutate` filter if you're sending events to OpenSearch and you need to change the data type of a field to match any existing mappings.
|
||||
|
||||
To convert the `quantity` field from a `string` type to an `integer` type:
|
||||
|
||||
```yml
|
||||
input {
|
||||
http {
|
||||
host => "127.0.0.1"
|
||||
port => 8080
|
||||
}
|
||||
}
|
||||
|
||||
filter {
|
||||
mutate {
|
||||
convert => {"quantity" => "integer"}
|
||||
}
|
||||
}
|
||||
|
||||
output {
|
||||
file {
|
||||
path => "output.txt"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Sample output
|
||||
|
||||
You can see that the type of the `quantity` field is changed from a `string` to an `integer`.
|
||||
|
||||
```yml
|
||||
{
|
||||
"quantity" => 3,
|
||||
"host" => "127.0.0.1",
|
||||
"@timestamp" => 2021-05-23T19:02:08.026Z,
|
||||
"amount" => 10,
|
||||
"@version" => "1",
|
||||
"headers" => {
|
||||
"request_path" => "/",
|
||||
"connection" => "keep-alive",
|
||||
"content_length" => "41",
|
||||
"http_user_agent" => "PostmanRuntime/7.26.8",
|
||||
"request_method" => "PUT",
|
||||
"cache_control" => "no-cache",
|
||||
"http_accept" => "*/*",
|
||||
"content_type" => "application/json",
|
||||
"http_version" => "HTTP/1.1",
|
||||
"http_host" => "127.0.0.1:8080",
|
||||
"accept_encoding" => "gzip, deflate, br",
|
||||
"postman_token" => "ffd1cdcb-7a1d-4d63-90f8-0f2773069205"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Other data types you can convert to are `float`, `string`, and `boolean` values. If you pass in an array, the `mutate` filter converts all the elements in the array. If you pass a `string` like "world" to cast to an `integer` type, the result is 0 and Logstash continues processing events.
|
||||
|
||||
Logstash supports a few common options for all filter plugins:
|
||||
|
||||
Option | Description
|
||||
:--- | :---
|
||||
`add_field` | Adds one or more fields to the event.
|
||||
`remove_field` | Removes one or more events from the field.
|
||||
`add_tag` | Adds one or more tags to the event. You can use tags to perform conditional processing on events depending on which tags they contain.
|
||||
`remove_tag` | Removes one or more tags from the event.
|
||||
|
||||
For example, you can remove the `host` field from the event:
|
||||
|
||||
```yml
|
||||
input {
|
||||
http {
|
||||
host => "127.0.0.1"
|
||||
port => 8080
|
||||
}
|
||||
}
|
||||
|
||||
filter {
|
||||
mutate {
|
||||
remove_field => {"host"}
|
||||
}
|
||||
}
|
||||
|
||||
output {
|
||||
file {
|
||||
path => "output.txt"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## grok
|
||||
|
||||
With the `grok` filter, you can parse unstructured data and and structure it into fields. The `grok` filter uses text patterns to match text in your logs. You can think of text patterns as variables containing regular expressions.
|
||||
|
||||
The format of a text pattern is as follows:
|
||||
|
||||
```bash
|
||||
%{SYNTAX:SEMANTIC}
|
||||
```
|
||||
|
||||
`SYNTAX` is the format a piece of text should be in for the pattern to match. You can enter any of `grok`'s predefined patterns. For example, you can use the email identifier to match an email address from a given piece of text.
|
||||
|
||||
`SEMANTIC` is an arbitrary name for the matched text. For example, if you're using the email identifier syntax, you can name it “email.”
|
||||
|
||||
The following request consists of the IP address of the visitor, name of the visitor, the timestamp of the request, the HTTP verb and URL, the HTTP status code, and the number of bytes:
|
||||
|
||||
```bash
|
||||
184.252.108.229 - joe [20/Sep/2017:13:22:22 +0200] GET /products/view/123 200 12798
|
||||
```
|
||||
|
||||
To split this request into different fields:
|
||||
|
||||
```yml
|
||||
filter {
|
||||
grok {
|
||||
match => { "message" => " %{IP: ip_address} %{USER:identity}
|
||||
%{USER:auth} \[%{HTTPDATE:reg_ts}\]
|
||||
\"%{WORD:http_verb}
|
||||
%{URIPATHPARAM: req_path}
|
||||
\" %{INT:http_status:int}
|
||||
%{INT:num_bytes:int}"}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
where:
|
||||
|
||||
- `IP`: matches the IP address field.
|
||||
- `USER`: matches the user name.
|
||||
- `WORD`: matches the HTTP verb.
|
||||
- `URIPATHPARAM`: matches the URI path.
|
||||
- `INT`: matches the HTTP status field.
|
||||
- `INT`: matches the number of bytes.
|
||||
|
||||
This is what the event looks like after the `grok` filter breaks it down into individual fields:
|
||||
|
||||
```yml
|
||||
ip_address: 184.252.108.229
|
||||
identity: joe
|
||||
reg_ts: 20/Sep/2017:13:22:22 +0200
|
||||
http_verb:GET
|
||||
req_path: /products/view/123
|
||||
http_status: 200
|
||||
num_bytes: 12798
|
||||
```
|
||||
|
||||
For common log formats, you use the predefined patterns defined here---[Logstash patterns](https://github.com/logstash-plugins/logstash-patterns-core/blob/master/patterns/ecs-v1). You can make any adjustments to the results with the `mutate` filter.
|
||||
@@ -1,40 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Logstash execution model
|
||||
parent: Logstash
|
||||
nav_order: 210
|
||||
---
|
||||
|
||||
# Logstash execution model
|
||||
|
||||
Here's a brief introduction to how Logstash processes events internally.
|
||||
|
||||
## Handling events concurrently
|
||||
|
||||
You can configure Logstash to have a number of inputs listening for events. Each input runs in its own thread to avoid inputs blocking each other. If you have two incoming events at the same time, Logstash handles both events concurrently.
|
||||
|
||||
After receiving an event and possibly applying an input codec, Logstash sends the event to a work queue. Pipeline workers or batchers perform the rest of the work involving filters and outputs along with any codec used at the output. Each pipeline worker also runs within its own thread meaning that Logstash processes multiple events simultaneously.
|
||||
|
||||
## Processing events in batches
|
||||
|
||||
A pipeline worker consumes events from the work queue in batches to optimize the throughput of the pipeline as a whole.
|
||||
|
||||
One reason why Logstash works in batches is that some code needs to be executed regardless of how many events are processed at a time within the pipeline worker. Instead of executing that code 100 times for 100 events, it’s more efficient to execute it once for a batch of 100 events.
|
||||
|
||||
Another reason is that a few output plugins group together events as batches. For example, if you send 100 requests to OpenSearch, the OpenSearch output plugin uses the bulk API to send a single request that groups together the 100 requests.
|
||||
|
||||
Logstash determines the batch size by two configuration options---a number representing the maximum batch size and the batch delay. The batch delay is how long Logstash waits before processing the unprocessed batch of events.
|
||||
If you set the maximum batch size to 50 and the batch delay to 100 ms, Logstash processes a batch if they're either 50 unprocessed events in the work queue or if one hundred milliseconds have elapsed.
|
||||
|
||||
The reason that a batch is processed, even if the maximum batch size isn’t reached, is to reduce the delay in processing and to continue to process events in a timely manner. This works well for pipelines that process a low volume of events.
|
||||
|
||||
Imagine that you’ve a pipeline that processes error logs from web servers and pushes them to OpenSearch. You’re using OpenSearch Dashboards to analyze the error logs. Because you’re possibly dealing with a fairly low number of events, it might take a long time to reach 50 events. Logstash processes the events before reaching this threshold because otherwise there would be a long delay before we see the errors appear in OpenSearch Dashboards.
|
||||
|
||||
The default batch size and batch delay work for most cases. You don’t need to change the default values unless you need to minutely optimize the performance.
|
||||
|
||||
## Optimizing based on CPU cores
|
||||
|
||||
The number of pipeline workers are proportional to the number of CPU cores on the nodes.
|
||||
If you have 5 workers running on a server with 2 CPU cores, the 5 workers won't be able to process events concurrently. On the other hand, running 5 workers on a server running 10 CPU cores limits the throughput of a Logstash instance.
|
||||
|
||||
Instead of running a fixed number of workers, which results in poor performance in some cases, Logstash examines the number of CPU cores of the instance and selects the number of pipeline workers to optimize its performance for the platform on which its running. For instance, your local development machine might not have the same processing power as a production server. So you don't need to manually configure Logstash for different machines.
|
||||
@@ -1,358 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Logstash
|
||||
nav_order: 200
|
||||
has_children: true
|
||||
has_toc: true
|
||||
redirect_from:
|
||||
- /clients/logstash/
|
||||
---
|
||||
|
||||
# Logstash
|
||||
|
||||
Logstash is a real-time event processing engine. It's part of the OpenSearch stack which includes OpenSearch, Beats, and OpenSearch Dashboards.
|
||||
|
||||
You can send events to Logstash from many different sources. Logstash processes the events and sends it one or more destinations. For example, you can send access logs from a web server to Logstash. Logstash extracts useful information from each log and sends it to a destination like OpenSearch.
|
||||
|
||||
Sending events to Logstash lets you decouple event processing from your app. Your app only needs to send events to Logstash and doesn’t need to know anything about what happens to the events afterwards.
|
||||
|
||||
The open-source community originally built Logstash for processing log data but now you can process any type of events, including events in XML or JSON format.
|
||||
|
||||
## Structure of a pipeline
|
||||
|
||||
The way that Logstash works is that you configure a pipeline that has three phases---inputs, filters, and outputs.
|
||||
|
||||
Each phase uses one or more plugins. Logstash has over 200 built-in plugins so chances are that you’ll find what you need. Apart from the built-in plugins, you can use plugins from the community or even write your own.
|
||||
|
||||
The structure of a pipeline is as follows:
|
||||
|
||||
```yml
|
||||
input {
|
||||
input_plugin => {}
|
||||
}
|
||||
|
||||
filter {
|
||||
filter_plugin => {}
|
||||
}
|
||||
|
||||
output {
|
||||
output_plugin => {}
|
||||
}
|
||||
```
|
||||
|
||||
where:
|
||||
|
||||
* `input` receives events like logs from multiple sources simultaneously. Logstash supports a number of input plugins for TCP/UDP, files, syslog, Microsoft Windows EventLogs, stdin, HTTP, and so on. You can also use an open source collection of input tools called Beats to gather events. The input plugin sends the events to a filter.
|
||||
* `filter` parses and enriches the events in one way or the other. Logstash has a large collection of filter plugins that modify events and pass them on to an output. For example, a `grok` filter parses unstructured events into fields and a `mutate` filter changes fields. Filters are executed sequentially.
|
||||
* `output` ships the filtered events to one or more destinations. Logstash supports a wide range of output plugins for destinations like OpenSearch, TCP/UDP, emails, files, stdout, HTTP, Nagios, and so on.
|
||||
|
||||
Both the input and output phases support codecs to process events as they enter or exit the pipeline.
|
||||
Some of the popular codecs are `json` and `multiline`. The `json` codec processes data that’s in JSON format and the `multiline` codec merges multiple line events into a single line.
|
||||
|
||||
You can also write conditional statements within pipeline configurations to perform certain actions, if a certain criteria is met.
|
||||
|
||||
## Install Logstash
|
||||
|
||||
The OpenSearch Logstash plugin has two installation options at this time: Linux (ARM64/X64) and Docker (ARM64/X64).
|
||||
|
||||
Make sure you have [Java Development Kit (JDK)](https://www.oracle.com/java/technologies/javase-downloads.html) version 8 or 11 installed.
|
||||
|
||||
### Tarball
|
||||
|
||||
1. Download the Logstash tarball from [OpenSearch downloads](https://opensearch.org/downloads.html).
|
||||
|
||||
2. Navigate to the downloaded folder in the terminal and extract the files:
|
||||
|
||||
```bash
|
||||
tar -zxvf logstash-oss-with-opensearch-output-plugin-7.13.2-linux-x64.tar.gz
|
||||
```
|
||||
|
||||
3. Navigate to the `logstash-7.13.2` directory.
|
||||
- You can add your pipeline configurations to the `config` directory. Logstash saves any data from the plugins in the `data` directory. The `bin` directory contains the binaries for starting Logstash and managing plugins.
|
||||
|
||||
### Docker
|
||||
|
||||
1. Pull the Logstash oss package with the OpenSearch output plugin image:
|
||||
|
||||
```
|
||||
docker pull opensearchproject/logstash-oss-with-opensearch-output-plugin:7.13.2
|
||||
```
|
||||
|
||||
1. Create a Docker network:
|
||||
|
||||
```
|
||||
docker network create test
|
||||
```
|
||||
|
||||
1. Start OpenSearch with this network:
|
||||
|
||||
```
|
||||
docker run -p 9200:9200 -p 9600:9600 --name opensearch --net test -e "discovery.type=single-node" opensearchproject/opensearch:1.0.0
|
||||
```
|
||||
|
||||
1. Start Logstash:
|
||||
|
||||
```
|
||||
docker run -it --rm --name logstash --net test opensearchproject/logstash-oss-with-opensearch-output-plugin:7.13.2 -e 'input { stdin { } } output {
|
||||
opensearch {
|
||||
hosts => ["https://opensearch:9200"]
|
||||
index => "opensearch-logstash-docker-%{+YYYY.MM.dd}"
|
||||
user => "admin"
|
||||
password => "admin"
|
||||
ssl => true
|
||||
ssl_certificate_verification => false
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
## Process text from the terminal
|
||||
|
||||
You can define a pipeline that listens for events on `stdin` and outputs events on `stdout`. `stdin` and `stdout` refer to the terminal in which you’re running Logstash.
|
||||
|
||||
To enter some text in the terminal and see the event data in the output:
|
||||
|
||||
1. Use the `-e` argument to pass a pipeline configuration directly to the Logstash binary. In this case, `stdin` is the input plugin and `stdout` is the output plugin:
|
||||
|
||||
```bash
|
||||
bin/logstash -e "input { stdin { } } output { stdout { } }"
|
||||
```
|
||||
Add the `—debug` flag to see a more detailed output.
|
||||
|
||||
2. Enter "hello world" in your terminal. Logstash processes the text and outputs it back to the terminal:
|
||||
|
||||
```yml
|
||||
{
|
||||
"message" => "hello world",
|
||||
"host" => "a483e711a548.ant.amazon.com",
|
||||
"@timestamp" => 2021-05-30T05:15:56.816Z,
|
||||
"@version" => "1"
|
||||
}
|
||||
```
|
||||
|
||||
The `message` field contains your raw input. The `host` field is an IP address when you don’t run Logstash locally. `@timestamp` shows the date and time for when the event is processed. Logstash uses the `@version` field for internal processing.
|
||||
|
||||
3. Press `Ctrl + C` to shut down Logstash.
|
||||
|
||||
### Troubleshooting
|
||||
|
||||
If you already have a Logstash process running, you’ll get an error. To fix this issue:
|
||||
|
||||
1. Delete the `.lock` file from the `data` directory:
|
||||
|
||||
```bash
|
||||
cd data
|
||||
rm -rf .lock
|
||||
```
|
||||
|
||||
2. Restart Logstash.
|
||||
|
||||
## Process JSON or HTTP input and output it to a file
|
||||
|
||||
To define a pipeline that handles JSON requests:
|
||||
|
||||
1. Open the `config/pipeline.conf` file in any text editor you like. You can create a pipeline configuration file with any extension, the `.conf` extension is a Logstash convention. Add the `json` codec to accept JSON as the input and the `file` plugin to output the processed events to a `.txt` file:
|
||||
|
||||
```yml
|
||||
input {
|
||||
stdin {
|
||||
codec => json
|
||||
}
|
||||
}
|
||||
output {
|
||||
file {
|
||||
path => "output.txt"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
To process inputs from a file, add an input file to the `events-data` directory and then pass its path to the `file` plugin at the input:
|
||||
|
||||
```yml
|
||||
input {
|
||||
file {
|
||||
path => "events-data/input_data.log"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
2. Start Logstash:
|
||||
|
||||
```bash
|
||||
$ bin/logstash -f config/pipeline.conf
|
||||
```
|
||||
|
||||
`config/pipeline.conf` is a relative path to the `pipeline.conf` file. You can use an absolute path as well.
|
||||
|
||||
3. Add a JSON object in the terminal:
|
||||
|
||||
```json
|
||||
{ "amount": 10, "quantity": 2}
|
||||
```
|
||||
|
||||
The pipeline only handles a single line of input. If you paste some JSON that spans multiple lines, you’ll get an error.
|
||||
|
||||
4. Check that the fields from the JSON object are added to the `output.txt` file:
|
||||
|
||||
```json
|
||||
$ cat output.txt
|
||||
|
||||
{
|
||||
"@version": "1",
|
||||
"@timestamp": "2021-05-30T05:52:52.421Z",
|
||||
"host": "a483e711a548.ant.amazon.com",
|
||||
"amount": 10,
|
||||
"quantity": 2
|
||||
}
|
||||
```
|
||||
|
||||
If you type in some invalid JSON as the input, you'll see a JSON parsing error. Logstash doesn't discard the invalid JSON because you still might want to do something with it. For example, you can trigger an email or send a notification to a Slack channel.
|
||||
|
||||
To define a pipeline that handles HTTP requests:
|
||||
|
||||
1. Use the `http` plugin to send events to Logstash through HTTP:
|
||||
|
||||
```yml
|
||||
input {
|
||||
http {
|
||||
host => "127.0.0.1"
|
||||
port => 8080
|
||||
}
|
||||
}
|
||||
|
||||
output {
|
||||
file {
|
||||
path => "output.txt"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
If you don’t specify any options, the `http` plugin binds to `localhost` and listens on port 8080.
|
||||
|
||||
2. Start Logstash:
|
||||
|
||||
```bash
|
||||
$ bin/logstash -f config/pipeline.conf
|
||||
```
|
||||
|
||||
3. Use Postman to send an HTTP request. Set `Content-Type` to an HTTP header with a value of `application/json`:
|
||||
|
||||
```json
|
||||
PUT 127.0.0.1:8080
|
||||
|
||||
{
|
||||
"amount": 10,
|
||||
"quantity": 2
|
||||
}
|
||||
```
|
||||
|
||||
Or, you can use the `curl` command:
|
||||
|
||||
```bash
|
||||
curl -XPUT -H "Content-Type: application/json" -d ' {"amount": 7, "quantity": 3 }' http://localhost:8080 (http://localhost:8080/)
|
||||
```
|
||||
|
||||
Even though we haven't added the `json` plugin to the input, the pipeline configuration still works because the HTTP plugin automatically applies the appropriate codec based on the `Content-Type` header.
|
||||
If you specify a value of `applications/json`, Logstash parses the request body as JSON.
|
||||
|
||||
The `headers` field contains the HTTP headers that Logstash receives:
|
||||
|
||||
```json
|
||||
{
|
||||
"host": "127.0.0.1",
|
||||
"quantity": "3",
|
||||
"amount": 10,
|
||||
"@timestamp": "2021-05-30T06:05:48.135Z",
|
||||
"headers": {
|
||||
"http_version": "HTTP/1.1",
|
||||
"request_method": "PUT",
|
||||
"http_user_agent": "PostmanRuntime/7.26.8",
|
||||
"connection": "keep-alive",
|
||||
"postman_token": "c6cd29cf-1b37-4420-8db3-9faec66b9e7e",
|
||||
"http_host": "127.0.0.1:8080",
|
||||
"cache_control": "no-cache",
|
||||
"request_path": "/",
|
||||
"content_type": "application/json",
|
||||
"http_accept": "*/*",
|
||||
"content_length": "41",
|
||||
"accept_encoding": "gzip, deflate, br"
|
||||
},
|
||||
"@version": "1"
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
## Automatically reload the pipeline configuration
|
||||
|
||||
You can configure Logstash to detect any changes to the pipeline configuration file or the input log file and automatically reload the configuration.
|
||||
|
||||
The `stdin` plugin doesn’t supporting automatic reloading.
|
||||
{: .note }
|
||||
|
||||
1. Add an option named `start_position` with a value of `beginning` to the input plugin:
|
||||
|
||||
```yml
|
||||
input {
|
||||
file {
|
||||
path => "/Users/<user>/Desktop/logstash7-12.1/events-data/input_file.log"
|
||||
start_position => "beginning"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Logstash only processes any new events added to the input file and ignores the ones that it has already processed to avoid processing the same event more than once on restart.
|
||||
|
||||
Logstash records its progress in a file that's referred to as a `sinceDB` file. Logstash creates a `sinceDB` file for each file that it watches for changes.
|
||||
|
||||
2. Open the `sinceDB` file to check how much of the input files are processed:
|
||||
|
||||
```bash
|
||||
cd data/plugins/inputs/file/
|
||||
ls -al
|
||||
|
||||
-rw-r--r-- 1 user staff 0 Jun 13 10:50 .sincedb_9e484f2a9e6c0d1bdfe6f23ac107ffc5
|
||||
|
||||
cat .sincedb_9e484f2a9e6c0d1bdfe6f23ac107ffc5
|
||||
|
||||
51575938 1 4 7727
|
||||
```
|
||||
|
||||
The last number in the `sinceDB` file (7727) is the byte offset of the last known event processed.
|
||||
|
||||
5. To process the input file from the beginning, delete the `sinceDB` file:
|
||||
|
||||
```yml
|
||||
rm .sincedb_*
|
||||
```
|
||||
|
||||
2. Start Logstash with a `—-config.reload.automatic` argument:
|
||||
|
||||
```bash
|
||||
bin/logstash -f config/pipeline.conf --config.reload.automatic
|
||||
```
|
||||
|
||||
The `reload` option only reloads if you add a new line at the end of the pipeline configuration file.
|
||||
|
||||
Sample output:
|
||||
|
||||
```yml
|
||||
{
|
||||
"message" => "216.243.171.38 - - [20/Sep/2017:19:11:52 +0200] \"GET /products/view/123 HTTP/1.1\" 200 12798 \"https://codingexplained.com/products\" \"Mozilla/5.0 (compatible; YandexBot/3.0; +http://yandex.com/bots)\"",
|
||||
"@version" => "1",
|
||||
"host" => "a483e711a548.ant.amazon.com",
|
||||
"path" => "/Users/kumarjao/Desktop/odfe1/logstash-7.12.1/events-data/input_file.log",
|
||||
"@timestamp" => 2021-06-13T18:03:30.423Z
|
||||
}
|
||||
{
|
||||
"message" => "91.59.108.75 - - [20/Sep/2017:20:11:43 +0200] \"GET /js/main.js HTTP/1.1\" 200 588 \"https://codingexplained.com/products/view/863\" \"Mozilla/5.0 (Windows NT 6.1; WOW64; rv:45.0) Gecko/20100101 Firefox/45.0\"",
|
||||
"@version" => "1",
|
||||
"host" => "a483e711a548.ant.amazon.com",
|
||||
"path" => "/Users/kumarjao/Desktop/odfe1/logstash-7.12.1/events-data/input_file.log",
|
||||
"@timestamp" => 2021-06-13T18:03:30.424Z
|
||||
}
|
||||
```
|
||||
|
||||
7. Add a new line to the input file.
|
||||
- Logstash immediately detects the change and processes the new line as an event.
|
||||
|
||||
8. Make a change to the `pipeline.conf` file.
|
||||
- Logstash immediately detects the change and reloads the modified pipeline.
|
||||
@@ -1,77 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Ship events to OpenSearch
|
||||
parent: Logstash
|
||||
nav_order: 220
|
||||
---
|
||||
|
||||
# Ship events to OpenSearch
|
||||
|
||||
You can Ship Logstash events to an OpenSearch cluster and then visualize your events with OpenSearch Dashboards.
|
||||
|
||||
Make sure you have [Logstash]({{site.url}}{{site.baseurl}}/clients/logstash/index/#install-logstash), [OpenSearch]({{site.url}}{{site.baseurl}}/opensearch/install/index/), and [OpenSearch Dashboards]({{site.url}}{{site.baseurl}}/dashboards/install/index/).
|
||||
{: .note }
|
||||
|
||||
## OpenSearch output plugin
|
||||
|
||||
To run the OpenSearch output plugin, add the following configuration in your `pipeline.conf` file:
|
||||
|
||||
```yml
|
||||
output {
|
||||
opensearch {
|
||||
hosts => "https://localhost:9200"
|
||||
user => "admin"
|
||||
password => "admin"
|
||||
index => "logstash-logs-%{+YYYY.MM.dd}"
|
||||
ssl_certificate_verification => false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
## Sample walkthrough
|
||||
|
||||
1. Open the `config/pipeline.conf` file and add in the following configuration:
|
||||
|
||||
```yml
|
||||
input {
|
||||
stdin {
|
||||
codec => json
|
||||
}
|
||||
}
|
||||
|
||||
output {
|
||||
opensearch {
|
||||
hosts => "https://localhost:9200"
|
||||
user => "admin"
|
||||
password => "admin"
|
||||
index => "logstash-logs-%{+YYYY.MM.dd}"
|
||||
ssl_certificate_verification => false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
This Logstash pipeline accepts JSON input through the terminal and ships the events to an OpenSearch cluster running locally. Logstash writes the events to an index with the `logstash-logs-%{+YYYY.MM.dd}` naming convention.
|
||||
|
||||
2. Start Logstash:
|
||||
|
||||
```bash
|
||||
$ bin/logstash -f config/pipeline.conf --config.reload.automatic
|
||||
```
|
||||
|
||||
`config/pipeline.conf` is a relative path to the `pipeline.conf` file. You can use an absolute path as well.
|
||||
|
||||
3. Add a JSON object in the terminal:
|
||||
|
||||
```json
|
||||
{ "amount": 10, "quantity": 2}
|
||||
```
|
||||
|
||||
4. Start OpenSearch Dashboards and choose **Dev Tools**:
|
||||
|
||||
```json
|
||||
GET _cat/indices?v
|
||||
|
||||
health | status | index | uuid | pri | rep | docs.count | docs.deleted | store.size | pri.store.size
|
||||
green | open | logstash-logs-2021.07.01 | iuh648LYSnmQrkGf70pplA | 1 | 1 | 1 | 0 | 10.3kb | 5.1kb
|
||||
```
|
||||
@@ -1,128 +0,0 @@
|
||||
---
|
||||
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)
|
||||
```
|
||||
+21
-77
@@ -1,13 +1,27 @@
|
||||
# Welcome to Jekyll!
|
||||
#
|
||||
# This config file is meant for settings that affect your whole blog, values
|
||||
# which you are expected to set up once and rarely edit after that. If you find
|
||||
# yourself editing this file very often, consider using Jekyll's data files
|
||||
# feature for the data you need to update frequently.
|
||||
#
|
||||
# For technical reasons, this file is *NOT* reloaded automatically when you use
|
||||
# 'bundle exec jekyll serve'. If you change this file, please restart the server process.
|
||||
|
||||
# Site settings
|
||||
# These are used to personalize your new site. If you look in the HTML files,
|
||||
# you will see them accessed via {{ site.title }}, {{ site.email }}, and so on.
|
||||
# You can create any custom variable you would like, and they will be accessible
|
||||
# in the templates via {{ site.myvariable }}.
|
||||
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
|
||||
url: "https://opensearch.org" # the base hostname & protocol for your site, e.g. http://example.com
|
||||
permalink: /:path/
|
||||
baseurl: "" # the subpath of your site, e.g. /blog
|
||||
url: "https://docs-beta.opensearch.org" # the base hostname & protocol for your site, e.g. http://example.com
|
||||
permalink: pretty
|
||||
|
||||
opensearch_version: 1.0.1
|
||||
opensearch_version: 1.0.0-beta1
|
||||
opensearch_major_minor_version: 1.0
|
||||
lucene_version: 8_8_2
|
||||
|
||||
# Build settings
|
||||
markdown: kramdown
|
||||
@@ -21,79 +35,10 @@ logo: "/assets/images/logo.svg"
|
||||
|
||||
# Aux links for the upper right navigation
|
||||
aux_links:
|
||||
|
||||
"Back to OpenSearch.org":
|
||||
- "https://opensearch.org"
|
||||
color_scheme: opensearch
|
||||
|
||||
# Define Jekyll collections
|
||||
collections:
|
||||
# Define a collection named "tests", its documents reside in the "_tests" directory
|
||||
upgrade-to:
|
||||
permalink: /:collection/:path/
|
||||
output: true
|
||||
opensearch:
|
||||
permalink: /:collection/:path/
|
||||
output: true
|
||||
dashboards:
|
||||
permalink: /:collection/:path/
|
||||
output: true
|
||||
security-plugin:
|
||||
permalink: /:collection/:path/
|
||||
output: true
|
||||
search-plugins:
|
||||
permalink: /:collection/:path/
|
||||
output: true
|
||||
im-plugin:
|
||||
permalink: /:collection/:path/
|
||||
output: true
|
||||
monitoring-plugins:
|
||||
permalink: /:collection/:path/
|
||||
output: true
|
||||
clients:
|
||||
permalink: /:collection/:path/
|
||||
output: true
|
||||
troubleshoot:
|
||||
permalink: /:collection/:path/
|
||||
output: true
|
||||
external_links:
|
||||
permalink: /:collection/:path/
|
||||
output: true
|
||||
|
||||
just_the_docs:
|
||||
# Define the collections used in the theme
|
||||
collections:
|
||||
upgrade-to:
|
||||
name: Upgrade to OpenSearch
|
||||
# nav_exclude: true
|
||||
nav_fold: true
|
||||
# search_exclude: true
|
||||
opensearch:
|
||||
name: OpenSearch
|
||||
nav_fold: true
|
||||
dashboards:
|
||||
name: OpenSearch Dashboards
|
||||
nav_fold: true
|
||||
security-plugin:
|
||||
name: Security plugin
|
||||
nav_fold: true
|
||||
search-plugins:
|
||||
name: Search plugins
|
||||
nav_fold: true
|
||||
im-plugin:
|
||||
name: Index management plugin
|
||||
nav_fold: true
|
||||
monitoring-plugins:
|
||||
name: Monitoring plugins
|
||||
nav_fold: true
|
||||
clients:
|
||||
name: Clients and tools
|
||||
nav_fold: true
|
||||
troubleshoot:
|
||||
name: Troubleshooting
|
||||
nav_fold: true
|
||||
external_links:
|
||||
name: External links
|
||||
|
||||
|
||||
# Enable or disable the site search
|
||||
# Supports true (default) or false
|
||||
search_enabled: true
|
||||
@@ -138,7 +83,6 @@ footer_content:
|
||||
plugins:
|
||||
- jekyll-remote-theme
|
||||
- jekyll-redirect-from
|
||||
- jekyll-sitemap
|
||||
|
||||
# Exclude from processing.
|
||||
# The following items will not be processed, by default. Create a custom list
|
||||
|
||||
@@ -1,17 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Browser compatibility
|
||||
parent: OpenSearch Dashboards
|
||||
nav_order: 3
|
||||
---
|
||||
|
||||
# Browser compatibility
|
||||
|
||||
OpenSearch Dashboards supports the following web browsers:
|
||||
|
||||
- Chrome
|
||||
- Firefox
|
||||
- Safari
|
||||
- Edge (Chromium)
|
||||
|
||||
Other Chromium-based browsers might work, as well. Internet Explorer and Microsoft Edge Legacy are **not** supported.
|
||||
@@ -1,135 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Helm
|
||||
parent: Install OpenSearch Dashboards
|
||||
nav_order: 35
|
||||
---
|
||||
|
||||
# Run OpenSearch Dashboards using Helm
|
||||
|
||||
Helm is a package manager that allows you to easily install and manage OpenSearch Dashboards in a Kubernetes cluster. You can define your OpenSearch configurations in a YAML file and use Helm to deploy your applications in a version-controlled and reproducible way.
|
||||
|
||||
The Helm chart contains the resources described in the following table.
|
||||
|
||||
Resource | Description
|
||||
:--- | :---
|
||||
`Chart.yaml` | Information about the chart.
|
||||
`values.yaml` | Default configuration values for the chart.
|
||||
`templates` | Templates that combine with values to generate the Kubernetes manifest files.
|
||||
|
||||
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/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 }
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before you get started, you must first use [Helm to install OpenSearch]({{site.url}}{{site.baseurl}}/opensearch/install/helm/).
|
||||
|
||||
Make sure that you can send requests to your OpenSearch pod:
|
||||
|
||||
```json
|
||||
$ curl -XGET https://localhost:9200 -u 'admin:admin' --insecure
|
||||
{
|
||||
"name" : "opensearch-cluster-master-1",
|
||||
"cluster_name" : "opensearch-cluster",
|
||||
"cluster_uuid" : "hP2gq5bPS3SLp8Z7wXm8YQ",
|
||||
"version" : {
|
||||
"distribution" : "opensearch",
|
||||
"number" : "1.0.0",
|
||||
"build_type" : "tar",
|
||||
"build_hash" : "34550c5b17124ddc59458ef774f6b43a086522e3",
|
||||
"build_date" : "2021-07-02T23:22:21.383695Z",
|
||||
"build_snapshot" : false,
|
||||
"lucene_version" : "8.8.2",
|
||||
"minimum_wire_compatibility_version" : "6.8.0",
|
||||
"minimum_index_compatibility_version" : "6.0.0-beta1"
|
||||
},
|
||||
"tagline" : "The OpenSearch Project: https://opensearch.org/"
|
||||
}
|
||||
```
|
||||
|
||||
## Install OpenSearch Dashboards using Helm
|
||||
|
||||
1. Change to the `opensearch-dashboards` directory:
|
||||
|
||||
```bash
|
||||
cd opensearch-dashboards
|
||||
```
|
||||
|
||||
1. Package the Helm chart:
|
||||
|
||||
```bash
|
||||
helm package .
|
||||
```
|
||||
|
||||
1. Deploy OpenSearch Dashboards:
|
||||
|
||||
```bash
|
||||
helm install --generate-name opensearch-dashboards-1.0.0.tgz
|
||||
```
|
||||
The output shows you the specifications instantiated from the install.
|
||||
To customize the deployment, pass in the values that you want to override with a custom YAML file:
|
||||
|
||||
```bash
|
||||
helm install --values=customvalues.yaml opensearch-dashboards-1.0.0.tgz
|
||||
```
|
||||
|
||||
#### Sample output
|
||||
|
||||
```yaml
|
||||
NAME: opensearch-dashboards-1-1629223356
|
||||
LAST DEPLOYED: Tue Aug 17 18:02:37 2021
|
||||
NAMESPACE: default
|
||||
STATUS: deployed
|
||||
REVISION: 1
|
||||
TEST SUITE: None
|
||||
NOTES:
|
||||
1. Get the application URL by running these commands:
|
||||
export POD_NAME=$(kubectl get pods --namespace default -l "app.kubernetes.io/name=opensearch-dashboards,app.kubernetes.io/instance=op
|
||||
ensearch-dashboards-1-1629223356" -o jsonpath="{.items[0].metadata.name}")
|
||||
export CONTAINER_PORT=$(kubectl get pod --namespace default $POD_NAME -o jsonpath="{.spec.containers[0].ports[0].containerPort}")
|
||||
echo "Visit http://127.0.0.1:8080 to use your application"
|
||||
kubectl --namespace default port-forward $POD_NAME 8080:$CONTAINER_PORT
|
||||
```
|
||||
|
||||
To make sure your OpenSearch Dashboards pod is up and running, run the following command:
|
||||
|
||||
```bash
|
||||
$ kubectl get pods
|
||||
NAME READY STATUS RESTARTS AGE
|
||||
opensearch-cluster-master-0 1/1 Running 0 4m35s
|
||||
opensearch-cluster-master-1 1/1 Running 0 4m35s
|
||||
opensearch-cluster-master-2 1/1 Running 0 4m35s
|
||||
opensearch-dashboards-1-1629223356-758bd8747f-8www5 1/1 Running 0 66s
|
||||
```
|
||||
|
||||
To set up port forwarding to access OpenSearch Dashboards, exit the OpenSearch shell and run the following command:
|
||||
|
||||
```bash
|
||||
$ kubectl port-forward deployment/opensearch-dashboards-1-1629223356 5601
|
||||
```
|
||||
|
||||
You can now access OpenSearch Dashboards from your browser at: http://localhost:5601.
|
||||
|
||||
|
||||
## Uninstall using Helm
|
||||
|
||||
To identify the OpenSearch Dashboards deployment that you want to delete:
|
||||
|
||||
```bash
|
||||
$ helm list
|
||||
NAME NAMESPACE REVISION UPDATED STATUS CHART APP VERSION
|
||||
opensearch-1-1629223146 default 1 2021-08-17 17:59:07.664498239 +0000 UTCdeployedopensearch-1.0.0 1.0.0
|
||||
opensearch-dashboards-1-1629223356 default 1 2021-08-17 18:02:37.600796946 +0000 UTCdepl
|
||||
oyedopensearch-dashboards-1.0.0 1.0.0
|
||||
```
|
||||
|
||||
To delete or uninstall a deployment, run the following command:
|
||||
|
||||
```bash
|
||||
helm delete opensearch-dashboards-1-1629223356
|
||||
```
|
||||
@@ -1,12 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Install OpenSearch Dashboards
|
||||
nav_order: 1
|
||||
has_children: true
|
||||
redirect_from:
|
||||
- /dashboards/install/
|
||||
---
|
||||
|
||||
# Install and configure OpenSearch Dashboards
|
||||
|
||||
OpenSearch Dashboards has three installation options at this time: Docker images, tarballs, and Helm charts.
|
||||
@@ -1,41 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Configure TLS
|
||||
parent: Install OpenSearch Dashboards
|
||||
nav_order: 40
|
||||
---
|
||||
|
||||
# Configure TLS for OpenSearch Dashboards
|
||||
|
||||
By default, for ease of testing and getting started, OpenSearch Dashboards runs over HTTP. To enable TLS for HTTPS, update the following settings in `opensearch_dashboards.yml`.
|
||||
|
||||
Setting | Description
|
||||
:--- | :---
|
||||
opensearch.ssl.verificationMode | This setting is for communications between OpenSearch and OpenSearch Dashboards. Valid values are `full`, `certificate`, or `none`. We recommend `full` if you enable TLS, which enables hostname verification. `certificate` just checks the certificate, not the hostname, and `none` performs no checks (suitable for HTTP). Default is `full`.
|
||||
opensearch.ssl.certificateAuthorities | If `opensearch.ssl.verificationMode` is `full` or `certificate`, specify the full path to one or more CA certificates that comprise a trusted chain for your OpenSearch cluster. For example, you might need to include a root CA _and_ an intermediate CA if you used the intermediate CA to issue your admin, client, and node certificates.
|
||||
server.ssl.enabled | This setting is for communications between OpenSearch Dashboards and the web browser. Set to true for HTTPS, false for HTTP.
|
||||
server.ssl.certificate | If `server.ssl.enabled` is true, specify the full path to a valid client certificate for your OpenSearch cluster. You can [generate your own]({{site.url}}{{site.baseurl}}/security-plugin/configuration/generate-certificates/) or get one from a certificate authority.
|
||||
server.ssl.key | If `server.ssl.enabled` is true, specify the full path (e.g. `/usr/share/opensearch-dashboards-1.0.0/config/my-client-cert-key.pem` to the key for your client certificate. You can [generate your own]({{site.url}}{{site.baseurl}}/security-plugin/configuration/generate-certificates/) or get one from a certificate authority.
|
||||
opensearch_security.cookie.secure | If you enable TLS for OpenSearch Dashboards, change this setting to `true`. For HTTP, set it to `false`.
|
||||
|
||||
This `opensearch_dashboards.yml` configuration shows OpenSearch and OpenSearch Dashboards running on the same machine with the demo configuration:
|
||||
|
||||
```yml
|
||||
opensearch.hosts: ["https://localhost:9200"]
|
||||
opensearch.ssl.verificationMode: full
|
||||
opensearch.username: "kibanaserver"
|
||||
opensearch.password: "kibanaserver"
|
||||
opensearch.requestHeadersWhitelist: [ authorization,securitytenant ]
|
||||
server.ssl.enabled: true
|
||||
server.ssl.certificate: /usr/share/opensearch-dashboards/config/client-cert.pem
|
||||
server.ssl.key: /usr/share/opensearch-dashboards/config/client-cert-key.pem
|
||||
opensearch.ssl.certificateAuthorities: [ "/usr/share/opensearch-dashboards/config/root-ca.pem", "/usr/share/opensearch-dashboards/config/intermediate-ca.pem" ]
|
||||
opensearch_security.multitenancy.enabled: true
|
||||
opensearch_security.multitenancy.tenants.preferred: ["Private", "Global"]
|
||||
opensearch_security.readonly_mode.roles: ["kibana_read_only"]
|
||||
opensearch_security.cookie.secure: true
|
||||
```
|
||||
|
||||
If you use the Docker install, you can pass a custom `opensearch_dashboards.yml` to the container. To learn more, see the [Docker installation page]({{site.url}}{{site.baseurl}}/opensearch/install/docker/).
|
||||
|
||||
After enabling these settings and starting OpenSearch Dashboards, you can connect to it at `https://localhost:5601`. You might have to acknowledge a browser warning if your certificates are self-signed. To avoid this sort of warning (or outright browser incompatibility), best practice is to use certificates from trusted certificate authority.
|
||||
@@ -1,124 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Notebooks
|
||||
nav_order: 50
|
||||
redirect_from: /notebooks/
|
||||
has_children: false
|
||||
---
|
||||
|
||||
# Notebooks
|
||||
|
||||
An OpenSearch Dashboards notebook is an interface that lets you easily combine code snippets, live visualizations, and narrative text in a single notebook interface.
|
||||
|
||||
Notebooks let you interactively explore data by running different visualizations that you can share with team members to collaborate on a project.
|
||||
|
||||
A notebook is a document composed of two elements: code blocks (Markdown/SQL/PPL) and visualizations. Choose multiple timelines to compare and contrast visualizations.
|
||||
|
||||
You can also generate [reports]({{site.url}}{{site.baseurl}}/dashboards/reporting/) directly from your notebooks.
|
||||
|
||||
Common use cases include creating postmortem reports, designing runbooks, building live infrastructure reports, and writing documentation.
|
||||
|
||||
Tenants in OpenSearch Dashboards are spaces for saving notebooks and other OpenSearch Dashboards objects. For more information, see [OpenSearch Dashboards multi-tenancy]({{site.url}}{{site.baseurl}}/security-plugin/access-control/multi-tenancy/).
|
||||
{: .note }
|
||||
|
||||
|
||||
## Get started with notebooks
|
||||
|
||||
To get started, choose **Notebooks** within OpenSearch Dashboards.
|
||||
|
||||
|
||||
### Step 1: Create a notebook
|
||||
|
||||
A notebook is an interface for creating reports.
|
||||
|
||||
1. Choose **Create notebook** and enter a descriptive name.
|
||||
1. Choose **Create**.
|
||||
|
||||
Choose **Actions** to rename, duplicate, or delete a notebook.
|
||||
|
||||
|
||||
|
||||
### Step 2: Add a paragraph
|
||||
|
||||
Paragraphs combine code blocks and visualizations for describing data.
|
||||
|
||||
#### Add a code block
|
||||
|
||||
Code blocks support markdown, SQL, and PPL languages.
|
||||
|
||||
Specify the input language on the first line using `%[language type]` syntax.
|
||||
For example, type `%md` for markdown, `%sql` for SQL, and `%ppl` for PPL.
|
||||
|
||||
##### Sample markdown block
|
||||
|
||||
```
|
||||
%md
|
||||
Add in text formatted in markdown.
|
||||
```
|
||||
|
||||
|
||||
|
||||
##### Sample SQL block
|
||||
|
||||
```sql
|
||||
%sql
|
||||
Select * from opensearch_dashboards_sample_data_flights limit 20;
|
||||
```
|
||||
|
||||
|
||||
|
||||
##### Sample PPL block
|
||||
|
||||
```
|
||||
%ppl
|
||||
source=opensearch_dashboards_sample_data_logs | head 20
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
#### Add a visualization
|
||||
|
||||
1. To add a visualization, choose **Add paragraph** and select **Visualization**.
|
||||
1. In **Title**, select your visualization and choose a date range. You can choose multiple timelines to compare and contrast visualizations.
|
||||
1. To run and save a paragraph, choose **Run**.
|
||||
|
||||
|
||||
|
||||
## Paragraph actions
|
||||
|
||||
You can perform the following actions on paragraphs:
|
||||
|
||||
- Add a new paragraph to the top of a report.
|
||||
- Add a new paragraph to the bottom of a report.
|
||||
- Run all the paragraphs at the same time.
|
||||
- Clear the outputs of all paragraphs.
|
||||
- Delete all the paragraphs.
|
||||
|
||||
|
||||
|
||||
## Sample notebooks
|
||||
|
||||
We prepared the following sample notebooks that showcase a variety of use cases:
|
||||
|
||||
- Using SQL to query the OpenSearch Dashboards sample flight data.
|
||||
- Using PPL to query the OpenSearch Dashboards sample web logs data.
|
||||
- Using PPL and visualizations to perform sample root cause event analysis on the OpenSearch Dashboards sample web logs data.
|
||||
|
||||
To add a sample notebook, choose **Actions** and select **Add sample notebooks**.
|
||||
|
||||
|
||||
|
||||
## Create a report
|
||||
|
||||
You can use notebooks to create PNG and PDF reports:
|
||||
|
||||
1. From the top menu bar, choose **Reporting actions**.
|
||||
1. You can choose to **Download PDF** or **Download PNG**.
|
||||
|
||||
Reports generate asynchronously in the background and might take a few minutes, depending on the size of the report. A notification appears when your report is ready to download.
|
||||
|
||||
1. To create a schedule-based report, choose **Create report definition**. For steps to create a report definition, see [Create reports using a definition]({{site.url}}{{site.baseurl}}/dashboards/reporting#create-reports-using-a-definition).
|
||||
1. To see all your reports, choose **View all reports**.
|
||||
|
||||
|
||||
@@ -1 +0,0 @@
|
||||
message: "🌡️ [OpenSearch 1.1.0 is here, get it while it's hot!](/downloads.html)"
|
||||
@@ -1,49 +0,0 @@
|
||||
columns:
|
||||
-
|
||||
title: 'Get Involved'
|
||||
links:
|
||||
-
|
||||
title: Code of Conduct
|
||||
url: '/codeofconduct.html'
|
||||
-
|
||||
title: 'Forums'
|
||||
url: 'https://discuss.opendistrocommunity.dev/'
|
||||
-
|
||||
title: 'Github'
|
||||
url: 'https://github.com/opensearch-project'
|
||||
-
|
||||
title: 'Partners'
|
||||
url: '/partners/'
|
||||
-
|
||||
title: 'Community Projects'
|
||||
url: '/community_projects'
|
||||
-
|
||||
title: 'Resources'
|
||||
links:
|
||||
#-
|
||||
# title: 'Documentation'
|
||||
# url: 'https://github.com/opensearch/documentation'
|
||||
-
|
||||
title: FAQ
|
||||
url: '/faq/'
|
||||
-
|
||||
title: 'Brand Guidelines'
|
||||
url: '/brand.html'
|
||||
-
|
||||
title: 'Trademark Usage Policy'
|
||||
url: '/trademark-usage.html'
|
||||
-
|
||||
title: OpenSearch Disambiguation
|
||||
url: '/disambiguation.html'
|
||||
-
|
||||
title: 'Connect'
|
||||
links:
|
||||
# -
|
||||
# title: 'Twitter'
|
||||
# url: 'https://twitter.com/opensearch_project'
|
||||
#-
|
||||
# title: 'Facebook'
|
||||
# url: 'http://www.facebook.com/opensearch'
|
||||
-
|
||||
title: 'E-mail'
|
||||
url: 'mailto:opensearch@amazon.com'
|
||||
@@ -1,4 +0,0 @@
|
||||
{
|
||||
"current": "1.0",
|
||||
"past": []
|
||||
}
|
||||
@@ -1,7 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Dashboards developer guide
|
||||
nav_order: 2
|
||||
permalink: /dashboards-developer-guide/
|
||||
redirect_to: https://github.com/opensearch-project/OpenSearch-Dashboards/blob/main/DEVELOPER_GUIDE.md
|
||||
---
|
||||
@@ -1,7 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Javadoc
|
||||
nav_order: 1
|
||||
permalink: /javadoc/
|
||||
redirect_to: https://opensearch.org/javadocs/
|
||||
---
|
||||
@@ -1,6 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
nav_exclude: true
|
||||
permalink: /javadocs/
|
||||
redirect_to: https://opensearch.org/javadocs/
|
||||
---
|
||||
@@ -1,156 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Index transforms
|
||||
nav_order: 20
|
||||
has_children: true
|
||||
redirect_from: /im-plugin/index-transforms/
|
||||
has_toc: false
|
||||
---
|
||||
|
||||
# Index transforms
|
||||
|
||||
Whereas index rollup jobs let you reduce data granularity by rolling up old data into condensed indices, transform jobs let you create a different, summarized view of your data centered around certain fields, so you can visualize or analyze the data in different ways.
|
||||
|
||||
For example, suppose that you have airline data that’s scattered across multiple fields and categories, and you want to view a summary of the data that’s organized by airline, quarter, and then price. You can use a transform job to create a new, summarized index that’s organized by those specific categories.
|
||||
|
||||
You can use transform jobs in two ways:
|
||||
|
||||
1. Use the OpenSearch Dashboards UI to specify the index you want to transform and any optional data filters you want to use to filter the original index. Then select the fields you want to transform and the aggregations to use in the transformation. Finally, define a schedule for your job to follow.
|
||||
2. Use the transforms API to specify all the details about your job: the index you want to transform, target groups you want the transformed index to have, any aggregations you want to use to group columns, and a schedule for your job to follow.
|
||||
|
||||
OpenSearch Dashboards provides a detailed summary of the jobs you created and their relevant information, such as associated indices and job statuses. You can review and edit your job’s details and selections before creation, and even preview a transformed index’s data as you’re choosing which fields to transform. However, you can also use the REST API to create transform jobs and preview transform job results, but you must know all of the necessary settings and parameters to submit them as part of the HTTP request body. Submitting your transform job configurations as JSON scripts offers you more portability, allowing you to share and replicate your transform jobs, which is harder to do using OpenSearch Dashboards.
|
||||
|
||||
Your use cases will help you decide which method to use to create transform jobs.
|
||||
|
||||
## Create a transform job
|
||||
|
||||
If you don't have any data in your cluster, you can use the sample flight data within OpenSearch Dashboards to try out transform jobs. Otherwise, after launching OpenSearch Dashboards, choose **Index Management**. Select **Transform Jobs**, and choose **Create Transform Job**.
|
||||
|
||||
### 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/).
|
||||
3. Choose **Next**.
|
||||
|
||||
### Step 2: Select fields to transform
|
||||
|
||||
After specifying the indices, you can select the fields you want to use in your transform job, as well as whether to use groupings or aggregations.
|
||||
|
||||
You can use groupings to place your data into separate buckets in your transformed index. For example, if you want to group all of the airport destinations within the sample flight data, you can group the `DestAirportID` field into a target field of `DestAirportID_terms` field, and you can find the grouped airport IDs in your transformed index after the transform job finishes.
|
||||
|
||||
On the other hand, aggregations let you perform simple calculations. For example, you can include an aggregation in your transform job to define a new field of `sum_of_total_ticket_price` that calculates the sum of all airplane tickets, and then analyze the newly summer data within your transformed index.
|
||||
|
||||
1. In the data table, select the fields you want to transform and expand the drop-down menu within the column header to choose the grouping or aggregation you want to use.
|
||||
|
||||
Currently, transform jobs support histogram, date_histogram, and terms groupings. For more information about groupings, see [Bucket Aggregations]({{site.url}}{{site.baseurl}}/opensearch/bucket-agg/). In terms of aggregations, you can select from `sum`, `avg`, `max`, `min`, `value_count`, `percentiles`, and `scripted_metric`. For more information about aggregations, see [Metric Aggregations]({{site.url}}{{site.baseurl}}/opensearch/metric-agg/).
|
||||
|
||||
2. Repeat step 1 for any other fields that you want to transform.
|
||||
3. After selecting the fields that you want to transform and verifying the transformation, choose **Next**.
|
||||
|
||||
### Step 3: Specify a schedule
|
||||
|
||||
You can configure transform jobs to run once or multiple times on a schedule. Transform jobs are enabled by default.
|
||||
|
||||
1. For **transformation execution frequency**, select **Define by fixed interval** and specify a **transform interval**.
|
||||
2. Under **Advanced**, specify an optional amount for **Pages per execution**. A larger number means more data is processed in each search request, but also uses more memory and causes higher latency. Exceeding allowed memory limits can cause exceptions and errors to occur.
|
||||
3. Choose **Next**.
|
||||
|
||||
### Step 4: Review and confirm details
|
||||
|
||||
After confirming your transform job’s details are correct, choose **Create Transform Job**. If you want to edit any part of the job, choose **Edit** of the section you want to change, and make the necessary changes. You can’t change aggregations or groupings after creating a job.
|
||||
|
||||
### Step 5: Search through the transformed index.
|
||||
|
||||
Once the transform job finishes, you can use the `_search` API operation to search the target index.
|
||||
|
||||
```json
|
||||
GET <target_index>/_search
|
||||
```
|
||||
|
||||
For example, after running a transform job that transforms the flight data based on a `DestAirportID` field, you can run the following request that returns all of the fields that have a value of `SFO`.
|
||||
|
||||
**Sample Request**
|
||||
|
||||
```json
|
||||
GET finished_flight_job/_search
|
||||
{
|
||||
"query": {
|
||||
"match": {
|
||||
"DestAirportID_terms" : "SFO"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Sample Response**
|
||||
|
||||
```json
|
||||
{
|
||||
"took" : 3,
|
||||
"timed_out" : false,
|
||||
"_shards" : {
|
||||
"total" : 5,
|
||||
"successful" : 5,
|
||||
"skipped" : 0,
|
||||
"failed" : 0
|
||||
},
|
||||
"hits" : {
|
||||
"total" : {
|
||||
"value" : 4,
|
||||
"relation" : "eq"
|
||||
},
|
||||
"max_score" : 3.845883,
|
||||
"hits" : [
|
||||
{
|
||||
"_index" : "finished_flight_job",
|
||||
"_type" : "_doc",
|
||||
"_id" : "dSNKGb8U3OJOmC4RqVCi1Q",
|
||||
"_score" : 3.845883,
|
||||
"_source" : {
|
||||
"transform._id" : "sample_flight_job",
|
||||
"transform._doc_count" : 14,
|
||||
"Carrier_terms" : "Dashboards Airlines",
|
||||
"DestAirportID_terms" : "SFO"
|
||||
}
|
||||
},
|
||||
{
|
||||
"_index" : "finished_flight_job",
|
||||
"_type" : "_doc",
|
||||
"_id" : "_D7oqOy7drx9E-MG96U5RA",
|
||||
"_score" : 3.845883,
|
||||
"_source" : {
|
||||
"transform._id" : "sample_flight_job",
|
||||
"transform._doc_count" : 14,
|
||||
"Carrier_terms" : "Logstash Airways",
|
||||
"DestAirportID_terms" : "SFO"
|
||||
}
|
||||
},
|
||||
{
|
||||
"_index" : "finished_flight_job",
|
||||
"_type" : "_doc",
|
||||
"_id" : "YuZ8tOt1OsBA54e84WuAEw",
|
||||
"_score" : 3.6988301,
|
||||
"_source" : {
|
||||
"transform._id" : "sample_flight_job",
|
||||
"transform._doc_count" : 11,
|
||||
"Carrier_terms" : "ES-Air",
|
||||
"DestAirportID_terms" : "SFO"
|
||||
}
|
||||
},
|
||||
{
|
||||
"_index" : "finished_flight_job",
|
||||
"_type" : "_doc",
|
||||
"_id" : "W_-e7bVmH6eu8veJeK8ZxQ",
|
||||
"_score" : 3.6988301,
|
||||
"_source" : {
|
||||
"transform._id" : "sample_flight_job",
|
||||
"transform._doc_count" : 10,
|
||||
"Carrier_terms" : "JetBeats",
|
||||
"DestAirportID_terms" : "SFO"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
|
||||
```
|
||||
@@ -1,729 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Transforms APIs
|
||||
nav_order: 45
|
||||
parent: Index transforms
|
||||
has_toc: true
|
||||
---
|
||||
|
||||
# Transforms APIs
|
||||
|
||||
Aside from using OpenSearch Dashboards, you can also use the REST API to create, start, stop, and complete other operations relative to transform jobs.
|
||||
|
||||
#### Table of contents
|
||||
- TOC
|
||||
{:toc}
|
||||
|
||||
## Create a transform job
|
||||
Introduced 1.0
|
||||
{: .label .label-purple }
|
||||
|
||||
Creates a transform job.
|
||||
|
||||
**Sample Request**
|
||||
|
||||
```json
|
||||
PUT _plugins/_transform/<transform_id>
|
||||
|
||||
{
|
||||
"transform": {
|
||||
"enabled": true,
|
||||
"schedule": {
|
||||
"interval": {
|
||||
"period": 1,
|
||||
"unit": "Minutes",
|
||||
"start_time": 1602100553
|
||||
}
|
||||
},
|
||||
"description": "Sample transform job",
|
||||
"source_index": "sample_index",
|
||||
"target_index": "sample_target",
|
||||
"data_selection_query": {
|
||||
"match_all": {}
|
||||
},
|
||||
"page_size": 1,
|
||||
"groups": [
|
||||
{
|
||||
"terms": {
|
||||
"source_field": "customer_gender",
|
||||
"target_field": "gender"
|
||||
}
|
||||
},
|
||||
{
|
||||
"terms": {
|
||||
"source_field": "day_of_week",
|
||||
"target_field": "day"
|
||||
}
|
||||
}
|
||||
],
|
||||
"aggregations": {
|
||||
"quantity": {
|
||||
"sum": {
|
||||
"field": "total_quantity"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Sample Response**
|
||||
|
||||
```json
|
||||
{
|
||||
"_id": "sample",
|
||||
"_version": 7,
|
||||
"_seq_no": 13,
|
||||
"_primary_term": 1,
|
||||
"transform": {
|
||||
"transform_id": "sample",
|
||||
"schema_version": 7,
|
||||
"schedule": {
|
||||
"interval": {
|
||||
"start_time": 1621467964243,
|
||||
"period": 1,
|
||||
"unit": "Minutes"
|
||||
}
|
||||
},
|
||||
"metadata_id": null,
|
||||
"updated_at": 1621467964243,
|
||||
"enabled": true,
|
||||
"enabled_at": 1621467964243,
|
||||
"description": "Sample transform job",
|
||||
"source_index": "sample_index",
|
||||
"data_selection_query": {
|
||||
"match_all": {
|
||||
"boost": 1.0
|
||||
}
|
||||
},
|
||||
"target_index": "sample_target",
|
||||
"roles": [],
|
||||
"page_size": 1,
|
||||
"groups": [
|
||||
{
|
||||
"terms": {
|
||||
"source_field": "customer_gender",
|
||||
"target_field": "gender"
|
||||
}
|
||||
},
|
||||
{
|
||||
"terms": {
|
||||
"source_field": "day_of_week",
|
||||
"target_field": "day"
|
||||
}
|
||||
}
|
||||
],
|
||||
"aggregations": {
|
||||
"quantity": {
|
||||
"sum": {
|
||||
"field": "total_quantity"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
You can specify the following options in the HTTP request body:
|
||||
|
||||
Option | Data Type | Description | Required
|
||||
:--- | :--- | :--- | :---
|
||||
enabled | Boolean | If true, the transform job is enabled at creation. | No
|
||||
schedule | JSON | The schedule the transform job runs on. | Yes
|
||||
start_time | Integer | The Unix epoch time of the transform job's start time. | Yes
|
||||
description | String | Describes the transform job. | No
|
||||
metadata_id | String | Any metadata to be associated with the transform job. | No
|
||||
source_index | String | The source index whose data to transform. | Yes
|
||||
target_index | String | The target index the newly transformed data is added into. You can create a new index or update an existing one. | Yes
|
||||
data_selection_query | JSON | The query DSL to use to filter a subset of the source index for the transform job. See [query DSL]({{site.url}}{{site.baseurl}}/opensearch/query-dsl) for more information. | Yes
|
||||
page_size | Integer | The number of fields to transform at a time. Higher number means higher performance but requires more memory and can cause higher latency. (Default: 1) | Yes
|
||||
groups | Array | Specifies the grouping(s) to use in the transform job. Supported groups are `terms`, `histogram`, and `date_histogram`. For more information, see [Bucket Aggregations]({{site.url}}{{site.baseurl}}/opensearch/bucket-agg). | Yes if not using aggregations
|
||||
source_field | String | The field(s) to transform | Yes
|
||||
aggregations | JSON | The aggregations to use in the transform job. Supported aggregations are: `sum`, `max`, `min`, `value_count`, `avg`, `scripted_metric`, and `percentiles`. For more information, see [Metric Aggregations]({{site.url}}{{site.baseurl}}/opensearch/metric-agg). | Yes if not using groups
|
||||
|
||||
## Update a transform job
|
||||
Introduced 1.0
|
||||
{: .label .label-purple }
|
||||
|
||||
Updates a transform job if `transform_id` already exists.
|
||||
|
||||
**Sample Request**
|
||||
|
||||
```json
|
||||
PUT _plugins/_transform/<transform_id>
|
||||
|
||||
{
|
||||
"transform": {
|
||||
"enabled": true,
|
||||
"schedule": {
|
||||
"interval": {
|
||||
"period": 1,
|
||||
"unit": "Minutes",
|
||||
"start_time": 1602100553
|
||||
}
|
||||
},
|
||||
"description": "Sample transform job",
|
||||
"source_index": "sample_index",
|
||||
"target_index": "sample_target",
|
||||
"data_selection_query": {
|
||||
"match_all": {}
|
||||
},
|
||||
"page_size": 1,
|
||||
"groups": [
|
||||
{
|
||||
"terms": {
|
||||
"source_field": "customer_gender",
|
||||
"target_field": "gender"
|
||||
}
|
||||
},
|
||||
{
|
||||
"terms": {
|
||||
"source_field": "day_of_week",
|
||||
"target_field": "day"
|
||||
}
|
||||
}
|
||||
],
|
||||
"aggregations": {
|
||||
"quantity": {
|
||||
"sum": {
|
||||
"field": "total_quantity"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Sample Response**
|
||||
|
||||
```json
|
||||
{
|
||||
"_id": "sample",
|
||||
"_version": 2,
|
||||
"_seq_no": 14,
|
||||
"_primary_term": 1,
|
||||
"transform": {
|
||||
"transform_id": "sample",
|
||||
"schema_version": 7,
|
||||
"schedule": {
|
||||
"interval": {
|
||||
"start_time": 1602100553,
|
||||
"period": 1,
|
||||
"unit": "Minutes"
|
||||
}
|
||||
},
|
||||
"metadata_id": null,
|
||||
"updated_at": 1621889843874,
|
||||
"enabled": true,
|
||||
"enabled_at": 1621889843874,
|
||||
"description": "Sample transform job",
|
||||
"source_index": "sample_index",
|
||||
"data_selection_query": {
|
||||
"match_all": {
|
||||
"boost": 1.0
|
||||
}
|
||||
},
|
||||
"target_index": "sample_target",
|
||||
"roles": [],
|
||||
"page_size": 1,
|
||||
"groups": [
|
||||
{
|
||||
"terms": {
|
||||
"source_field": "customer_gender",
|
||||
"target_field": "gender"
|
||||
}
|
||||
},
|
||||
{
|
||||
"terms": {
|
||||
"source_field": "day_of_week",
|
||||
"target_field": "day"
|
||||
}
|
||||
}
|
||||
],
|
||||
"aggregations": {
|
||||
"quantity": {
|
||||
"sum": {
|
||||
"field": "total_quantity"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The `Update` operation supports the following URL parameters:
|
||||
|
||||
Parameter | Description | Required
|
||||
:---| :--- | :---
|
||||
`if_seq_no` | Only perform the transform operation if the last operation that changed the transform job has the specified sequence number. | No
|
||||
`if_primary_term` | Only perform the transform operation if the last operation that changed the transform job has the specified sequence term. | No
|
||||
|
||||
## Get a transform job's details
|
||||
Introduced 1.0
|
||||
{: .label .label-purple }
|
||||
|
||||
Returns a transform job's details.
|
||||
|
||||
**Sample Request**
|
||||
|
||||
```json
|
||||
GET _plugins/_transform/<transform_id>
|
||||
```
|
||||
|
||||
**Sample Response**
|
||||
|
||||
```json
|
||||
{
|
||||
"_id": "sample",
|
||||
"_version": 7,
|
||||
"_seq_no": 13,
|
||||
"_primary_term": 1,
|
||||
"transform": {
|
||||
"transform_id": "sample",
|
||||
"schema_version": 7,
|
||||
"schedule": {
|
||||
"interval": {
|
||||
"start_time": 1621467964243,
|
||||
"period": 1,
|
||||
"unit": "Minutes"
|
||||
}
|
||||
},
|
||||
"metadata_id": null,
|
||||
"updated_at": 1621467964243,
|
||||
"enabled": true,
|
||||
"enabled_at": 1621467964243,
|
||||
"description": "Sample transform job",
|
||||
"source_index": "sample_index",
|
||||
"data_selection_query": {
|
||||
"match_all": {
|
||||
"boost": 1.0
|
||||
}
|
||||
},
|
||||
"target_index": "sample_target",
|
||||
"roles": [],
|
||||
"page_size": 1,
|
||||
"groups": [
|
||||
{
|
||||
"terms": {
|
||||
"source_field": "customer_gender",
|
||||
"target_field": "gender"
|
||||
}
|
||||
},
|
||||
{
|
||||
"terms": {
|
||||
"source_field": "day_of_week",
|
||||
"target_field": "day"
|
||||
}
|
||||
}
|
||||
],
|
||||
"aggregations": {
|
||||
"quantity": {
|
||||
"sum": {
|
||||
"field": "total_quantity"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
You can also get details of all transform jobs by omitting `transform_id`.
|
||||
|
||||
**Sample Request**
|
||||
|
||||
```json
|
||||
GET _plugins/_transform/
|
||||
```
|
||||
|
||||
**Sample Response**
|
||||
|
||||
```json
|
||||
{
|
||||
"total_transforms": 1,
|
||||
"transforms": [
|
||||
{
|
||||
"_id": "sample",
|
||||
"_seq_no": 13,
|
||||
"_primary_term": 1,
|
||||
"transform": {
|
||||
"transform_id": "sample",
|
||||
"schema_version": 7,
|
||||
"schedule": {
|
||||
"interval": {
|
||||
"start_time": 1621467964243,
|
||||
"period": 1,
|
||||
"unit": "Minutes"
|
||||
}
|
||||
},
|
||||
"metadata_id": null,
|
||||
"updated_at": 1621467964243,
|
||||
"enabled": true,
|
||||
"enabled_at": 1621467964243,
|
||||
"description": "Sample transform job",
|
||||
"source_index": "sample_index",
|
||||
"data_selection_query": {
|
||||
"match_all": {
|
||||
"boost": 1.0
|
||||
}
|
||||
},
|
||||
"target_index": "sample_target",
|
||||
"roles": [],
|
||||
"page_size": 1,
|
||||
"groups": [
|
||||
{
|
||||
"terms": {
|
||||
"source_field": "customer_gender",
|
||||
"target_field": "gender"
|
||||
}
|
||||
},
|
||||
{
|
||||
"terms": {
|
||||
"source_field": "day_of_week",
|
||||
"target_field": "day"
|
||||
}
|
||||
}
|
||||
],
|
||||
"aggregations": {
|
||||
"quantity": {
|
||||
"sum": {
|
||||
"field": "total_quantity"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
You can specify these options as the `GET` API operation’s URL parameters to filter results:
|
||||
|
||||
Parameter | Description | Required
|
||||
:--- | :--- | :---
|
||||
from | The starting index to search from. (Default: 0) | No
|
||||
size | Specifies the amount of results to return (Default: 10) | No
|
||||
search |The search term to use to filter results. | No
|
||||
sortField | The field to sort results with. | No
|
||||
sortDirection | Specifies the direction to sort results in. Can be `ASC` or `DESC`. (Default: ASC) | No
|
||||
|
||||
For example, this request returns two results starting from the eighth index.
|
||||
|
||||
**Sample Request**
|
||||
|
||||
```json
|
||||
GET _plugins/_transform?size=2&from=8
|
||||
```
|
||||
|
||||
**Sample Response**
|
||||
|
||||
```json
|
||||
{
|
||||
"total_transforms": 18,
|
||||
"transforms": [
|
||||
{
|
||||
"_id": "sample8",
|
||||
"_seq_no": 93,
|
||||
"_primary_term": 1,
|
||||
"transform": {
|
||||
"transform_id": "sample8",
|
||||
"schema_version": 7,
|
||||
"schedule": {
|
||||
"interval": {
|
||||
"start_time": 1622063596812,
|
||||
"period": 1,
|
||||
"unit": "Minutes"
|
||||
}
|
||||
},
|
||||
"metadata_id": "y4hFAB2ZURQ2dzY7BAMxWA",
|
||||
"updated_at": 1622063657233,
|
||||
"enabled": false,
|
||||
"enabled_at": null,
|
||||
"description": "Sample transform job",
|
||||
"source_index": "sample_index3",
|
||||
"data_selection_query": {
|
||||
"match_all": {
|
||||
"boost": 1.0
|
||||
}
|
||||
},
|
||||
"target_index": "sample_target3",
|
||||
"roles": [],
|
||||
"page_size": 1,
|
||||
"groups": [
|
||||
{
|
||||
"terms": {
|
||||
"source_field": "customer_gender",
|
||||
"target_field": "gender"
|
||||
}
|
||||
},
|
||||
{
|
||||
"terms": {
|
||||
"source_field": "day_of_week",
|
||||
"target_field": "day"
|
||||
}
|
||||
}
|
||||
],
|
||||
"aggregations": {
|
||||
"quantity": {
|
||||
"sum": {
|
||||
"field": "total_quantity"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
{
|
||||
"_id": "sample9",
|
||||
"_seq_no": 98,
|
||||
"_primary_term": 1,
|
||||
"transform": {
|
||||
"transform_id": "sample9",
|
||||
"schema_version": 7,
|
||||
"schedule": {
|
||||
"interval": {
|
||||
"start_time": 1622063598065,
|
||||
"period": 1,
|
||||
"unit": "Minutes"
|
||||
}
|
||||
},
|
||||
"metadata_id": "x8tCIiYMTE3veSbIJkit5A",
|
||||
"updated_at": 1622063658388,
|
||||
"enabled": false,
|
||||
"enabled_at": null,
|
||||
"description": "Sample transform job",
|
||||
"source_index": "sample_index4",
|
||||
"data_selection_query": {
|
||||
"match_all": {
|
||||
"boost": 1.0
|
||||
}
|
||||
},
|
||||
"target_index": "sample_target4",
|
||||
"roles": [],
|
||||
"page_size": 1,
|
||||
"groups": [
|
||||
{
|
||||
"terms": {
|
||||
"source_field": "customer_gender",
|
||||
"target_field": "gender"
|
||||
}
|
||||
},
|
||||
{
|
||||
"terms": {
|
||||
"source_field": "day_of_week",
|
||||
"target_field": "day"
|
||||
}
|
||||
}
|
||||
],
|
||||
"aggregations": {
|
||||
"quantity": {
|
||||
"sum": {
|
||||
"field": "total_quantity"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Start a transform job
|
||||
Introduced 1.0
|
||||
{: .label .label-purple }
|
||||
|
||||
Transform jobs created using the API are automatically enabled, but if you ever need to enable a job, you can use the `start` API operation.
|
||||
|
||||
**Sample Request**
|
||||
|
||||
```json
|
||||
POST _plugins/_transform/<transform_id>/_start
|
||||
```
|
||||
|
||||
**Sample Response**
|
||||
|
||||
```json
|
||||
{
|
||||
"acknowledged": true
|
||||
}
|
||||
```
|
||||
|
||||
## Stop a transform job
|
||||
Introduced 1.0
|
||||
{: .label .label-purple }
|
||||
|
||||
Stops/disables a transform job.
|
||||
|
||||
**Sample Request**
|
||||
|
||||
```json
|
||||
POST _plugins/_transform/<transform_id>/_stop
|
||||
```
|
||||
|
||||
**Sample Response**
|
||||
|
||||
```json
|
||||
{
|
||||
"acknowledged": true
|
||||
}
|
||||
```
|
||||
|
||||
## Get the status of a transform job
|
||||
Introduced 1.0
|
||||
{: .label .label-purple }
|
||||
|
||||
Returns the status and metadata of a transform job.
|
||||
|
||||
**Sample Request**
|
||||
|
||||
```json
|
||||
GET _plugins/_transform/<transform_id>/_explain
|
||||
```
|
||||
|
||||
**Sample Response**
|
||||
|
||||
```json
|
||||
{
|
||||
"sample": {
|
||||
"metadata_id": "PzmjweME5xbgkenl9UpsYw",
|
||||
"transform_metadata": {
|
||||
"transform_id": "sample",
|
||||
"last_updated_at": 1621883525873,
|
||||
"status": "finished",
|
||||
"failure_reason": "null",
|
||||
"stats": {
|
||||
"pages_processed": 0,
|
||||
"documents_processed": 0,
|
||||
"documents_indexed": 0,
|
||||
"index_time_in_millis": 0,
|
||||
"search_time_in_millis": 0
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Preview a transform job's results
|
||||
Introduced 1.0
|
||||
{: .label .label-purple }
|
||||
|
||||
Returns a preview of what a transformed index would look like.
|
||||
|
||||
**Sample Request**
|
||||
|
||||
```json
|
||||
POST _plugins/_transform/_preview
|
||||
|
||||
{
|
||||
"transform": {
|
||||
"enabled": false,
|
||||
"schedule": {
|
||||
"interval": {
|
||||
"period": 1,
|
||||
"unit": "Minutes",
|
||||
"start_time": 1602100553
|
||||
}
|
||||
},
|
||||
"description": "test transform",
|
||||
"source_index": "sample_index",
|
||||
"target_index": "sample_target",
|
||||
"data_selection_query": {
|
||||
"match_all": {}
|
||||
},
|
||||
"page_size": 10,
|
||||
"groups": [
|
||||
{
|
||||
"terms": {
|
||||
"source_field": "customer_gender",
|
||||
"target_field": "gender"
|
||||
}
|
||||
},
|
||||
{
|
||||
"terms": {
|
||||
"source_field": "day_of_week",
|
||||
"target_field": "day"
|
||||
}
|
||||
}
|
||||
],
|
||||
"aggregations": {
|
||||
"quantity": {
|
||||
"sum": {
|
||||
"field": "total_quantity"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Sample Response**
|
||||
|
||||
```json
|
||||
{
|
||||
"documents" : [
|
||||
{
|
||||
"quantity" : 862.0,
|
||||
"gender" : "FEMALE",
|
||||
"day" : "Friday"
|
||||
},
|
||||
{
|
||||
"quantity" : 682.0,
|
||||
"gender" : "FEMALE",
|
||||
"day" : "Monday"
|
||||
},
|
||||
{
|
||||
"quantity" : 772.0,
|
||||
"gender" : "FEMALE",
|
||||
"day" : "Saturday"
|
||||
},
|
||||
{
|
||||
"quantity" : 669.0,
|
||||
"gender" : "FEMALE",
|
||||
"day" : "Sunday"
|
||||
},
|
||||
{
|
||||
"quantity" : 887.0,
|
||||
"gender" : "FEMALE",
|
||||
"day" : "Thursday"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Delete a transform job
|
||||
Introduced 1.0
|
||||
{: .label .label-purple }
|
||||
|
||||
Deletes a transform job. This operation does not delete the source or target indices.
|
||||
|
||||
**Sample Request**
|
||||
|
||||
```json
|
||||
DELETE _plugins/_transform/<transform_id>
|
||||
```
|
||||
|
||||
**Sample Response**
|
||||
|
||||
```json
|
||||
{
|
||||
"took": 205,
|
||||
"errors": false,
|
||||
"items": [
|
||||
{
|
||||
"delete": {
|
||||
"_index": ".opensearch-ism-config",
|
||||
"_type": "_doc",
|
||||
"_id": "sample",
|
||||
"_version": 4,
|
||||
"result": "deleted",
|
||||
"forced_refresh": true,
|
||||
"_shards": {
|
||||
"total": 2,
|
||||
"successful": 1,
|
||||
"failed": 0
|
||||
},
|
||||
"_seq_no": 6,
|
||||
"_primary_term": 1,
|
||||
"status": 200
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
@@ -1,48 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Settings
|
||||
parent: Index State Management
|
||||
nav_order: 4
|
||||
---
|
||||
|
||||
# ISM settings
|
||||
|
||||
We don't recommend changing these settings; the defaults should work well for most use cases.
|
||||
|
||||
Index State Management (ISM) stores its configuration in the `.opendistro-ism-config` index. Don't modify this index without using the [ISM API operations]({{site.url}}{{site.baseurl}}/im-plugin/ism/api/).
|
||||
|
||||
All settings are available using the OpenSearch `_cluster/settings` operation. None require a restart, and all can be marked `persistent` or `transient`.
|
||||
|
||||
Setting | Default | Description
|
||||
:--- | :--- | :---
|
||||
`plugins.index_state_management.enabled` | True | Specifies whether ISM is enabled or not.
|
||||
`plugins.index_state_management.job_interval` | 5 minutes | The interval at which the managed index jobs are run.
|
||||
`plugins.index_state_management.coordinator.sweep_period` | 10 minutes | How often the routine background sweep is run.
|
||||
`plugins.index_state_management.coordinator.backoff_millis` | 50 milliseconds | The backoff time between retries for failures in the `ManagedIndexCoordinator` (such as when we update managed indices).
|
||||
`plugins.index_state_management.coordinator.backoff_count` | 2 | The count of retries for failures in the `ManagedIndexCoordinator`.
|
||||
`plugins.index_state_management.history.enabled` | True | Specifies whether audit history is enabled or not. The logs from ISM are automatically indexed to a logs document.
|
||||
`plugins.index_state_management.history.max_docs` | 2,500,000 | The maximum number of documents before rolling over the audit history index.
|
||||
`plugins.index_state_management.history.max_age` | 24 hours | The maximum age before rolling over the audit history index.
|
||||
`plugins.index_state_management.history.rollover_check_period` | 8 hours | The time between rollover checks for the audit history index.
|
||||
`plugins.index_state_management.history.rollover_retention_period` | 30 days | How long audit history indices are kept.
|
||||
`plugins.index_state_management.allow_list` | All actions | List of actions that you can use.
|
||||
|
||||
|
||||
## Audit history indices
|
||||
|
||||
If you don't want to disable ISM audit history or shorten the retention period, you can create an [index template]({{site.url}}{{site.baseurl}}/opensearch/index-templates/) to reduce the shard count of the history indices:
|
||||
|
||||
```json
|
||||
PUT _index_template/ism_history_indices
|
||||
{
|
||||
"index_patterns": [
|
||||
".opendistro-ism-managed-index-history-*"
|
||||
],
|
||||
"template": {
|
||||
"settings": {
|
||||
"number_of_shards": 1,
|
||||
"number_of_replicas": 0
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
@@ -1,45 +0,0 @@
|
||||
|
||||
<div role="contentinfo">
|
||||
<div class="subfooter">
|
||||
<div class="container">
|
||||
<h1 class="visuallyhidden">OpenSearch Links</h1>
|
||||
|
||||
{% for column in site.data.footer.columns %}
|
||||
<div class="col {% if forloop.index > 2 %}last-child{% endif %}">
|
||||
|
||||
<h2>{{ column.title }}</h2>
|
||||
<ul>
|
||||
{% for link in column.links %}
|
||||
<li><a href="{{ link.url }}">{{ link.title}}</a></li>
|
||||
{% endfor %}
|
||||
</ul>
|
||||
</div>
|
||||
{% endfor %}
|
||||
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="footer">
|
||||
<div class="container">
|
||||
|
||||
<a href="{{ '/' | relative_url }}"><svg viewBox="0 0 64 64" fill="currentColor" xmlns="http://www.w3.org/2000/svg">
|
||||
<path d="M61.7374 23.5C60.4878 23.5 59.4748 24.513 59.4748 25.7626C59.4748 44.3813 44.3813 59.4748 25.7626 59.4748C24.513 59.4748 23.5 60.4878 23.5 61.7374C23.5 62.987 24.513 64 25.7626 64C46.8805 64 64 46.8805 64 25.7626C64 24.513 62.987 23.5 61.7374 23.5Z" fill="currentColor" />
|
||||
<path d="M48.0814 38C50.2572 34.4505 52.3615 29.7178 51.9475 23.0921C51.0899 9.36725 38.6589 -1.04463 26.9206 0.0837327C22.3253 0.525465 17.6068 4.2712 18.026 10.9805C18.2082 13.8961 19.6352 15.6169 21.9544 16.9399C24.1618 18.1992 26.9978 18.9969 30.2128 19.9011C34.0962 20.9934 38.6009 22.2203 42.063 24.7717C46.2125 27.8295 49.0491 31.3743 48.0814 38Z" fill="currentColor" />
|
||||
<path d="M3.91861 14C1.74276 17.5495 -0.361506 22.2822 0.0524931 28.9079C0.910072 42.6327 13.3411 53.0446 25.0794 51.9163C29.6747 51.4745 34.3932 47.7288 33.974 41.0195C33.7918 38.1039 32.3647 36.3831 30.0456 35.0601C27.8382 33.8008 25.0022 33.0031 21.7872 32.0989C17.9038 31.0066 13.3991 29.7797 9.93694 27.2283C5.78746 24.1704 2.95092 20.6257 3.91861 14Z" fill="currentColor" />
|
||||
</svg></a>
|
||||
|
||||
<p class="copyright">© {{ 'now' | date: "%Y" }}
|
||||
<a href="https://aws.amazon.com/"> Amazon Web Services</a> and individual contributors. OpenSearch is a
|
||||
<a href="/trademark-usage.html">registered trademark</a> of Amazon Web Services.</a> <br /><br />
|
||||
|
||||
© 2005-2021
|
||||
<a href="https://www.djangoproject.com/foundation/"> Django Software
|
||||
Foundation</a> and individual contributors. Django is a
|
||||
<a href="https://www.djangoproject.com/trademarks/">registered
|
||||
trademark</a> of the Django Software Foundation.<br />
|
||||
This website was forked from the BSD-licensed <a href="https://github.com/django/djangoproject.com/">djangoproject.com</a> originally designed by <a href="https://www.threespot.com">Threespot</a> <span class="ampersand">&</span> <a href="http://andrevv.com/">andrevv</a>.<br /> We ♡ Django and the Django community. If you need a <a href="https://www.djangoproject.com/">high-level Python framework</a>, check it out.
|
||||
</p>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
</div>
|
||||
@@ -6,9 +6,3 @@
|
||||
<script src="https://polyfill.io/v3/polyfill.min.js?features=es6"></script>
|
||||
<script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3.0.1/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 %}
|
||||
|
||||
@@ -1,41 +0,0 @@
|
||||
{% assign url_full = site.baseurl | append: page.url %}
|
||||
{% assign url_parts = url_full | split: "/" %}
|
||||
{%if page.alert %}
|
||||
<div role="banner" class="banner-alert">
|
||||
<div class="container">
|
||||
{{page.alert | markdownify}}
|
||||
</div>
|
||||
</div>
|
||||
{%endif%}
|
||||
{%if site.data.alert.message %}
|
||||
<div role="banner" class="banner-alert">
|
||||
<div class="container">
|
||||
{{site.data.alert.message | markdownify}}
|
||||
</div>
|
||||
</div>
|
||||
{%endif%}
|
||||
<div role="banner" id="top">
|
||||
<div class="container">
|
||||
<a class="logo" href="/">
|
||||
OpenSearch
|
||||
<svg viewBox="0 0 372 72" fill="none" xmlns="http://www.w3.org/2000/svg">
|
||||
<path d="M61.7374 26.5C60.4878 26.5 59.4748 27.513 59.4748 28.7626C59.4748 47.3814 44.3814 62.4748 25.7626 62.4748C24.513 62.4748 23.5 63.4878 23.5 64.7374C23.5 65.987 24.513 67 25.7626 67C46.8805 67 64 49.8805 64 28.7626C64 27.513 62.987 26.5 61.7374 26.5Z" fill="#00A3E0"/>
|
||||
<path d="M48.0814 41C50.2572 37.4505 52.3615 32.7178 51.9475 26.0921C51.0899 12.3673 38.6589 1.95537 26.9206 3.08373C22.3253 3.52547 17.6068 7.2712 18.026 13.9805C18.2082 16.8961 19.6352 18.6169 21.9544 19.9399C24.1618 21.1992 26.9978 21.9969 30.2128 22.9011C34.0962 23.9934 38.6009 25.2203 42.0631 27.7717C46.2125 30.8296 49.0491 34.3743 48.0814 41Z" fill="#B9D9EB"/>
|
||||
<path d="M3.91861 17C1.74276 20.5495 -0.361506 25.2822 0.0524931 31.9079C0.910072 45.6327 13.3411 56.0446 25.0794 54.9163C29.6747 54.4745 34.3932 50.7288 33.974 44.0195C33.7918 41.1039 32.3647 39.3831 30.0456 38.0601C27.8382 36.8008 25.0022 36.0031 21.7872 35.0989C17.9038 34.0066 13.3991 32.7797 9.93695 30.2283C5.78747 27.1704 2.95092 23.6257 3.91861 17Z" fill="#00A3E0"/>
|
||||
<path fill-rule="evenodd" clip-rule="evenodd" d="M362.5 31V54H371.5V29C371.5 24.3927 370.6 20.9121 368.799 18.5511C366.998 16.1672 364.282 15 360.75 15C356.918 15 353.847 17.2408 352 21H351.5C351.636 19.0591 351.76 17.9472 351.85 17.1353C351.943 16.298 352 15.7797 352 15V0.5H343V54H352.5V35.5C352.5 31.3511 352.639 28.2815 353.493 26.081C354.347 23.8575 355.836 22.7458 357.96 22.7458C360.799 22.7458 362.5 25.3841 362.5 31ZM231.852 51.2289C234.284 48.7148 235.5 45.0936 235.5 40.3653C235.5 37.4129 234.834 34.7835 233.501 32.477C232.191 30.1705 229.865 27.9102 226.521 25.6959C224.042 24.0814 222.3 22.6398 221.294 21.3713C220.312 20.1027 219.821 18.615 219.821 16.9082C219.821 15.1783 220.23 13.8175 221.049 12.8257C221.891 11.8108 223.083 11.3034 224.627 11.3034C226.03 11.3034 227.339 11.5571 228.555 12.0645C229.794 12.572 230.975 13.1486 232.098 13.7944L235.254 6.25216C231.63 4.08405 227.854 3 223.925 3C219.809 3 216.524 4.26857 214.069 6.80572C211.637 9.34287 210.421 12.7796 210.421 17.1158C210.421 19.3761 210.725 21.3597 211.333 23.0665C211.964 24.7733 212.841 26.3187 213.964 27.7026C215.109 29.0634 216.781 30.4935 218.979 31.9927C221.505 33.6995 223.317 35.2564 224.416 36.6633C225.515 38.0472 226.065 39.5811 226.065 41.2648C226.065 42.9716 225.597 44.3209 224.662 45.3127C223.75 46.3045 222.382 46.8004 220.558 46.8004C217.354 46.8004 213.835 45.5664 210 43.0985V52.4052C213.133 54.1351 216.933 55 221.4 55C225.959 55 229.444 53.743 231.852 51.2289ZM241.674 49.8745C244.48 53.2915 248.306 55 253.152 55C257.303 55 260.862 54.1111 263.83 52.3333V44.7489C260.677 46.619 257.593 47.5541 254.578 47.5541C252.213 47.5541 250.358 46.7229 249.013 45.0606C247.668 43.3752 247.07 40.9401 247 37.5H265.5V32.4545C265.5 26.9365 264.283 22.6537 261.848 19.6061C259.413 16.5354 256.086 15 251.865 15C247.343 15 243.819 16.7893 241.291 20.368C238.764 23.9466 237.5 28.9221 237.5 35.2944C237.5 41.5743 238.891 46.4343 241.674 49.8745ZM248.526 24.2121C249.384 22.8038 250.474 22.0996 251.796 22.0996C253.21 22.0996 254.323 22.8268 255.135 24.2814C255.946 25.7359 256.454 28.1833 256.5 31H247C247.139 28.0678 247.668 25.5974 248.526 24.2121ZM288 54L286.5 49H286C284.622 51.2587 283.295 52.868 281.824 53.7208C280.352 54.5736 278.494 55 276.252 55C273.378 55 271.112 53.9398 269.453 51.8194C267.818 49.6989 267 46.7488 267 42.9689C267 38.9124 268.121 35.9046 270.364 33.9455C272.63 31.9634 276.006 30.8686 280.492 30.6612L285.678 30.4538V27.688C285.678 24.0925 284.101 22.2947 280.947 22.2947C278.611 22.2947 275.924 23.1936 272.887 24.9914L269.663 18.6301C273.541 16.21 277.694 15 282.25 15C286.385 15 289.592 16.1755 291.741 18.5264C293.914 20.8542 295 24.1616 295 28.4486V54H288ZM280.071 47.809C281.777 47.809 283.132 47.0599 284.136 45.5618C285.164 44.0406 285.678 42.0239 285.678 39.5117V36.2619L282.805 36.4002C280.679 36.5154 279.113 37.1147 278.109 38.1979C277.128 39.2812 276.637 40.8946 276.637 43.038C276.637 46.2187 277.782 47.809 280.071 47.809ZM318 15.75C316.93 15.405 315.337 15 314.222 15C312.651 15 311.273 15.5174 310.089 16.5523C308.905 17.5872 308.002 18.5853 307 21H306.5L305 16H298V54H307.463V34C307.463 30.6424 307.676 28.4763 308.86 26.7285C310.044 24.9577 311.74 24.0723 313.948 24.0723C314.973 24.0723 315.863 24.27 316.5 24.5L318 15.75ZM332 55C327.443 55 323.954 53.478 321.573 50.1302C319.191 46.7824 318 41.8647 318 35.377C318 28.5891 319.122 23.5213 321.366 20.1735C323.634 16.8257 327.017 15 331.735 15C333.154 15 334.752 15.3596 336.309 15.7752C337.866 16.1908 339.763 16.715 341 17.5L337.889 24.7449C335.989 23.6136 334.305 23.048 332.84 23.048C330.893 23.048 329.485 24.0754 328.614 26.1302C327.767 28.162 327.344 31.2211 327.344 35.3077C327.344 39.3019 327.767 42.2918 328.614 44.2774C329.462 46.2399 330.847 47.2211 332.771 47.2211C335.061 47.2211 337.454 46.413 339.95 44.7969V52.9008C337.546 54.4015 334.908 55 332 55Z" fill="#B9D9EB"/>
|
||||
<path fill-rule="evenodd" clip-rule="evenodd" d="M107.777 48.2625C110.926 43.7708 112.5 37.3442 112.5 28.9827C112.5 20.6213 110.937 14.2062 107.812 9.73754C104.686 5.24585 100.194 3 94.3368 3C88.4098 3 83.8719 5.23433 80.7231 9.70299C77.5744 14.1486 76 20.5522 76 28.9136C76 37.3442 77.5744 43.8053 80.7231 48.297C83.8719 52.7657 88.3866 55 94.2674 55C100.125 55 104.628 52.7542 107.777 48.2625ZM87.8425 42.1468C86.3839 39.1293 85.6546 34.7413 85.6546 28.9827C85.6546 23.2011 86.3839 18.8131 87.8425 15.8186C89.3011 12.8011 91.4659 11.2924 94.3368 11.2924C99.986 11.2924 102.811 17.1891 102.811 28.9827C102.811 40.7763 99.9629 46.6731 94.2674 46.6731C91.4428 46.6731 89.3011 45.1643 87.8425 42.1468ZM128.186 53.9979C129.469 54.7387 130.85 55 132.5 55C136.03 55 138.9 53.3265 140.94 49.7612C142.98 46.196 144 41.2764 144 35.0025C144 28.6359 143.014 23.7164 141.043 20.2437C139.072 16.7479 136.345 15 132.861 15C129.24 15 126.402 17.1569 124.5 21H124L122.5 16H115.5V71.5H124.5V55C124.5 54.3518 124.367 52.1485 124 49H124.5C125.25 51.25 126.925 53.2339 128.186 53.9979ZM125.882 25.3832C126.685 23.6932 127.979 22.8482 129.767 22.8482C131.44 22.8482 132.666 23.8437 133.446 25.8347C134.248 27.8257 134.649 30.8353 134.649 34.8636C134.649 43.059 133.045 47.1567 129.836 47.1567C127.979 47.1567 126.65 46.1844 125.848 44.2397C125.046 42.295 124.645 39.1928 124.645 34.933V33.7176C124.691 29.8282 125.103 27.0501 125.882 25.3832ZM161.652 55C156.806 55 152.98 53.2915 150.174 49.8745C147.391 46.4343 146 41.5743 146 35.2944C146 28.9221 147.264 23.9466 149.791 20.368C152.319 16.7893 155.843 15 160.365 15C164.585 15 167.913 16.5354 170.348 19.6061C172.783 22.6537 174 26.9365 174 32.4545V37.5H155.5C155.57 40.9401 156.168 43.3752 157.513 45.0606C158.858 46.7229 160.713 47.5541 163.078 47.5541C166.093 47.5541 169.177 46.619 172.33 44.7489V52.3333C169.362 54.1111 165.803 55 161.652 55ZM160.296 22.0996C158.974 22.0996 157.884 22.8038 157.026 24.2121C156.168 25.5974 155.639 28.0678 155.5 31H165C164.954 28.1833 164.446 25.7359 163.635 24.2814C162.823 22.8268 161.71 22.0996 160.296 22.0996ZM196.5 31V54H205.5V29.1991C205.5 24.5589 204.623 21.0323 202.868 18.6194C201.137 16.2065 198.516 15 195.007 15C192.93 15 191.117 15.5104 189.57 16.5313C188.024 17.5289 186.831 19.2135 186 21H185.5L184.25 16H177V54H186.5V35.75C186.5 31.0402 186.673 27.8302 187.597 25.8582C188.52 23.8628 189.974 22.8652 191.96 22.8652C193.46 22.8652 194.546 23.5844 195.215 25.0229C195.885 26.4614 196.5 28.1927 196.5 31Z" fill="#00A3E0"/>
|
||||
</svg>
|
||||
</a>
|
||||
|
||||
<div class="menu-button"><i class="icon icon-reorder"></i><span>Menu</span></div>
|
||||
<div class="nav-menu-on" role="navigation">
|
||||
<ul class="small-nav">
|
||||
{%- include nav_item.html text="News" href="/blog" url_full="/blog/" url_fragment="blog" -%}
|
||||
{%- include nav_item.html text="Source" href="/source.html" url_full="/source.html" url_fragment="source" -%}
|
||||
{%- include nav_item.html text="Documentation" href="/docs" url_full="/docs/" url_fragment="docs" -%}
|
||||
{%- include nav_item.html text="Events" href="/events" url_full="/events/" url_fragment="events" -%}
|
||||
{%- include nav_item.html text="Get Started" href="/downloads.html" url_full="/downloads.html" url_fragment="downloads" -%}
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
+5
-27
@@ -60,7 +60,7 @@
|
||||
{%- for node in pages_list -%}
|
||||
{%- if node.parent == nil -%}
|
||||
{%- unless node.nav_exclude -%}
|
||||
<li class="nav-list-item{% if page.collection == include.key and page.url == node.url or page.parent == node.title or page.grand_parent == node.title %} active{% endif %}">
|
||||
<li class="nav-list-item{% if page.url == node.url or page.parent == node.title or page.grand_parent == node.title %} active{% endif %}">
|
||||
{%- if node.has_children -%}
|
||||
<a href="#" class="nav-list-expander"><svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg></a>
|
||||
{%- endif -%}
|
||||
@@ -90,36 +90,14 @@
|
||||
</li>
|
||||
{%- endunless -%}
|
||||
{%- endfor -%}
|
||||
|
||||
</ul>
|
||||
{%- endif -%}
|
||||
</li>
|
||||
{%- endunless -%}
|
||||
{%- endif -%}
|
||||
{%- endfor -%}
|
||||
<li class="nav-list-item">
|
||||
<a href="https://opensearch.org/docs/javadocs/" target="_blank" class="nav-list-link">Javadoc <svg class="external-arrow" width="16" height="16" fill="#002A3A"><use xlink:href="#external-arrow"></use></svg></a>
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
{%- if page.collection == include.key -%}
|
||||
|
||||
{%- for node in pages_list -%}
|
||||
{%- if node.parent == nil -%}
|
||||
{%- if page.parent == node.title or page.grand_parent == node.title -%}
|
||||
{%- assign first_level_url = node.url | absolute_url -%}
|
||||
{%- endif -%}
|
||||
{%- if node.has_children -%}
|
||||
{%- assign children_list = pages_list | where: "parent", node.title -%}
|
||||
{%- for child in children_list -%}
|
||||
{%- if child.has_children -%}
|
||||
{%- if page.url == child.url or page.parent == child.title and page.grand_parent == child.parent -%}
|
||||
{%- assign second_level_url = child.url | absolute_url -%}
|
||||
{%- endif -%}
|
||||
{%- endif -%}
|
||||
{%- endfor -%}
|
||||
{%- endif -%}
|
||||
{%- endif -%}
|
||||
{%- endfor -%}
|
||||
|
||||
{% if page.has_children == true and page.has_toc != false %}
|
||||
{%- assign toc_list = pages_list | where: "parent", page.title | where: "grand_parent", page.parent -%}
|
||||
{%- endif -%}
|
||||
|
||||
{%- endif -%}
|
||||
|
||||
@@ -1,7 +0,0 @@
|
||||
<li>
|
||||
{% if url_full == include.url_full %} {{ include.text }} {% else %}
|
||||
<a href="{{ include.href }}" {% if url_parts[1] == {{include.url_fragment}} %} class="in-category" {% endif %}>
|
||||
{{ include.text }}
|
||||
</a>
|
||||
{% endif %}
|
||||
</li>
|
||||
+156
-154
@@ -38,74 +38,48 @@ layout: table_wrappers
|
||||
<path d="M13 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V9z"></path><polyline points="13 2 13 9 20 9"></polyline>
|
||||
</svg>
|
||||
</symbol>
|
||||
<symbol id="svg-grid" viewBox="0 0 24 24">
|
||||
<title>Documentation Menu</title>
|
||||
<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1" stroke-linecap="round" stroke-linejoin="round" class="feather feather-grid">
|
||||
<rect x="3" y="3" width="7" height="7"></rect><rect x="14" y="3" width="7" height="7"></rect><rect x="14" y="14" width="7" height="7"></rect><rect x="3" y="14" width="7" height="7"></rect>
|
||||
<symbol id="external-arrow" viewBox="0 0 16 16">
|
||||
<title>External</title>
|
||||
<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="currentColor" viewBox="0 0 16 16">
|
||||
<path fill-rule="evenodd" d="M8.636 3.5a.5.5 0 0 0-.5-.5H1.5A1.5 1.5 0 0 0 0 4.5v10A1.5 1.5 0 0 0 1.5 16h10a1.5 1.5 0 0 0 1.5-1.5V7.864a.5.5 0 0 0-1 0V14.5a.5.5 0 0 1-.5.5h-10a.5.5 0 0 1-.5-.5v-10a.5.5 0 0 1 .5-.5h6.636a.5.5 0 0 0 .5-.5z"/>
|
||||
<path fill-rule="evenodd" d="M16 .5a.5.5 0 0 0-.5-.5h-5a.5.5 0 0 0 0 1h3.793L6.146 9.146a.5.5 0 1 0 .708.708L15 1.707V5.5a.5.5 0 0 0 1 0v-5z"/>
|
||||
</svg>
|
||||
</symbol>
|
||||
</svg>
|
||||
|
||||
{% include header.html %}
|
||||
|
||||
<main>
|
||||
<div id="main-header"></div>
|
||||
<div class="side-bar">
|
||||
<div class="site-header">
|
||||
<a href="#" id="menu-button" class="site-button">
|
||||
Documentation <svg viewBox="0 0 24 24" class="icon"><use xlink:href="#svg-grid"></use></svg>
|
||||
</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"
|
||||
| where_exp:"item", "item.nav_exclude != true"
|
||||
| size %}
|
||||
{% if pages_top_size > 0 %}
|
||||
{% include nav.html pages=site.html_pages key=nil %}
|
||||
{% endif %}
|
||||
{% if site.just_the_docs.collections %}
|
||||
{% assign collections_size = site.just_the_docs.collections | size %}
|
||||
{% for collection_entry in site.just_the_docs.collections %}
|
||||
{% assign collection_key = collection_entry[0] %}
|
||||
{% assign collection_value = collection_entry[1] %}
|
||||
{% assign collection = site[collection_key] %}
|
||||
{% if collection_value.nav_exclude != true %}
|
||||
{% if collections_size > 1 or pages_top_size > 0 %}
|
||||
{% if collection_value.nav_fold == true %}
|
||||
<ul class="nav-list nav-category-list">
|
||||
<li class="nav-list-item{% if page.collection == collection_key %} active{% endif %}">
|
||||
{%- if collection.size > 0 -%}
|
||||
<a href="#" class="nav-list-expander"><svg viewBox="0 0 24 24"><use xlink:href="#svg-arrow-right"></use></svg></a>
|
||||
{%- endif -%}
|
||||
<div class="nav-category">{{ collection_value.name }}</div>
|
||||
{% include nav.html pages=collection key=collection_key %}
|
||||
</li>
|
||||
</ul>
|
||||
{% else %}
|
||||
<div class="nav-category">{{ collection_value.name }}</div>
|
||||
{% include nav.html pages=collection key=collection_key %}
|
||||
{% endif %}
|
||||
{% else %}
|
||||
{% include nav.html pages=collection key=collection_key %}
|
||||
{% endif %}
|
||||
{% endif %}
|
||||
{% endfor %}
|
||||
{% endif %}
|
||||
</nav>
|
||||
<div class="site-footer">
|
||||
<p class="text-small text-grey-dk-100">See a problem? Submit <a href="https://github.com/opensearch-project/documentation-website/issues">issues</a> or <a href="https://github.com/opensearch-project/documentation-website/edit/main/{{ page.path }}">edit this page</a> on <a href="https://github.com/opensearch-project/documentation-website/">GitHub</a>.</p>
|
||||
</div>
|
||||
<div class="side-bar">
|
||||
<div class="site-header">
|
||||
<a href="{{ '/' | absolute_url }}" class="site-title lh-tight">{% include title.html %}</a>
|
||||
<a href="#" id="menu-button" class="site-button">
|
||||
<svg viewBox="0 0 24 24" class="icon"><use xlink:href="#svg-menu"></use></svg>
|
||||
</a>
|
||||
</div>
|
||||
<div class="copy-banner">
|
||||
<div class="container">
|
||||
<h1><a href="#">Documentation</a></h1>
|
||||
{% if site.search_enabled != false %}
|
||||
<nav role="navigation" aria-label="Main" id="site-nav" class="site-nav">
|
||||
{% if site.just_the_docs.collections %}
|
||||
{% assign collections_size = site.just_the_docs.collections | size %}
|
||||
{% for collection_entry in site.just_the_docs.collections %}
|
||||
{% assign collection_key = collection_entry[0] %}
|
||||
{% assign collection_value = collection_entry[1] %}
|
||||
{% assign collection = site[collection_key] %}
|
||||
{% if collection_value.nav_exclude != true %}
|
||||
{% if collections_size > 1 %}
|
||||
<div class="nav-category">{{ collection_value.name }}</div>
|
||||
{% endif %}
|
||||
{% include nav.html pages=collection %}
|
||||
{% endif %}
|
||||
{% endfor %}
|
||||
{% else %}
|
||||
{% include nav.html pages=site.html_pages %}
|
||||
{% endif %}
|
||||
</nav>
|
||||
<footer class="site-footer">
|
||||
<p class="text-small text-grey-dk-100">See a problem? Submit <a href="https://github.com/opensearch-project/documentation-website/issues">issues</a> or <a href="https://github.com/opensearch-project/documentation-website/edit/main/{{ page.path }}">edit this page</a> on GitHub.</p>
|
||||
<p class="text-small text-grey-dk-100 mb-0">© Amazon Web Services, Inc. or its affiliates. All rights reserved.</p>
|
||||
</footer>
|
||||
</div>
|
||||
<div class="main" id="top">
|
||||
<div id="main-header" class="main-header">
|
||||
{% if site.search_enabled != false %}
|
||||
<div class="search">
|
||||
<div class="search-input-wrap">
|
||||
<input type="text" id="search-input" class="search-input" tabindex="0" placeholder="Search..." aria-label="Search {{ site.title }}" autocomplete="off">
|
||||
@@ -113,105 +87,133 @@ layout: table_wrappers
|
||||
</div>
|
||||
<div id="search-results" class="search-results"></div>
|
||||
</div>
|
||||
{% endif %}
|
||||
</div>
|
||||
<div class="search-overlay"></div>
|
||||
</div>
|
||||
<div class="main" id="top">
|
||||
<div id="main-content-wrap" class="main-content-wrap">
|
||||
{% unless page.url == "/" %}
|
||||
{% if page.parent %}
|
||||
<nav aria-label="Breadcrumb" class="breadcrumb-nav">
|
||||
<ol class="breadcrumb-nav-list">
|
||||
{% if page.grand_parent %}
|
||||
<li class="breadcrumb-nav-list-item"><a href="{{ first_level_url }}">{{ page.grand_parent }}</a></li>
|
||||
<li class="breadcrumb-nav-list-item"><a href="{{ second_level_url }}">{{ page.parent }}</a></li>
|
||||
{% else %}
|
||||
<li class="breadcrumb-nav-list-item"><a href="{{ first_level_url }}">{{ page.parent }}</a></li>
|
||||
{% endif %}
|
||||
<li class="breadcrumb-nav-list-item"><span>{{ page.title }}</span></li>
|
||||
</ol>
|
||||
</nav>
|
||||
{% endif %}
|
||||
{% endunless %}
|
||||
<div id="main-content" class="main-content" role="main">
|
||||
{% if site.heading_anchors != false %}
|
||||
{% include vendor/anchor_headings.html html=content beforeHeading="true" anchorBody="<svg viewBox=\"0 0 16 16\" aria-hidden=\"true\"><use xlink:href=\"#svg-link\"></use></svg>" anchorClass="anchor-heading" anchorAttrs="aria-labelledby=\"%html_id%\"" %}
|
||||
{% else %}
|
||||
{{ content }}
|
||||
{% endif %}
|
||||
|
||||
{% if page.has_children == true and page.has_toc != false %}
|
||||
<hr>
|
||||
<h2 class="text-delta">Table of contents</h2>
|
||||
<ul>
|
||||
{% for child in toc_list %}
|
||||
<li>
|
||||
<a href="{{ child.url | absolute_url }}">{{ child.title }}</a>{% if child.summary %} - {{ child.summary }}{% endif %}
|
||||
</li>
|
||||
{% endfor %}
|
||||
</ul>
|
||||
{% endif %}
|
||||
|
||||
{% capture footer_custom %}
|
||||
{%- include footer_custom.html -%}
|
||||
{% endcapture %}
|
||||
{% if footer_custom != "" or site.last_edit_timestamp or site.gh_edit_link %}
|
||||
<hr>
|
||||
<footer>
|
||||
{% if site.back_to_top %}
|
||||
<p><a href="#top" id="back-to-top">{{ site.back_to_top_text }}</a></p>
|
||||
{% endif %}
|
||||
|
||||
{{ footer_custom }}
|
||||
|
||||
{% if site.last_edit_timestamp or site.gh_edit_link %}
|
||||
<div class="d-flex mt-2">
|
||||
{% if site.last_edit_timestamp and site.last_edit_time_format and page.last_modified_date %}
|
||||
<p class="text-small text-grey-dk-000 mb-0 mr-2">
|
||||
Page last modified: <span class="d-inline-block">{{ page.last_modified_date | date: site.last_edit_time_format }}</span>.
|
||||
</p>
|
||||
{% endif %}
|
||||
{% include header_custom.html %}
|
||||
{% if site.aux_links %}
|
||||
<nav aria-label="Auxiliary" class="aux-nav">
|
||||
<ul class="aux-nav-list">
|
||||
{% for link in site.aux_links %}
|
||||
<li class="aux-nav-list-item">
|
||||
<a href="{{ link.last }}" class="site-button"
|
||||
{% if site.aux_links_new_tab %}
|
||||
target="_blank" rel="noopener noreferrer"
|
||||
{% endif %}
|
||||
{% if
|
||||
site.gh_edit_link and
|
||||
site.gh_edit_link_text and
|
||||
site.gh_edit_repository and
|
||||
site.gh_edit_branch and
|
||||
site.gh_edit_view_mode
|
||||
%}
|
||||
<p class="text-small text-grey-dk-000 mb-0">
|
||||
<a href="{{ site.gh_edit_repository }}/{{ site.gh_edit_view_mode }}/{{ site.gh_edit_branch }}{% if site.gh_edit_source %}/{{ site.gh_edit_source }}{% endif %}/{{ page.path }}" id="edit-this-page">{{ site.gh_edit_link_text }}</a>
|
||||
</p>
|
||||
{% endif %}
|
||||
</div>
|
||||
{% endif %}
|
||||
</footer>
|
||||
{% endif %}
|
||||
|
||||
</div>
|
||||
</div>
|
||||
<div class="toc-wrap">
|
||||
<div class="toc">
|
||||
{% include toc.html html=content h_min=2 h_max=2 class="toc-list" item_class="toc-item" sanitize=true %}
|
||||
</div>
|
||||
</div>
|
||||
{% if site.search_enabled != false %}
|
||||
{% if site.search.button %}
|
||||
<a href="#" id="search-button" class="search-button">
|
||||
<svg viewBox="0 0 24 24" class="icon"><use xlink:href="#svg-search"></use></svg>
|
||||
</a>
|
||||
{% endif %}
|
||||
>
|
||||
{{ link.first }}
|
||||
</a>
|
||||
</li>
|
||||
{% endfor %}
|
||||
</ul>
|
||||
</nav>
|
||||
{% endif %}
|
||||
</div>
|
||||
</main>
|
||||
<div id="main-content-wrap" class="main-content-wrap">
|
||||
{% unless page.url == "/" %}
|
||||
{% if page.parent %}
|
||||
{%- for node in pages_list -%}
|
||||
{%- if node.parent == nil -%}
|
||||
{%- if page.parent == node.title or page.grand_parent == node.title -%}
|
||||
{%- assign first_level_url = node.url | absolute_url -%}
|
||||
{%- endif -%}
|
||||
{%- if node.has_children -%}
|
||||
{%- assign children_list = pages_list | where: "parent", node.title -%}
|
||||
{%- for child in children_list -%}
|
||||
{%- if page.url == child.url or page.parent == child.title -%}
|
||||
{%- assign second_level_url = child.url | absolute_url -%}
|
||||
{%- endif -%}
|
||||
{%- endfor -%}
|
||||
{%- endif -%}
|
||||
{%- endif -%}
|
||||
{%- endfor -%}
|
||||
<nav aria-label="Breadcrumb" class="breadcrumb-nav">
|
||||
<ol class="breadcrumb-nav-list">
|
||||
{% if page.grand_parent %}
|
||||
<li class="breadcrumb-nav-list-item"><a href="{{ first_level_url }}">{{ page.grand_parent }}</a></li>
|
||||
<li class="breadcrumb-nav-list-item"><a href="{{ second_level_url }}">{{ page.parent }}</a></li>
|
||||
{% else %}
|
||||
<li class="breadcrumb-nav-list-item"><a href="{{ first_level_url }}">{{ page.parent }}</a></li>
|
||||
{% endif %}
|
||||
<li class="breadcrumb-nav-list-item"><span>{{ page.title }}</span></li>
|
||||
</ol>
|
||||
</nav>
|
||||
{% endif %}
|
||||
{% endunless %}
|
||||
<div id="main-content" class="main-content" role="main">
|
||||
{% if site.heading_anchors != false %}
|
||||
{% include vendor/anchor_headings.html html=content beforeHeading="true" anchorBody="<svg viewBox=\"0 0 16 16\" aria-hidden=\"true\"><use xlink:href=\"#svg-link\"></use></svg>" anchorClass="anchor-heading" anchorAttrs="aria-labelledby=\"%html_id%\"" %}
|
||||
{% else %}
|
||||
<p class="warning" style="margin-top: 0">Like OpenSearch itself, this documentation is a beta. It has content gaps and might contain bugs.</p>
|
||||
{{ content }}
|
||||
{% endif %}
|
||||
|
||||
{% include footer.html %}
|
||||
{% if page.has_children == true and page.has_toc != false %}
|
||||
<hr>
|
||||
<h2 class="text-delta">Table of contents</h2>
|
||||
<ul>
|
||||
{%- assign children_list = pages_list | where: "parent", page.title | where: "grand_parent", page.parent -%}
|
||||
{% for child in children_list %}
|
||||
<li>
|
||||
<a href="{{ child.url | absolute_url }}">{{ child.title }}</a>{% if child.summary %} - {{ child.summary }}{% endif %}
|
||||
</li>
|
||||
{% endfor %}
|
||||
</ul>
|
||||
{% endif %}
|
||||
|
||||
{% capture footer_custom %}
|
||||
{%- include footer_custom.html -%}
|
||||
{% endcapture %}
|
||||
{% if footer_custom != "" or site.last_edit_timestamp or site.gh_edit_link %}
|
||||
<hr>
|
||||
<footer>
|
||||
{% if site.back_to_top %}
|
||||
<p><a href="#top" id="back-to-top">{{ site.back_to_top_text }}</a></p>
|
||||
{% endif %}
|
||||
|
||||
{{ footer_custom }}
|
||||
|
||||
{% if site.last_edit_timestamp or site.gh_edit_link %}
|
||||
<div class="d-flex mt-2">
|
||||
{% if site.last_edit_timestamp and site.last_edit_time_format and page.last_modified_date %}
|
||||
<p class="text-small text-grey-dk-000 mb-0 mr-2">
|
||||
Page last modified: <span class="d-inline-block">{{ page.last_modified_date | date: site.last_edit_time_format }}</span>.
|
||||
</p>
|
||||
{% endif %}
|
||||
{% if
|
||||
site.gh_edit_link and
|
||||
site.gh_edit_link_text and
|
||||
site.gh_edit_repository and
|
||||
site.gh_edit_branch and
|
||||
site.gh_edit_view_mode
|
||||
%}
|
||||
<p class="text-small text-grey-dk-000 mb-0">
|
||||
<a href="{{ site.gh_edit_repository }}/{{ site.gh_edit_view_mode }}/{{ site.gh_edit_branch }}{% if site.gh_edit_source %}/{{ site.gh_edit_source }}{% endif %}/{{ page.path }}" id="edit-this-page">{{ site.gh_edit_link_text }}</a>
|
||||
</p>
|
||||
{% endif %}
|
||||
</div>
|
||||
{% endif %}
|
||||
</footer>
|
||||
{% endif %}
|
||||
|
||||
</div>
|
||||
</div>
|
||||
<div class="toc">
|
||||
{% include toc.html html=content h_min=2 h_max=2 class="toc-list" item_class="toc-item" sanitize=true %}
|
||||
</div>
|
||||
{% if site.search_enabled != false %}
|
||||
{% if site.search.button %}
|
||||
<a href="#" id="search-button" class="search-button">
|
||||
<svg viewBox="0 0 24 24" class="icon"><use xlink:href="#svg-search"></use></svg>
|
||||
</a>
|
||||
{% endif %}
|
||||
|
||||
<div class="search-overlay"></div>
|
||||
{% endif %}
|
||||
</div>
|
||||
|
||||
{% if site.anchor_links != nil %}
|
||||
<script>
|
||||
anchors.add().remove('.subfooter h1, .subfooter h2');
|
||||
anchors.add();
|
||||
</script>
|
||||
{% endif %}
|
||||
<script src="{{ '/assets/js/header-nav.js' | relative_url }}"></script>
|
||||
</body>
|
||||
</html>
|
||||
|
||||
@@ -1,42 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Settings
|
||||
parent: Anomaly detection
|
||||
nav_order: 4
|
||||
---
|
||||
|
||||
# Settings
|
||||
|
||||
The anomaly detection plugin adds several settings to the standard OpenSearch cluster settings.
|
||||
The settings are dynamic, so you can change the default behavior of the plugin without restarting your cluster.
|
||||
You can mark settings as `persistent` or `transient`.
|
||||
|
||||
For example, to update the retention period of the result index:
|
||||
|
||||
```json
|
||||
PUT _cluster/settings
|
||||
{
|
||||
"transient": {
|
||||
"plugins.anomaly_detection.ad_result_history_retention_period": "5m"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
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.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_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_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_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 | 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` | 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.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_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_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.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_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.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.
|
||||
@@ -1,59 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Management
|
||||
parent: Alerting
|
||||
nav_order: 5
|
||||
---
|
||||
|
||||
# Management
|
||||
|
||||
|
||||
## Alerting indices
|
||||
|
||||
The alerting feature creates several indices and one alias. The security plugin demo script configures them as [system indices]({{site.url}}{{site.baseurl}}/security-plugin/configuration/system-indices/) for an extra layer of protection. Don't delete these indices or modify their contents without using the alerting APIs.
|
||||
|
||||
Index | Purpose
|
||||
:--- | :---
|
||||
`.opendistro-alerting-alerts` | Stores ongoing alerts.
|
||||
`.opendistro-alerting-alert-history-<date>` | Stores a history of completed alerts.
|
||||
`.opendistro-alerting-config` | Stores monitors, triggers, and destinations. [Take a snapshot]({{site.url}}{{site.baseurl}}/opensearch/snapshot-restore) of this index to back up your alerting configuration.
|
||||
`.opendistro-alerting-alert-history-write` (alias) | Provides a consistent URI for the `.opendistro-alerting-alert-history-<date>` index.
|
||||
|
||||
All alerting indices are hidden by default. For a summary, make the following request:
|
||||
|
||||
```
|
||||
GET _cat/indices?expand_wildcards=open,hidden
|
||||
```
|
||||
|
||||
|
||||
## Alerting settings
|
||||
|
||||
We don't recommend changing these settings; the defaults should work well for most use cases.
|
||||
|
||||
All settings are available using the OpenSearch `_cluster/settings` API. None require a restart, and all can be marked `persistent` or `transient`.
|
||||
|
||||
Setting | Default | Description
|
||||
:--- | :--- | :---
|
||||
`plugins.scheduled_jobs.enabled` | true | Whether the alerting plugin is enabled or not. If disabled, all monitors immediately stop running.
|
||||
`plugins.alerting.index_timeout` | 60s | The timeout for creating monitors and destinations using the REST APIs.
|
||||
`plugins.alerting.request_timeout` | 10s | The timeout for miscellaneous requests from the plugin.
|
||||
`plugins.alerting.action_throttle_max_value` | 24h | The maximum amount of time you can set for action throttling. By default, this value displays as 1440 minutes in OpenSearch Dashboards.
|
||||
`plugins.alerting.input_timeout` | 30s | How long the monitor can take to issue the search request.
|
||||
`plugins.alerting.bulk_timeout` | 120s | How long the monitor can write alerts to the alert index.
|
||||
`plugins.alerting.alert_backoff_count` | 3 | The number of retries for writing alerts before the operation fails.
|
||||
`plugins.alerting.alert_backoff_millis` | 50ms | The amount of time to wait between retries---increases exponentially after each failed retry.
|
||||
`plugins.alerting.alert_history_rollover_period` | 12h | How frequently to check whether the `.opendistro-alerting-alert-history-write` alias should roll over to a new history index and whether the Alerting plugin should delete any history indices.
|
||||
`plugins.alerting.move_alerts_backoff_millis` | 250 | The amount of time to wait between retries---increases exponentially after each failed retry.
|
||||
`plugins.alerting.move_alerts_backoff_count` | 3 | The number of retries for moving alerts to a deleted state after their monitor or trigger has been deleted.
|
||||
`plugins.alerting.monitor.max_monitors` | 1000 | The maximum number of monitors users can create.
|
||||
`plugins.alerting.alert_history_max_age` | 30d | The oldest document to store in the `.opendistro-alert-history-<date>` index before creating a new index. If the number of alerts in this time period does not exceed `alert_history_max_docs`, alerting creates one history index per period (e.g. one index every 30 days).
|
||||
`plugins.alerting.alert_history_max_docs` | 1000 | The maximum number of alerts to store in the `.opendistro-alert-history-<date>` index before creating a new index.
|
||||
`plugins.alerting.alert_history_enabled` | true | Whether to create `.opendistro-alerting-alert-history-<date>` indices.
|
||||
`plugins.alerting.alert_history_retention_period` | 60d | The amount of time to keep history indices before automatically deleting them.
|
||||
`plugins.alerting.destination.allow_list` | ["chime", "slack", "custom_webhook", "email", "test_action"] | The list of allowed destinations. If you don't want to allow users to a certain type of destination, you can remove it from this list, but we recommend leaving this setting as-is.
|
||||
`plugins.alerting.filter_by_backend_roles` | "false" | Restricts access to monitors by backend role. See [Alerting security]({{site.url}}{{site.baseurl}}/monitoring-plugins/alerting/security/).
|
||||
`plugins.scheduled_jobs.sweeper.period` | 5m | The alerting feature uses its "job sweeper" component to periodically check for new or updated jobs. This setting is the rate at which the sweeper checks to see if any jobs (monitors) have changed and need to be rescheduled.
|
||||
`plugins.scheduled_jobs.sweeper.page_size` | 100 | The page size for the sweeper. You shouldn't need to change this value.
|
||||
`plugins.scheduled_jobs.sweeper.backoff_millis` | 50ms | The amount of time the sweeper waits between retries---increases exponentially after each failed retry.
|
||||
`plugins.scheduled_jobs.sweeper.retry_count` | 3 | The total number of times the sweeper should retry before throwing an error.
|
||||
`plugins.scheduled_jobs.request_timeout` | 10s | The timeout for the request that sweeps shards for jobs.
|
||||
@@ -1,265 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Data streams
|
||||
nav_order: 13
|
||||
---
|
||||
|
||||
# Data streams
|
||||
|
||||
If you're ingesting continuously generated time-series data such as logs, events, and metrics into OpenSearch, you're likely in a scenario where the number of documents grows rapidly and you don't need to update older documents.
|
||||
|
||||
A typical workflow to manage time-series data involves multiple steps, such as creating a rollover index alias, defining a write index, and defining common mappings and settings for the backing indices.
|
||||
|
||||
Data streams simplify this process and enforce a setup that best suits time-series data, such as being designed primarily for append-only data and ensuring that each document has a timestamp field.
|
||||
|
||||
A data stream is internally composed of multiple backing indices. Search requests are routed to all the backing indices, while indexing requests are routed to the latest write index. [ISM]({{site.url}}{{site.baseurl}}/im-plugin/ism/index/) policies let you automatically handle index rollovers or deletions.
|
||||
|
||||
|
||||
## Get started with data streams
|
||||
|
||||
### Step 1: Create an index template
|
||||
|
||||
To create a data stream, you first need to create an index template that configures a set of indices as a data stream. The `data_stream` object indicates that it’s a data stream and not a regular index template. The index pattern matches with the name of the data stream:
|
||||
|
||||
```json
|
||||
PUT _index_template/logs-template
|
||||
{
|
||||
"index_patterns": [
|
||||
"my-data-stream",
|
||||
"logs-*"
|
||||
],
|
||||
"data_stream": {},
|
||||
"priority": 100
|
||||
}
|
||||
```
|
||||
|
||||
In this case, each ingested document must have an `@timestamp` field.
|
||||
You also have the ability to define your own custom timestamp field as a property in the `data_stream` object. You can also add index mappings and other settings here, just as you would for a regular index template.
|
||||
|
||||
```json
|
||||
PUT _index_template/logs-template-nginx
|
||||
{
|
||||
"index_patterns": "logs-nginx",
|
||||
"data_stream": {
|
||||
"timestamp_field": {
|
||||
"name": "request_time"
|
||||
}
|
||||
},
|
||||
"priority": 200,
|
||||
"template": {
|
||||
"settings": {
|
||||
"number_of_shards": 1,
|
||||
"number_of_replicas": 0
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
In this case, `logs-nginx` index matches both the `logs-template` and `logs-template-nginx` templates. When you have a tie, OpenSearch selects the matching index template with the higher priority value.
|
||||
|
||||
### Step 2: Create a data stream
|
||||
|
||||
After you create an index template, you can create a data stream.
|
||||
You can use the data stream API to explicitly create a data stream. The data stream API initializes the first backing index:
|
||||
|
||||
```json
|
||||
PUT _data_stream/logs-redis
|
||||
PUT _data_stream/logs-nginx
|
||||
```
|
||||
|
||||
You can also directly start ingesting data without creating a data stream.
|
||||
|
||||
Because we have a matching index template with a data_stream object, OpenSearch automatically creates the data stream:
|
||||
|
||||
```json
|
||||
POST logs-staging/_doc
|
||||
{
|
||||
"message": "login attempt failed",
|
||||
"@timestamp": "2013-03-01T00:00:00"
|
||||
}
|
||||
```
|
||||
|
||||
To see information about a specific data stream:
|
||||
|
||||
```json
|
||||
GET _data_stream/logs-nginx
|
||||
```
|
||||
|
||||
#### Sample response
|
||||
|
||||
```json
|
||||
{
|
||||
"data_streams" : [
|
||||
{
|
||||
"name" : "logs-nginx",
|
||||
"timestamp_field" : {
|
||||
"name" : "request_time"
|
||||
},
|
||||
"indices" : [
|
||||
{
|
||||
"index_name" : ".ds-logs-nginx-000001",
|
||||
"index_uuid" : "-VhmuhrQQ6ipYCmBhn6vLw"
|
||||
}
|
||||
],
|
||||
"generation" : 1,
|
||||
"status" : "GREEN",
|
||||
"template" : "logs-template-nginx"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
You can see the name of the timestamp field, the list of the backing indices, and the template that's used to create the data stream. You can also see the health of the data stream, which represents the lowest status of all its backing indices.
|
||||
|
||||
To see more insights about the data stream, use the `_stats` endpoint:
|
||||
|
||||
```json
|
||||
GET _data_stream/logs-nginx/_stats
|
||||
```
|
||||
|
||||
#### Sample response
|
||||
|
||||
```json
|
||||
{
|
||||
"_shards" : {
|
||||
"total" : 1,
|
||||
"successful" : 1,
|
||||
"failed" : 0
|
||||
},
|
||||
"data_stream_count" : 1,
|
||||
"backing_indices" : 1,
|
||||
"total_store_size_bytes" : 208,
|
||||
"data_streams" : [
|
||||
{
|
||||
"data_stream" : "logs-nginx",
|
||||
"backing_indices" : 1,
|
||||
"store_size_bytes" : 208,
|
||||
"maximum_timestamp" : 0
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Step 3: Ingest data into the data stream
|
||||
|
||||
To ingest data into a data stream, you can use the regular indexing APIs. Make sure every document that you index has a timestamp field. If you try to ingest a document that doesn't have a timestamp field, you get an error.
|
||||
|
||||
```json
|
||||
POST logs-redis/_doc
|
||||
{
|
||||
"message": "login attempt",
|
||||
"@timestamp": "2013-03-01T00:00:00"
|
||||
}
|
||||
```
|
||||
|
||||
### Step 4: Searching a data stream
|
||||
|
||||
You can search a data stream just like you search a regular index or an index alias.
|
||||
The search operation applies to all of the backing indices (all data present in the stream).
|
||||
|
||||
```json
|
||||
GET logs-redis/_search
|
||||
{
|
||||
"query": {
|
||||
"match": {
|
||||
"message": "login"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Sample response
|
||||
|
||||
```json
|
||||
{
|
||||
"took" : 514,
|
||||
"timed_out" : false,
|
||||
"_shards" : {
|
||||
"total" : 5,
|
||||
"successful" : 5,
|
||||
"skipped" : 0,
|
||||
"failed" : 0
|
||||
},
|
||||
"hits" : {
|
||||
"total" : {
|
||||
"value" : 1,
|
||||
"relation" : "eq"
|
||||
},
|
||||
"max_score" : 0.2876821,
|
||||
"hits" : [
|
||||
{
|
||||
"_index" : ".ds-logs-redis-000001",
|
||||
"_type" : "_doc",
|
||||
"_id" : "-rhVmXoBL6BAVWH3mMpC",
|
||||
"_score" : 0.2876821,
|
||||
"_source" : {
|
||||
"message" : "login attempt",
|
||||
"@timestamp" : "2013-03-01T00:00:00"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Step 5: Rollover a data stream
|
||||
|
||||
A rollover operation creates a new backing index that becomes the data stream’s new write index.
|
||||
|
||||
To perform manual rollover operation on the data stream:
|
||||
|
||||
```json
|
||||
POST logs-redis/_rollover
|
||||
```
|
||||
|
||||
#### Sample response
|
||||
|
||||
```json
|
||||
{
|
||||
"acknowledged" : true,
|
||||
"shards_acknowledged" : true,
|
||||
"old_index" : ".ds-logs-redis-000001",
|
||||
"new_index" : ".ds-logs-redis-000002",
|
||||
"rolled_over" : true,
|
||||
"dry_run" : false,
|
||||
"conditions" : { }
|
||||
}
|
||||
```
|
||||
|
||||
If you now perform a `GET` operation on the `logs-redis` data stream, you see that the generation ID is incremented from 1 to 2.
|
||||
|
||||
You can also set up an [Index State Management (ISM) policy]({{site.url}}{{site.baseurl}}/im-plugin/ism/policies/) to automate the rollover process for the data stream.
|
||||
The ISM policy is applied to the backing indices at the time of their creation. When you associate a policy to a data stream, it only affects the future backing indices of that data stream.
|
||||
|
||||
You also don’t need to provide the `rollover_alias` setting, because the ISM policy infers this information from the backing index.
|
||||
|
||||
### Step 6: Manage data streams in OpenSearch Dashboards
|
||||
|
||||
To manage data streams from OpenSearch Dashboards, open **OpenSearch Dashboards**, choose **Index Management**, select **Indices** or **Policy managed indices**.
|
||||
|
||||
You see a toggle switch for data streams that you can use to show or hide indices belonging to a data stream.
|
||||
|
||||
When you enable this switch, you see a data stream multi-select dropdown menu that you can use for filtering data streams.
|
||||
You also see a data stream column that shows you the name of the data stream the index is contained in.
|
||||
|
||||
|
||||
|
||||
You can select one or more data streams and apply an ISM policy on them. You can also apply a policy on any individual backing index.
|
||||
|
||||
You can performing visualizations on a data stream just like you would on a regular index or index alias.
|
||||
|
||||
### Step 7: Delete a data stream
|
||||
|
||||
The delete operation first deletes the backing indices of a data stream and then deletes the data stream itself.
|
||||
|
||||
To delete a data stream and all of its hidden backing indices:
|
||||
|
||||
```json
|
||||
DELETE _data_stream/<name_of_data_stream>
|
||||
```
|
||||
|
||||
You can use wildcards to delete more than one data stream.
|
||||
|
||||
We recommend deleting data from a data stream using an ISM policy.
|
||||
|
||||
You can also use [asynchronous search]({{site.url}}{{site.baseurl}}/search-plugins/async/index/) and [SQL]({{site.url}}{{site.baseurl}}/search-plugins/sql/index/) and [PPL]({{site.url}}{{site.baseurl}}/search-plugins/ppl/index/) to query your data stream directly. You can also use the security plugin to define granular permissions on the data stream name.
|
||||
@@ -1,19 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Compatibility
|
||||
parent: Install OpenSearch
|
||||
nav_order: 2
|
||||
---
|
||||
|
||||
# Operating system and JVM compatibility
|
||||
|
||||
- We recommend installing OpenSearch on RHEL- or Debian-based Linux distributions that use [systemd](https://en.wikipedia.org/wiki/Systemd), such as CentOS, Amazon Linux 2, and Ubuntu (LTS). OpenSearch should work on many Linux distributions, but we only test a handful.
|
||||
- The OpenSearch tarball ships with a compatible version of Java in the `jdk` directory. To find its version, run `./jdk/bin/java -version`. For example, the OpenSearch 1.0.0 tarball ships with Java 15 (non-LTS).
|
||||
|
||||
{% comment %}`./jdk/bin/java -version` doesn't work on macOS with zsh at the moment, and I have no idea why. Maybe we need a macOS artifact. Regardless, the command works on Amazon Linux 2 with bash and presumably other distros. - aetter{% endcomment %}
|
||||
|
||||
To use a different Java installation, set the `OPENSEARCH_JAVA_HOME` environment variable to the Java install location. We recommend Java 11 (LTS), but OpenSearch also works with Java 8.
|
||||
|
||||
OpenSearch version | Compatible Java versions | Recommended operating systems
|
||||
:--- | :--- | :---
|
||||
1.x | 8, 11 | Red Hat Enterprise Linux 7, 8; CentOS 7, 8; Amazon Linux 2; Ubuntu 16.04, 18.04, 20.04
|
||||
@@ -1,133 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Helm
|
||||
parent: Install OpenSearch
|
||||
nav_order: 6
|
||||
---
|
||||
|
||||
# Run OpenSearch using Helm
|
||||
|
||||
Helm is a package manager that allows you to easily install and manage OpenSearch in a Kubernetes cluster. You can define your OpenSearch configurations in a YAML file and use Helm to deploy your applications in a version-controlled and reproducible way.
|
||||
|
||||
The Helm chart contains the resources described in the following table.
|
||||
|
||||
Resource | Description
|
||||
:--- | :---
|
||||
`Chart.yaml` | Information about the chart.
|
||||
`values.yaml` | Default configuration values for the chart.
|
||||
`templates` | Templates that combine with values to generate the Kubernetes manifest files.
|
||||
|
||||
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/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 }
|
||||
|
||||
## Prerequisites
|
||||
|
||||
The default Helm chart deploys a three-node cluster. We recommend that you have at least 8 GiB of memory available for this deployment. You can expect the deployment to fail if, say, you have less than 4 GiB of memory available.
|
||||
|
||||
## Install OpenSearch using Helm
|
||||
|
||||
1. Clone the [helm-charts](https://github.com/opensearch-project/helm-charts) repository:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/opensearch-project/helm-charts
|
||||
```
|
||||
|
||||
1. Change to the `opensearch` directory:
|
||||
|
||||
```bash
|
||||
cd charts/opensearch
|
||||
```
|
||||
|
||||
1. Package the Helm chart:
|
||||
|
||||
```bash
|
||||
helm package .
|
||||
```
|
||||
|
||||
1. Deploy OpenSearch:
|
||||
|
||||
```bash
|
||||
helm install --generate-name opensearch-1.0.0.tgz
|
||||
```
|
||||
The output shows you the specifications instantiated from the install.
|
||||
To customize the deployment, pass in the values that you want to override with a custom YAML file:
|
||||
|
||||
```bash
|
||||
helm install --values=customvalues.yaml opensearch-1.0.0.tgz
|
||||
```
|
||||
|
||||
#### Sample output
|
||||
|
||||
```yaml
|
||||
NAME: opensearch-1-1629223146
|
||||
LAST DEPLOYED: Tue Aug 17 17:59:07 2021
|
||||
NAMESPACE: default
|
||||
STATUS: deployed
|
||||
REVISION: 1
|
||||
TEST SUITE: None
|
||||
NOTES:
|
||||
Watch all cluster members come up.
|
||||
$ kubectl get pods --namespace=default -l app=opensearch-cluster-master -w
|
||||
```
|
||||
|
||||
To make sure your OpenSearch pod is up and running, run the following command:
|
||||
|
||||
```bash
|
||||
$ kubectl get pods
|
||||
NAME READY STATUS RESTARTS AGE
|
||||
opensearch-cluster-master-0 1/1 Running 0 3m56s
|
||||
opensearch-cluster-master-1 1/1 Running 0 3m56s
|
||||
opensearch-cluster-master-2 1/1 Running 0 3m56s
|
||||
```
|
||||
|
||||
To access the OpenSearch shell:
|
||||
|
||||
```bash
|
||||
$ kubectl exec -it opensearch-cluster-master-0 -- /bin/bash
|
||||
```
|
||||
|
||||
You can send requests to the pod to verify that OpenSearch is up and running:
|
||||
|
||||
```json
|
||||
$ curl -XGET https://localhost:9200 -u 'admin:admin' --insecure
|
||||
{
|
||||
"name" : "opensearch-cluster-master-1",
|
||||
"cluster_name" : "opensearch-cluster",
|
||||
"cluster_uuid" : "hP2gq5bPS3SLp8Z7wXm8YQ",
|
||||
"version" : {
|
||||
"distribution" : "opensearch",
|
||||
"number" : "1.0.0",
|
||||
"build_type" : "tar",
|
||||
"build_hash" : "34550c5b17124ddc59458ef774f6b43a086522e3",
|
||||
"build_date" : "2021-07-02T23:22:21.383695Z",
|
||||
"build_snapshot" : false,
|
||||
"lucene_version" : "8.8.2",
|
||||
"minimum_wire_compatibility_version" : "6.8.0",
|
||||
"minimum_index_compatibility_version" : "6.0.0-beta1"
|
||||
},
|
||||
"tagline" : "The OpenSearch Project: https://opensearch.org/"
|
||||
}
|
||||
```
|
||||
|
||||
## Uninstall using Helm
|
||||
|
||||
To identify the OpenSearch deployment that you want to delete:
|
||||
|
||||
```bash
|
||||
$ helm list
|
||||
NAME NAMESPACEREVISIONUPDATED STATUS CHART APP VERSION
|
||||
opensearch-1-1629223146 default 1 2021-08-17 17:59:07.664498239 +0000 UTCdeployedopensearch-1.0.0 1.0.0
|
||||
```
|
||||
|
||||
To delete or uninstall a deployment, run the following command:
|
||||
|
||||
```bash
|
||||
helm delete opensearch-1-1629223146
|
||||
```
|
||||
|
||||
For steps to install OpenSearch Dashboards, see [Helm to install OpenSearch Dashboards]({{site.url}}{{site.baseurl}}/dashboards/install/helm/).
|
||||
@@ -1,125 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Query DSL
|
||||
nav_order: 27
|
||||
has_children: true
|
||||
redirect_from:
|
||||
- /opensearch/query-dsl/
|
||||
- /docs/opensearch/query-dsl/
|
||||
---
|
||||
|
||||
{%- comment -%}The `/docs/opensearch/query-dsl/` redirect is specifically to support the UI links in OpenSearch Dashboards 1.0.0.{%- endcomment -%}
|
||||
|
||||
# Query DSL
|
||||
|
||||
While you can use HTTP request parameters to perform simple searches, you can also use the OpenSearch query domain-specific language (DSL), which provides a wider range of search options. The query DSL uses the HTTP request body, so you can more easily customize your queries to get the exact results that you want.
|
||||
|
||||
For example, the following request performs a simple search to search for a `speaker` field that has a value of `queen`.
|
||||
|
||||
**Sample request**
|
||||
```json
|
||||
GET _search?q=speaker:queen
|
||||
```
|
||||
|
||||
**Sample response**
|
||||
```
|
||||
{
|
||||
"took": 87,
|
||||
"timed_out": false,
|
||||
"_shards": {
|
||||
"total": 68,
|
||||
"successful": 68,
|
||||
"skipped": 0,
|
||||
"failed": 0
|
||||
},
|
||||
"hits": {
|
||||
"total": {
|
||||
"value": 4080,
|
||||
"relation": "eq"
|
||||
},
|
||||
"max_score": 4.4368687,
|
||||
"hits": [
|
||||
{
|
||||
"_index": "new_shakespeare",
|
||||
"_type": "_doc",
|
||||
"_id": "28559",
|
||||
"_score": 4.4368687,
|
||||
"_source": {
|
||||
"type": "line",
|
||||
"line_id": 28560,
|
||||
"play_name": "Cymbeline",
|
||||
"speech_number": 20,
|
||||
"line_number": "1.1.81",
|
||||
"speaker": "QUEEN",
|
||||
"text_entry": "No, be assured you shall not find me, daughter,"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
With query DSL, however, you can include an HTTP request body to look for results more tailored to your needs. The following example shows how to search for `speaker` and `text_entry` fields that have a value of `QUEEN`.
|
||||
|
||||
**Sample request**
|
||||
```json
|
||||
{
|
||||
"query": {
|
||||
"multi_match": {
|
||||
"query": "QUEEN",
|
||||
"fields": ["speaker", "text_entry"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Sample Response**
|
||||
```json
|
||||
{
|
||||
"took": 39,
|
||||
"timed_out": false,
|
||||
"_shards": {
|
||||
"total": 68,
|
||||
"successful": 68,
|
||||
"skipped": 0,
|
||||
"failed": 0
|
||||
},
|
||||
"hits": {
|
||||
"total": {
|
||||
"value": 5837,
|
||||
"relation": "eq"
|
||||
},
|
||||
"max_score": 7.8623476,
|
||||
"hits": [
|
||||
{
|
||||
"_index": "new_shakespeare",
|
||||
"_type": "_doc",
|
||||
"_id": "100763",
|
||||
"_score": 7.8623476,
|
||||
"_source": {
|
||||
"type": "line",
|
||||
"line_id": 100764,
|
||||
"play_name": "Troilus and Cressida",
|
||||
"speech_number": 43,
|
||||
"line_number": "3.1.68",
|
||||
"speaker": "PANDARUS",
|
||||
"text_entry": "Sweet queen, sweet queen! thats a sweet queen, i faith."
|
||||
}
|
||||
},
|
||||
{
|
||||
"_index": "shakespeare",
|
||||
"_type": "_doc",
|
||||
"_id": "28559",
|
||||
"_score": 5.8923807,
|
||||
"_source": {
|
||||
"type": "line",
|
||||
"line_id": 28560,
|
||||
"play_name": "Cymbeline",
|
||||
"speech_number": 20,
|
||||
"line_number": "1.1.81",
|
||||
"speaker": "QUEEN",
|
||||
"text_entry": "No, be assured you shall not find me, daughter,"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
The OpenSearch query DSL comes in three varieties: term-level queries, full-text queries, and boolean queries. You can even perform more complicated searches by using different elements from each variety to find whatever data you need.
|
||||
@@ -1,81 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Alias
|
||||
parent: REST API reference
|
||||
nav_order: 5
|
||||
---
|
||||
|
||||
# Alias
|
||||
Introduced 1.0
|
||||
{: .label .label-purple }
|
||||
|
||||
An alias is a virtual pointer that you can use to reference one or more indices. Creating and updating aliases are atomic operations, so you can reindex your data and point an alias at it without any downtime.
|
||||
|
||||
|
||||
## Example
|
||||
|
||||
```json
|
||||
POST _aliases
|
||||
{
|
||||
"actions": [
|
||||
{
|
||||
"add": {
|
||||
"index": "movies",
|
||||
"alias": "movies-alias1"
|
||||
}
|
||||
},
|
||||
{
|
||||
"remove": {
|
||||
"index": "old-index",
|
||||
"alias": "old-index-alias"
|
||||
}
|
||||
}
|
||||
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Path and HTTP methods
|
||||
|
||||
```
|
||||
POST _aliases
|
||||
```
|
||||
|
||||
## URL parameters
|
||||
|
||||
All alias parameters are optional.
|
||||
|
||||
Parameter | Data Type | Description
|
||||
:--- | :--- | :---
|
||||
master_timeout | Time | The amount of time to wait for a response from the master node. Default is `30s`.
|
||||
timeout | Time | The amount of time to wait for a response from the cluster. Default is `30s`.
|
||||
|
||||
## Request body
|
||||
|
||||
In your request body, you need to specify what action to take, the alias name, and the index you want to associate with the alias. Other fields are optional.
|
||||
|
||||
Field | Data Type | Description | Required
|
||||
:--- | :--- | :--- | :---
|
||||
actions | Array | Set of actions you want to perform on the index. Valid options are: `add`, `remove`, and `remove_index`. You must have at least one action in the array. | Yes
|
||||
add | N/A | Adds an alias to the specified index. | No
|
||||
remove | N/A | Removes an alias from the specified index. | No
|
||||
remove_index | N/A | Deletes an index. | No
|
||||
index | String | Name of the index you want to associate with the alias. Supports wildcard expressions. | Yes if you don't supply an `indices` field in the body.
|
||||
indices | Array | Array of index names you want to associate with the alias. | Yes if you don't supply an `index` field in the body.
|
||||
alias | String | The name of the alias. | Yes if you don't supply an `aliases` field in the body.
|
||||
aliases | Array | Array of alias names. | Yes if you don't supply an `alias` field in the body.
|
||||
filter | Object | A filter to use with the alias, so the alias points to a filtered part of the index. | No
|
||||
is_hidden | Boolean | Specifies whether the alias should be hidden from results that include wildcard expressions | No
|
||||
must_exist | Boolean | Specifies whether the alias to remove must exist. | No
|
||||
is_write_index | Boolean | Specifies whether the index should be a write index. An alias can only have one write index at a time. | No
|
||||
routing | String | Used to assign a custom value to a shard for specific operations. | No
|
||||
index_routing | String | Assigns a custom value to a shard only for index operations. | No
|
||||
search_routing | String | Assigns a custom value to a shard only for search operations. | No
|
||||
|
||||
## Response
|
||||
|
||||
```json
|
||||
{
|
||||
"acknowledged": true
|
||||
}
|
||||
```
|
||||
@@ -1,63 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: cat aliases
|
||||
parent: CAT
|
||||
grand_parent: REST API reference
|
||||
nav_order: 1
|
||||
has_children: false
|
||||
---
|
||||
|
||||
# cat aliases
|
||||
Introduced 1.0
|
||||
{: .label .label-purple }
|
||||
|
||||
The cat aliases operation lists the mapping of aliases to indices, plus routing and filtering information.
|
||||
|
||||
## Example
|
||||
|
||||
```json
|
||||
GET _cat/aliases?v
|
||||
```
|
||||
|
||||
To limit the information to a specific alias, add the alias name after your query:
|
||||
|
||||
```json
|
||||
GET _cat/aliases/<alias>?v
|
||||
```
|
||||
|
||||
If you want to get information for more than one alias, separate the alias names with commas:
|
||||
|
||||
```json
|
||||
GET _cat/aliases/alias1,alias2,alias3
|
||||
```
|
||||
|
||||
## Path and HTTP methods
|
||||
|
||||
```
|
||||
GET _cat/aliases/<alias>
|
||||
GET _cat/aliases
|
||||
```
|
||||
|
||||
|
||||
## URL parameters
|
||||
|
||||
All cat aliases URL parameters are optional.
|
||||
|
||||
In addition to the [common URL parameters]({{site.url}}{{site.baseurl}}/opensearch/rest-api/cat/index#common-url-parameters), you can specify the following parameters:
|
||||
|
||||
Parameter | Type | Description
|
||||
:--- | :--- | :---
|
||||
local | Boolean | Whether to return information from the local node only instead of from the master node. Default is false.
|
||||
expand_wildcards | Enum | Expands wildcard expressions to concrete indices. Combine multiple values with commas. Supported values are `all`, `open`, `closed`, `hidden`, and `none`. Default is `open`.
|
||||
|
||||
## Response
|
||||
|
||||
The following response shows that `alias1` refers to a `movies` index and has a configured filter:
|
||||
|
||||
```json
|
||||
alias | index | filter | routing.index | routing.search | is_write_index
|
||||
alias1 | movies | * | - | - | -
|
||||
.kibana | .kibana_1 | - | - | - | -
|
||||
```
|
||||
|
||||
To learn more about index aliases, see [Index aliases]({{site.url}}{{site.baseurl}}/opensearch/index-alias).
|
||||
@@ -1,63 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: cat allocation
|
||||
parent: CAT
|
||||
grand_parent: REST API reference
|
||||
nav_order: 5
|
||||
has_children: false
|
||||
---
|
||||
|
||||
# cat allocation
|
||||
Introduced 1.0
|
||||
{: .label .label-purple }
|
||||
|
||||
The cat allocation operation lists the allocation of disk space for indices and the number of shards on each node.
|
||||
|
||||
## Example
|
||||
|
||||
```json
|
||||
GET _cat/allocation?v
|
||||
```
|
||||
|
||||
To limit the information to a specific node, add the node name after your query:
|
||||
|
||||
```json
|
||||
GET _cat/allocation/<node_name>
|
||||
```
|
||||
|
||||
If you want to get information for more than one node, separate the node names with commas:
|
||||
|
||||
```json
|
||||
GET _cat/aliases/node_name_1,node_name_2,node_name_3
|
||||
```
|
||||
|
||||
## Path and HTTP methods
|
||||
|
||||
```
|
||||
GET _cat/allocation?v
|
||||
GET _cat/allocation/<node_name>
|
||||
```
|
||||
|
||||
## URL parameters
|
||||
|
||||
All cat allocation URL parameters are optional.
|
||||
|
||||
In addition to the [common URL parameters]({{site.url}}{{site.baseurl}}/opensearch/rest-api/cat/index#common-url-parameters), you can specify the following parameters:
|
||||
|
||||
Parameter | Type | Description
|
||||
:--- | :--- | :---
|
||||
bytes | Byte size | Specify the units for byte size. For example, `7kb` or `6gb`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/opensearch/units/).
|
||||
local | Boolean | Whether to return information from the local node only instead of from the master node. Default is false.
|
||||
master_timeout | Time | The amount of time to wait for a connection to the master node. Default is 30 seconds.
|
||||
|
||||
|
||||
|
||||
## Response
|
||||
|
||||
The following response shows that 8 shards are allocated to each the two nodes available:
|
||||
|
||||
```json
|
||||
shards | disk.indices | disk.used | disk.avail | disk.total | disk.percent host | ip | node
|
||||
8 | 989.4kb | 25.9gb | 32.4gb | 58.4gb | 44 172.18.0.4 | 172.18.0.4 | odfe-node1
|
||||
8 | 962.4kb | 25.9gb | 32.4gb | 58.4gb | 44 172.18.0.3 | 172.18.0.3 | odfe-node2
|
||||
```
|
||||
@@ -1,53 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: cat count
|
||||
parent: CAT
|
||||
grand_parent: REST API reference
|
||||
nav_order: 10
|
||||
has_children: false
|
||||
---
|
||||
|
||||
# cat count
|
||||
Introduced 1.0
|
||||
{: .label .label-purple }
|
||||
|
||||
The cat count operation lists the number of documents in your cluster.
|
||||
|
||||
## Example
|
||||
|
||||
```json
|
||||
GET _cat/count?v
|
||||
```
|
||||
|
||||
To see the number of documents in a specific index or alias, add the index or alias name after your query:
|
||||
|
||||
```json
|
||||
GET _cat/count/<index_or_alias>?v
|
||||
```
|
||||
|
||||
If you want to get information for more than one index or alias, separate the index or alias names with commas:
|
||||
|
||||
```json
|
||||
GET _cat/aliases/index_or_alias_1,index_or_alias_2,index_or_alias_3
|
||||
```
|
||||
|
||||
## Path and HTTP methods
|
||||
|
||||
```
|
||||
GET _cat/count?v
|
||||
GET _cat/count/<index>?v
|
||||
```
|
||||
|
||||
## URL parameters
|
||||
|
||||
All cat count URL parameters are optional. You can specify any of the [common URL parameters]({{site.url}}{{site.baseurl}}/opensearch/rest-api/cat/index#common-url-parameters).
|
||||
|
||||
|
||||
## Response
|
||||
|
||||
The following response shows the overall document count as 1625:
|
||||
|
||||
```json
|
||||
epoch | timestamp | count
|
||||
1624237738 | 01:08:58 | 1625
|
||||
```
|
||||
@@ -1,59 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: cat field data
|
||||
parent: CAT
|
||||
grand_parent: REST API reference
|
||||
nav_order: 15
|
||||
has_children: false
|
||||
---
|
||||
|
||||
# cat fielddata
|
||||
Introduced 1.0
|
||||
{: .label .label-purple }
|
||||
|
||||
The cat fielddata operation lists the memory size used by each field per node.
|
||||
|
||||
## Example
|
||||
|
||||
```json
|
||||
GET _cat/fielddata?v
|
||||
```
|
||||
|
||||
To limit the information to a specific field, add the field name after your query:
|
||||
|
||||
```json
|
||||
GET _cat/fielddata/<field_name>?v
|
||||
```
|
||||
|
||||
If you want to get information for more than one field, separate the field names with commas:
|
||||
|
||||
```json
|
||||
GET _cat/aliases/field_name_1,field_name_2,field_name_3
|
||||
```
|
||||
|
||||
## Path and HTTP methods
|
||||
|
||||
```
|
||||
GET _cat/fielddata?v
|
||||
GET _cat/fielddata/<field_name>?v
|
||||
```
|
||||
|
||||
## URL parameters
|
||||
|
||||
All cat fielddata URL parameters are optional.
|
||||
|
||||
In addition to the [common URL parameters]({{site.url}}{{site.baseurl}}/opensearch/rest-api/cat/index#common-url-parameters), you can specify the following parameter:
|
||||
|
||||
Parameter | Type | Description
|
||||
:--- | :--- | :---
|
||||
bytes | Byte size | Specify the units for byte size. For example, `7kb` or `6gb`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/opensearch/units/).
|
||||
|
||||
## Response
|
||||
|
||||
The following response shows the memory size for all fields as 284 bytes:
|
||||
|
||||
```json
|
||||
id host ip node field size
|
||||
1vo54NuxSxOrbPEYdkSF0w 172.18.0.4 172.18.0.4 odfe-node1 _id 284b
|
||||
ZaIkkUd4TEiAihqJGkp5CA 172.18.0.3 172.18.0.3 odfe-node2 _id 284b
|
||||
```
|
||||
@@ -1,44 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: cat health
|
||||
parent: CAT
|
||||
grand_parent: REST API reference
|
||||
nav_order: 20
|
||||
has_children: false
|
||||
---
|
||||
|
||||
# cat health
|
||||
Introduced 1.0
|
||||
{: .label .label-purple }
|
||||
|
||||
The cat health operation lists the status of the cluster, how long the cluster has been up, the number of nodes, and other useful information that helps you analyze the health of your cluster.
|
||||
|
||||
## Example
|
||||
|
||||
```json
|
||||
GET _cat/health?v
|
||||
```
|
||||
|
||||
## Path and HTTP methods
|
||||
|
||||
```
|
||||
GET _cat/health?v
|
||||
```
|
||||
|
||||
## URL parameters
|
||||
|
||||
All cat health URL parameters are optional.
|
||||
|
||||
Parameter | Type | Description
|
||||
:--- | :--- | :---
|
||||
time | Time | Specify the units for time. For example, `5d` or `7h`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/opensearch/units/).
|
||||
ts | Boolean | If true, returns HH:MM:SS and Unix epoch timestamps. Default is true.
|
||||
|
||||
## Response
|
||||
|
||||
```json
|
||||
GET _cat/health?v&time=5d
|
||||
|
||||
epoch | timestamp | cluster | status | node.total | node.data | shards | pri | relo | init | unassign | pending_tasks | max_task_wait_time | active_shards_percent
|
||||
1624248112 | 04:01:52 | odfe-cluster | green | 2 | 2 | 16 | 8 | 0 | 0 | 0 | 0 | - | 100.0%
|
||||
```
|
||||
@@ -1,63 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: cat indices
|
||||
parent: CAT
|
||||
grand_parent: REST API reference
|
||||
nav_order: 25
|
||||
has_children: false
|
||||
---
|
||||
|
||||
# cat indices
|
||||
Introduced 1.0
|
||||
{: .label .label-purple }
|
||||
|
||||
The cat indices operation lists information related to indices—how much disk space they are using, how many shards they have, their health status, and so on.
|
||||
|
||||
## Example
|
||||
|
||||
```
|
||||
GET _cat/indices?v
|
||||
```
|
||||
|
||||
To limit the information to a specific index, add the index name after your query.
|
||||
|
||||
```
|
||||
GET _cat/indices/<index>?v
|
||||
```
|
||||
|
||||
If you want to get information for more than one index, separate the indices with commas:
|
||||
|
||||
```json
|
||||
GET _cat/aliases/index1,index2,index3
|
||||
```
|
||||
|
||||
## Path and HTTP methods
|
||||
|
||||
```
|
||||
GET _cat/indices/<index>
|
||||
GET _cat/indices
|
||||
```
|
||||
|
||||
## URL parameters
|
||||
|
||||
All cat indices URL parameters are optional.
|
||||
|
||||
In addition to the [common URL parameters]({{site.url}}{{site.baseurl}}/opensearch/rest-api/cat/index#common-url-parameters), you can specify the following parameters:
|
||||
|
||||
Parameter | Type | Description
|
||||
:--- | :--- | :---
|
||||
bytes | Byte size | Specify the units for byte size. For example, `7kb` or `6gb`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/opensearch/units/).
|
||||
health | String | Limit indices based on their health status. Supported values are `green`, `yellow`, and `red`.
|
||||
include_unloaded_segments | Boolean | Whether to include information from segments not loaded into memory. Default is false.
|
||||
master_timeout | Time | The amount of time to wait for a connection to the master node. Default is 30 seconds.
|
||||
pri | Boolean | Whether to return information only from the primary shards. Default is false.
|
||||
time | Time | Specify the units for time. For example, `5d` or `7h`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/opensearch/units/).
|
||||
expand_wildcards | Enum | Expands wildcard expressions to concrete indices. Combine multiple values with commas. Supported values are `all`, `open`, `closed`, `hidden`, and `none`. Default is `open`.
|
||||
|
||||
|
||||
## Response
|
||||
|
||||
```json
|
||||
health | status | index | uuid | pri | rep | docs.count | docs.deleted | store.size | pri.store.size
|
||||
green | open | movies | UZbpfERBQ1-3GSH2bnM3sg | 1 | 1 | 1 | 0 | 7.7kb | 3.8kb
|
||||
```
|
||||
@@ -1,44 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: cat master
|
||||
parent: CAT
|
||||
grand_parent: REST API reference
|
||||
nav_order: 30
|
||||
has_children: false
|
||||
---
|
||||
|
||||
# cat master
|
||||
Introduced 1.0
|
||||
{: .label .label-purple }
|
||||
|
||||
The cat master operation lists information that helps identify the elected master node.
|
||||
|
||||
## Example
|
||||
|
||||
```
|
||||
GET _cat/master?v
|
||||
```
|
||||
|
||||
## Path and HTTP methods
|
||||
|
||||
```
|
||||
GET _cat/master
|
||||
```
|
||||
|
||||
## URL parameters
|
||||
|
||||
All cat master URL parameters are optional.
|
||||
|
||||
In addition to the [common URL parameters]({{site.url}}{{site.baseurl}}/opensearch/rest-api/cat/index#common-url-parameters), you can specify the following parameters:
|
||||
|
||||
Parameter | Type | Description
|
||||
:--- | :--- | :---
|
||||
master_timeout | Time | The amount of time to wait for a connection to the master node. Default is 30 seconds.
|
||||
|
||||
|
||||
## Response
|
||||
|
||||
```json
|
||||
id | host | ip | node
|
||||
ZaIkkUd4TEiAihqJGkp5CA | 172.18.0.3 | 172.18.0.3 | odfe-node2
|
||||
```
|
||||
@@ -1,45 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: cat nodeattrs
|
||||
parent: CAT
|
||||
grand_parent: REST API reference
|
||||
nav_order: 35
|
||||
has_children: false
|
||||
---
|
||||
|
||||
# cat nodeattrs
|
||||
Introduced 1.0
|
||||
{: .label .label-purple }
|
||||
|
||||
The cat nodeattrs operation lists the attributes of custom nodes.
|
||||
|
||||
## Example
|
||||
|
||||
```
|
||||
GET _cat/nodeattrs?v
|
||||
```
|
||||
|
||||
## Path and HTTP methods
|
||||
|
||||
```
|
||||
GET _cat/nodeattrs
|
||||
```
|
||||
|
||||
## URL parameters
|
||||
|
||||
All cat nodeattrs URL parameters are optional.
|
||||
|
||||
In addition to the [common URL parameters]({{site.url}}{{site.baseurl}}/opensearch/rest-api/cat/index#common-url-parameters), you can specify the following parameters:
|
||||
|
||||
Parameter | Type | Description
|
||||
:--- | :--- | :---
|
||||
local | Boolean | Whether to return information from the local node only instead of from the master node. Default is false.
|
||||
master_timeout | Time | The amount of time to wait for a connection to the master node. Default is 30 seconds.
|
||||
|
||||
|
||||
## Response
|
||||
|
||||
```json
|
||||
node | host | ip | attr | value
|
||||
odfe-node2 | 172.18.0.3 | 172.18.0.3 | testattr | test
|
||||
```
|
||||
@@ -1,52 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: cat nodes
|
||||
parent: CAT
|
||||
grand_parent: REST API reference
|
||||
nav_order: 40
|
||||
has_children: false
|
||||
---
|
||||
|
||||
# cat nodes
|
||||
Introduced 1.0
|
||||
{: .label .label-purple }
|
||||
|
||||
The cat nodes operation lists node-level information, including node roles and load metrics.
|
||||
|
||||
A few important node metrics are `pid`, `name`, `master`, `ip`, `port`, `version`, `build`, `jdk`, along with `disk`, `heap`, `ram`, and `file_desc`.
|
||||
|
||||
## Example
|
||||
|
||||
```
|
||||
GET _cat/nodes?v
|
||||
```
|
||||
|
||||
## Path and HTTP methods
|
||||
|
||||
```
|
||||
GET _cat/nodes
|
||||
```
|
||||
|
||||
## URL parameters
|
||||
|
||||
All cat nodes URL parameters are optional.
|
||||
|
||||
In addition to the [common URL parameters]({{site.url}}{{site.baseurl}}/opensearch/rest-api/cat/index#common-url-parameters), you can specify the following parameters:
|
||||
|
||||
Parameter | Type | Description
|
||||
:--- | :--- | :---
|
||||
bytes | Byte size | Specify the units for byte size. For example, `7kb` or `6gb`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/opensearch/units/).
|
||||
full_id | Boolean | If true, return the full node ID. If false, return the shortened node ID. Defaults to false.
|
||||
local | Boolean | Whether to return information from the local node only instead of from the master node. Default is false.
|
||||
master_timeout | Time | The amount of time to wait for a connection to the master node. Default is 30 seconds.
|
||||
time | Time | Specify the units for time. For example, `5d` or `7h`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/opensearch/units/).
|
||||
include_unloaded_segments | Boolean | Whether to include information from segments not loaded into memory. Default is false.
|
||||
|
||||
|
||||
## Response
|
||||
|
||||
```json
|
||||
ip | heap.percent | ram.percent | cpu load_1m | load_5m | load_15m | node.role | master | name
|
||||
172.18.0.3 | 31 | 97 | 3 | 0.03 | 0.10 | 0.14 dimr | * | odfe-node2
|
||||
172.18.0.4 | 45 | 97 | 3 | 0.19 | 0.14 | 0.15 dimr | - | odfe-node1
|
||||
```
|
||||
@@ -1,46 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: cat pending tasks
|
||||
parent: CAT
|
||||
grand_parent: REST API reference
|
||||
nav_order: 45
|
||||
has_children: false
|
||||
---
|
||||
|
||||
# cat pending tasks
|
||||
Introduced 1.0
|
||||
{: .label .label-purple }
|
||||
|
||||
The cat pending tasks operation lists the progress of all pending tasks, including task priority and time in queue.
|
||||
|
||||
## Example
|
||||
|
||||
```
|
||||
GET _cat/pending_tasks?v
|
||||
```
|
||||
|
||||
## Path and HTTP methods
|
||||
|
||||
```
|
||||
GET _cat/pending_tasks
|
||||
```
|
||||
|
||||
## URL parameters
|
||||
|
||||
All cat nodes URL parameters are optional.
|
||||
|
||||
In addition to the [common URL parameters]({{site.url}}{{site.baseurl}}/opensearch/rest-api/cat/index#common-url-parameters), you can specify the following parameters:
|
||||
|
||||
Parameter | Type | Description
|
||||
:--- | :--- | :---
|
||||
local | Boolean | Whether to return information from the local node only instead of from the master node. Default is false.
|
||||
master_timeout | Time | The amount of time to wait for a connection to the master node. Default is 30 seconds.
|
||||
time | Time | Specify the units for time. For example, `5d` or `7h`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/opensearch/units/).
|
||||
|
||||
|
||||
## Response
|
||||
|
||||
```json
|
||||
insertOrder | timeInQueue | priority | source
|
||||
1786 | 1.8s | URGENT | shard-started
|
||||
```
|
||||
@@ -1,64 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: cat plugins
|
||||
parent: CAT
|
||||
grand_parent: REST API reference
|
||||
nav_order: 50
|
||||
has_children: false
|
||||
---
|
||||
|
||||
# cat plugins
|
||||
Introduced 1.0
|
||||
{: .label .label-purple }
|
||||
|
||||
The cat plugins operation lists the names, components, and versions of the installed plugins.
|
||||
|
||||
## Example
|
||||
|
||||
```
|
||||
GET _cat/plugins?v
|
||||
```
|
||||
|
||||
## Path and HTTP methods
|
||||
|
||||
```
|
||||
GET _cat/plugins
|
||||
```
|
||||
|
||||
## URL parameters
|
||||
|
||||
All cat plugins URL parameters are optional.
|
||||
|
||||
In addition to the [common URL parameters]({{site.url}}{{site.baseurl}}/opensearch/rest-api/cat/index#common-url-parameters), you can specify the following parameters:
|
||||
|
||||
Parameter | Type | Description
|
||||
:--- | :--- | :---
|
||||
local | Boolean | Whether to return information from the local node only instead of from the master node. Default is false.
|
||||
master_timeout | Time | The amount of time to wait for a connection to the master node. Default is 30 seconds.
|
||||
|
||||
|
||||
## Response
|
||||
|
||||
```json
|
||||
name component version
|
||||
odfe-node2 opendistro-alerting 1.13.1.0
|
||||
odfe-node2 opendistro-anomaly-detection 1.13.0.0
|
||||
odfe-node2 opendistro-asynchronous-search 1.13.0.1
|
||||
odfe-node2 opendistro-index-management 1.13.2.0
|
||||
odfe-node2 opendistro-job-scheduler 1.13.0.0
|
||||
odfe-node2 opendistro-knn 1.13.0.0
|
||||
odfe-node2 opendistro-performance-analyzer 1.13.0.0
|
||||
odfe-node2 opendistro-reports-scheduler 1.13.0.0
|
||||
odfe-node2 opendistro-sql 1.13.2.0
|
||||
odfe-node2 opendistro_security 1.13.1.0
|
||||
odfe-node1 opendistro-alerting 1.13.1.0
|
||||
odfe-node1 opendistro-anomaly-detection 1.13.0.0
|
||||
odfe-node1 opendistro-asynchronous-search 1.13.0.1
|
||||
odfe-node1 opendistro-index-management 1.13.2.0
|
||||
odfe-node1 opendistro-job-scheduler 1.13.0.0
|
||||
odfe-node1 opendistro-knn 1.13.0.0
|
||||
odfe-node1 opendistro-performance-analyzer 1.13.0.0
|
||||
odfe-node1 opendistro-reports-scheduler 1.13.0.0
|
||||
odfe-node1 opendistro-sql 1.13.2.0
|
||||
odfe-node1 opendistro_security 1.13.1.0
|
||||
```
|
||||
@@ -1,59 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: cat recovery
|
||||
parent: CAT
|
||||
grand_parent: REST API reference
|
||||
nav_order: 50
|
||||
has_children: false
|
||||
---
|
||||
|
||||
# cat recovery
|
||||
Introduced 1.0
|
||||
{: .label .label-purple }
|
||||
|
||||
The cat recovery operation lists all completed and ongoing index and shard recoveries.
|
||||
|
||||
## Example
|
||||
|
||||
```
|
||||
GET _cat/recovery?v
|
||||
```
|
||||
|
||||
To see only the recoveries of a specific index, add the index name after your query.
|
||||
|
||||
```
|
||||
GET _cat/recovery/<index>?v
|
||||
```
|
||||
|
||||
If you want to get information for more than one index, separate the indices with commas:
|
||||
|
||||
```json
|
||||
GET _cat/aliases/index1,index2,index3
|
||||
```
|
||||
|
||||
## Path and HTTP methods
|
||||
|
||||
```
|
||||
GET _cat/recovery
|
||||
```
|
||||
|
||||
## URL parameters
|
||||
|
||||
All cat recovery URL parameters are optional.
|
||||
|
||||
In addition to the [common URL parameters]({{site.url}}{{site.baseurl}}/opensearch/rest-api/cat/index#common-url-parameters), you can specify the following parameters:
|
||||
|
||||
Parameter | Type | Description
|
||||
:--- | :--- | :---
|
||||
active_only | Boolean | Whether to only include ongoing shard recoveries. Default is false.
|
||||
bytes | Byte size | Specify the units for byte size. For example, `7kb` or `6gb`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/opensearch/units/).
|
||||
detailed | Boolean | Whether to include detailed information about shard recoveries. Default is false.
|
||||
time | Time | Specify the units for time. For example, `5d` or `7h`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/opensearch/units/).
|
||||
|
||||
## Response
|
||||
|
||||
```json
|
||||
index | shard | time | type | stage | source_host | source_node | target_host | target_node | repository | snapshot | files | files_recovered | files_percent | files_total | bytes | bytes_recovered | bytes_percent | bytes_total | translog_ops | translog_ops_recovered | translog_ops_percent
|
||||
movies | 0 | 117ms | empty_store | done | n/a | n/a | 172.18.0.4 | odfe-node1 | n/a | n/a | 0 | 0 | 0.0% | 0 | 0 | 0 | 0.0% | 0 | 0 | 0 | 100.0%
|
||||
movies | 0 | 382ms | peer | done | 172.18.0.4 | odfe-node1 | 172.18.0.3 | odfe-node2 | n/a | n/a | 1 | 1 | 100.0% | 1 | 208 | 208 | 100.0% | 208 | 1 | 1 | 100.0%
|
||||
```
|
||||
@@ -1,46 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: cat repositories
|
||||
parent: CAT
|
||||
grand_parent: REST API reference
|
||||
nav_order: 55
|
||||
has_children: false
|
||||
---
|
||||
|
||||
# cat repositories
|
||||
Introduced 1.0
|
||||
{: .label .label-purple }
|
||||
|
||||
The cat repositories operation lists all completed and ongoing index and shard recoveries.
|
||||
|
||||
## Example
|
||||
|
||||
```
|
||||
GET _cat/repositories?v
|
||||
```
|
||||
|
||||
## Path and HTTP methods
|
||||
|
||||
```
|
||||
GET _cat/repositories
|
||||
```
|
||||
|
||||
## URL parameters
|
||||
|
||||
All cat repositories URL parameters are optional.
|
||||
|
||||
In addition to the [common URL parameters]({{site.url}}{{site.baseurl}}/opensearch/rest-api/cat/index#common-url-parameters), you can specify the following parameters:
|
||||
|
||||
Parameter | Type | Description
|
||||
:--- | :--- | :---
|
||||
local | Boolean | Whether to return information from the local node only instead of from the master node. Default is false.
|
||||
master_timeout | Time | The amount of time to wait for a connection to the master node. Default is 30 seconds.
|
||||
|
||||
|
||||
## Response
|
||||
|
||||
```json
|
||||
id type
|
||||
repo1 fs
|
||||
repo2 s3
|
||||
```
|
||||
@@ -1,57 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: cat segments
|
||||
parent: CAT
|
||||
grand_parent: REST API reference
|
||||
nav_order: 55
|
||||
has_children: false
|
||||
---
|
||||
|
||||
# cat segments
|
||||
Introduced 1.0
|
||||
{: .label .label-purple }
|
||||
|
||||
The cat segments operation lists Lucene segment-level information for each index.
|
||||
|
||||
## Example
|
||||
|
||||
```
|
||||
GET _cat/segments?v
|
||||
```
|
||||
|
||||
To see only the information about segments of a specific index, add the index name after your query.
|
||||
|
||||
```
|
||||
GET _cat/segments/<index>?v
|
||||
```
|
||||
|
||||
If you want to get information for more than one index, separate the indices with commas:
|
||||
|
||||
```
|
||||
GET _cat/segments/index1,index2,index3
|
||||
```
|
||||
|
||||
## Path and HTTP methods
|
||||
|
||||
```
|
||||
GET _cat/segments
|
||||
```
|
||||
|
||||
## URL parameters
|
||||
|
||||
All cat segments URL parameters are optional.
|
||||
|
||||
In addition to the [common URL parameters]({{site.url}}{{site.baseurl}}/opensearch/rest-api/cat/index#common-url-parameters), you can specify the following parameter:
|
||||
|
||||
Parameter | Type | Description
|
||||
:--- | :--- | :---
|
||||
bytes | Byte size | Specify the units for byte size. For example, `7kb` or `6gb`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/opensearch/units/)..
|
||||
|
||||
|
||||
## Response
|
||||
|
||||
```json
|
||||
index | shard | prirep | ip | segment | generation | docs.count | docs.deleted | size | size.memory | committed | searchable | version | compound
|
||||
movies | 0 | p | 172.18.0.4 | _0 | 0 | 1 | 0 | 3.5kb | 1364 | true | true | 8.7.0 | true
|
||||
movies | 0 | r | 172.18.0.3 | _0 | 0 | 1 | 0 | 3.5kb | 1364 | true | true | 8.7.0 | true
|
||||
```
|
||||
@@ -1,60 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: cat shards
|
||||
parent: CAT
|
||||
grand_parent: REST API reference
|
||||
nav_order: 60
|
||||
has_children: false
|
||||
---
|
||||
|
||||
# cat shards
|
||||
Introduced 1.0
|
||||
{: .label .label-purple }
|
||||
|
||||
The cat shards operation lists the state of all primary and replica shards and how they are distributed.
|
||||
|
||||
## Example
|
||||
|
||||
```
|
||||
GET _cat/shards?v
|
||||
```
|
||||
|
||||
To see only the information about shards of a specific index, add the index name after your query.
|
||||
|
||||
```
|
||||
GET _cat/shards/<index>?v
|
||||
```
|
||||
|
||||
If you want to get information for more than one index, separate the indices with commas:
|
||||
|
||||
```
|
||||
GET _cat/shards/index1,index2,index3
|
||||
```
|
||||
|
||||
## Path and HTTP methods
|
||||
|
||||
```
|
||||
GET _cat/shards
|
||||
```
|
||||
|
||||
## URL parameters
|
||||
|
||||
All cat shards URL parameters are optional.
|
||||
|
||||
In addition to the [common URL parameters]({{site.url}}{{site.baseurl}}/opensearch/rest-api/cat/index#common-url-parameters), you can specify the following parameter:
|
||||
|
||||
Parameter | Type | Description
|
||||
:--- | :--- | :---
|
||||
bytes | Byte size | Specify the units for byte size. For example, `7kb` or `6gb`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/opensearch/units/).
|
||||
local | Boolean | Whether to return information from the local node only instead of from the master node. Default is false.
|
||||
master_timeout | Time | The amount of time to wait for a connection to the master node. Default is 30 seconds.
|
||||
time | Time | Specify the units for time. For example, `5d` or `7h`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/opensearch/units/).
|
||||
|
||||
|
||||
## Response
|
||||
|
||||
```json
|
||||
index | shard | prirep | state | docs | store | ip | | node
|
||||
plugins | 0 | p | STARTED | 0 | 208b | 172.18.0.4 | odfe-node1
|
||||
plugins | 0 | r | STARTED | 0 | 208b | 172.18.0.3 | odfe-node2
|
||||
```
|
||||
@@ -1,46 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: cat snapshots
|
||||
parent: CAT
|
||||
grand_parent: REST API reference
|
||||
nav_order: 65
|
||||
has_children: false
|
||||
---
|
||||
|
||||
# cat snapshots
|
||||
Introduced 1.0
|
||||
{: .label .label-purple }
|
||||
|
||||
The cat snapshots operation lists all snapshots for a repository.
|
||||
|
||||
## Example
|
||||
|
||||
```
|
||||
GET _cat/snapshots?v
|
||||
```
|
||||
|
||||
## Path and HTTP methods
|
||||
|
||||
```
|
||||
GET _cat/snapshots
|
||||
```
|
||||
|
||||
## URL parameters
|
||||
|
||||
All cat snapshots URL parameters are optional.
|
||||
|
||||
In addition to the [common URL parameters]({{site.url}}{{site.baseurl}}/opensearch/rest-api/cat/index#common-url-parameters), you can specify the following parameter:
|
||||
|
||||
Parameter | Type | Description
|
||||
:--- | :--- | :---
|
||||
master_timeout | Time | The amount of time to wait for a connection to the master node. Default is 30 seconds.
|
||||
time | Time | Specify the units for time. For example, `5d` or `7h`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/opensearch/units/).
|
||||
|
||||
|
||||
## Response
|
||||
|
||||
```json
|
||||
index | shard | prirep | state | docs | store | ip | | node
|
||||
plugins | 0 | p | STARTED | 0 | 208b | 172.18.0.4 | odfe-node1
|
||||
plugins | 0 | r | STARTED | 0 | 208b | 172.18.0.3 | odfe-node2
|
||||
```
|
||||
@@ -1,47 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: cat tasks
|
||||
parent: CAT
|
||||
grand_parent: REST API reference
|
||||
nav_order: 70
|
||||
has_children: false
|
||||
---
|
||||
|
||||
# cat tasks
|
||||
Introduced 1.0
|
||||
{: .label .label-purple }
|
||||
|
||||
The cat tasks operation lists the progress of all tasks currently running on your cluster.
|
||||
|
||||
## Example
|
||||
|
||||
```
|
||||
GET _cat/tasks?v
|
||||
```
|
||||
|
||||
## Path and HTTP methods
|
||||
|
||||
```
|
||||
GET _cat/tasks
|
||||
```
|
||||
|
||||
## URL parameters
|
||||
|
||||
All cat tasks URL parameters are optional.
|
||||
|
||||
In addition to the [common URL parameters]({{site.url}}{{site.baseurl}}/opensearch/rest-api/cat/index#common-url-parameters), you can specify the following parameter:
|
||||
|
||||
Parameter | Type | Description
|
||||
:--- | :--- | :---
|
||||
nodes | List | A comma-separated list of node IDs or names to limit the returned information. Use `_local` to return information from the node you're connecting to, specify the node name to get information from specific nodes, or keep the parameter empty to get information from all nodes.
|
||||
detailed | Boolean | Returns detailed task information. (Default: false)
|
||||
parent_task_id | String | Returns tasks with a specified parent task ID (node_id:task_number). Keep empty or set to -1 to return all.
|
||||
time | Time | Specify the units for time. For example, `5d` or `7h`. For more information, see [Supported units]({{site.url}}{{site.baseurl}}/opensearch/units/).
|
||||
|
||||
|
||||
## Response
|
||||
|
||||
```json
|
||||
action | task_id | parent_task_id | type | start_time | timestamp | running_time | ip | node
|
||||
cluster:monitor/tasks/lists | 1vo54NuxSxOrbPEYdkSF0w:168062 | - | transport | 1624337809471 | 04:56:49 | 489.5ms | 172.18.0.4 | odfe-node1
|
||||
```
|
||||
@@ -1,53 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: cat templates
|
||||
parent: CAT
|
||||
grand_parent: REST API reference
|
||||
nav_order: 70
|
||||
has_children: false
|
||||
---
|
||||
|
||||
# cat templates
|
||||
Introduced 1.0
|
||||
{: .label .label-purple }
|
||||
|
||||
The cat templates operation lists the names, patterns, order numbers, and version numbers of index templates.
|
||||
|
||||
## Example
|
||||
|
||||
```
|
||||
GET _cat/templates?v
|
||||
```
|
||||
|
||||
If you want to get information for more than one template, separate the template names with commas:
|
||||
|
||||
```
|
||||
GET _cat/shards/template_name_1,template_name_2,template_name_3
|
||||
```
|
||||
|
||||
## Path and HTTP methods
|
||||
|
||||
```
|
||||
GET _cat/templates
|
||||
```
|
||||
|
||||
## URL parameters
|
||||
|
||||
All cat templates URL parameters are optional.
|
||||
|
||||
In addition to the [common URL parameters]({{site.url}}{{site.baseurl}}/opensearch/rest-api/cat/index#common-url-parameters), you can specify the following parameter:
|
||||
|
||||
Parameter | Type | Description
|
||||
:--- | :--- | :---
|
||||
local | Boolean | Whether to return information from the local node only instead of from the master node. Default is false.
|
||||
master_timeout | Time | The amount of time to wait for a connection to the master node. Default is 30 seconds.
|
||||
|
||||
|
||||
## Response
|
||||
|
||||
```
|
||||
name | index_patterns order version composed_of
|
||||
tenant_template | [kibana*] | 0 |
|
||||
```
|
||||
|
||||
To learn more about index templates, see [Index templates]({{site.url}}{{site.baseurl}}/opensearch/index-templates).
|
||||
@@ -1,53 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: cat thread pool
|
||||
parent: CAT
|
||||
grand_parent: REST API reference
|
||||
nav_order: 75
|
||||
has_children: false
|
||||
---
|
||||
|
||||
# cat thread pool
|
||||
Introduced 1.0
|
||||
{: .label .label-purple }
|
||||
|
||||
The cat thread pool operation lists the active, queued, and rejected threads of different thread pools on each node.
|
||||
|
||||
## Example
|
||||
|
||||
```
|
||||
GET _cat/thread_pool?v
|
||||
```
|
||||
|
||||
If you want to get information for more than one thread pool, separate the thread pool names with commas:
|
||||
|
||||
```
|
||||
GET _cat/v/thread_pool_name_1,thread_pool_name_2,thread_pool_name_3
|
||||
```
|
||||
|
||||
## Path and HTTP methods
|
||||
|
||||
```
|
||||
GET _cat/thread_pool
|
||||
```
|
||||
|
||||
## URL parameters
|
||||
|
||||
All cat thread pool URL parameters are optional.
|
||||
|
||||
In addition to the [common URL parameters]({{site.url}}{{site.baseurl}}/opensearch/rest-api/cat/index#common-url-parameters), you can specify the following parameter:
|
||||
|
||||
Parameter | Type | Description
|
||||
:--- | :--- | :---
|
||||
local | Boolean | Whether to return information from the local node only instead of from the master node. Default is false.
|
||||
master_timeout | Time | The amount of time to wait for a connection to the master node. Default is 30 seconds.
|
||||
|
||||
|
||||
## Response
|
||||
|
||||
```json
|
||||
node_name name active queue rejected
|
||||
odfe-node2 ad-batch-task-threadpool 0 0 0
|
||||
odfe-node2 ad-threadpool 0 0 0
|
||||
odfe-node2 analyze 0 0 0s
|
||||
```
|
||||
@@ -1,58 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: CAT
|
||||
parent: REST API reference
|
||||
nav_order: 100
|
||||
has_children: true
|
||||
redirect_from:
|
||||
- /opensearch/catapis/
|
||||
---
|
||||
|
||||
# cat API
|
||||
|
||||
You can get essential statistics about your cluster in an easy-to-understand, tabular format using the compact and aligned text (CAT) API. The cat API is a human-readable interface that returns plain text instead of traditional JSON.
|
||||
|
||||
Using the cat API, you can answer questions like which node is the elected master, what state is the cluster in, how many documents are in each index, and so on.
|
||||
|
||||
## Example
|
||||
|
||||
To see the available operations in the cat API, use the following command:
|
||||
|
||||
```
|
||||
GET _cat
|
||||
```
|
||||
|
||||
## Common URL parameters
|
||||
|
||||
You can use the following string parameters with your query.
|
||||
|
||||
Parameter | Description
|
||||
:--- | :--- |
|
||||
`?v` | Makes the output more verbose by adding headers to the columns. It also adds some formatting to help align each of the columns together. All examples in this section include the `v` parameter.
|
||||
`?help` | Lists the default and other available headers for a given operation.
|
||||
`?h` | Limits the output to specific headers.
|
||||
`?format` | Outputs the result in JSON, YAML, or CBOR formats.
|
||||
`?sort` | Sorts the output by the specified columns.
|
||||
|
||||
To see what each column represents, use the `?v` parameter:
|
||||
|
||||
```
|
||||
GET _cat/<operation_name>?v
|
||||
```
|
||||
|
||||
To see all the available headers, use the `?help` parameter:
|
||||
|
||||
```
|
||||
GET _cat/<operation_name>?help
|
||||
```
|
||||
|
||||
To limit the output to a subset of headers, use the `?h` parameter:
|
||||
|
||||
```
|
||||
GET _cat/<operation_name>?h=<header_name_1>,<header_name_2>&v
|
||||
```
|
||||
|
||||
Typically, for any operation you can find out what headers are available using the `?help` parameter, and then use the `?h` parameter to limit the output to only the headers that you care about.
|
||||
|
||||
If you use the security plugin, make sure you have the appropriate permissions.
|
||||
{: .note }
|
||||
@@ -1,146 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Cluster allocation explain
|
||||
parent: REST API reference
|
||||
nav_order: 10
|
||||
---
|
||||
|
||||
# Cluster allocation explain
|
||||
Introduced 1.0
|
||||
{: .label .label-purple }
|
||||
|
||||
The most basic cluster allocation explain request finds an unassigned shard and explains why it can't be allocated to a node.
|
||||
|
||||
If you add some options, you can instead get information on a specific shard, including why OpenSearch assigned it to its current node.
|
||||
|
||||
|
||||
## Example
|
||||
|
||||
```json
|
||||
GET _cluster/allocation/explain?include_yes_decisions=true
|
||||
{
|
||||
"index": "movies",
|
||||
"shard": 0,
|
||||
"primary": true
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
## Path and HTTP methods
|
||||
|
||||
```
|
||||
GET _cluster/allocation/explain
|
||||
POST _cluster/allocation/explain
|
||||
```
|
||||
|
||||
|
||||
## URL parameters
|
||||
|
||||
All cluster allocation explain parameters are optional.
|
||||
|
||||
Parameter | Type | Description
|
||||
:--- | :--- | :---
|
||||
include_yes_decisions | Boolean | OpenSearch makes a series of yes or no decisions when trying to allocate a shard to a node. If this parameter is true, OpenSearch includes the (generally more numerous) "yes" decisions in its response. Default is false.
|
||||
include_disk_info | Boolean | Whether to include information about disk usage in the response. Default is false.
|
||||
|
||||
|
||||
## Request body
|
||||
|
||||
All cluster allocation explain fields are optional.
|
||||
|
||||
Field | Type | Description
|
||||
:--- | :--- | :---
|
||||
current_node | String | If you only want an explanation if the shard happens to be on a particular node, specify that node name here.
|
||||
index | String | The name of the shard's index.
|
||||
primary | Boolean | Whether to provide an explanation for the primary shard (true) or its first replica (false), which share the same shard ID.
|
||||
shard | Integer | The shard ID that you want an explanation for.
|
||||
|
||||
|
||||
## Response
|
||||
|
||||
```json
|
||||
{
|
||||
"index": "movies",
|
||||
"shard": 0,
|
||||
"primary": true,
|
||||
"current_state": "started",
|
||||
"current_node": {
|
||||
"id": "d8jRZcW1QmCBeVFlgOJx5A",
|
||||
"name": "opensearch-node1",
|
||||
"transport_address": "172.24.0.4:9300",
|
||||
"weight_ranking": 1
|
||||
},
|
||||
"can_remain_on_current_node": "yes",
|
||||
"can_rebalance_cluster": "yes",
|
||||
"can_rebalance_to_other_node": "no",
|
||||
"rebalance_explanation": "cannot rebalance as no target node exists that can both allocate this shard and improve the cluster balance",
|
||||
"node_allocation_decisions": [{
|
||||
"node_id": "vRxi4uPcRt2BtHlFoyCyTQ",
|
||||
"node_name": "opensearch-node2",
|
||||
"transport_address": "172.24.0.3:9300",
|
||||
"node_decision": "no",
|
||||
"weight_ranking": 1,
|
||||
"deciders": [{
|
||||
"decider": "max_retry",
|
||||
"decision": "YES",
|
||||
"explanation": "shard has no previous failures"
|
||||
},
|
||||
{
|
||||
"decider": "replica_after_primary_active",
|
||||
"decision": "YES",
|
||||
"explanation": "shard is primary and can be allocated"
|
||||
},
|
||||
{
|
||||
"decider": "enable",
|
||||
"decision": "YES",
|
||||
"explanation": "all allocations are allowed"
|
||||
},
|
||||
{
|
||||
"decider": "node_version",
|
||||
"decision": "YES",
|
||||
"explanation": "can relocate primary shard from a node with version [1.0.0] to a node with equal-or-newer version [1.0.0]"
|
||||
},
|
||||
{
|
||||
"decider": "snapshot_in_progress",
|
||||
"decision": "YES",
|
||||
"explanation": "no snapshots are currently running"
|
||||
},
|
||||
{
|
||||
"decider": "restore_in_progress",
|
||||
"decision": "YES",
|
||||
"explanation": "ignored as shard is not being recovered from a snapshot"
|
||||
},
|
||||
{
|
||||
"decider": "filter",
|
||||
"decision": "YES",
|
||||
"explanation": "node passes include/exclude/require filters"
|
||||
},
|
||||
{
|
||||
"decider": "same_shard",
|
||||
"decision": "NO",
|
||||
"explanation": "a copy of this shard is already allocated to this node [[movies][0], node[vRxi4uPcRt2BtHlFoyCyTQ], [R], s[STARTED], a[id=x8w7QxWdQQa188HKGn0iMQ]]"
|
||||
},
|
||||
{
|
||||
"decider": "disk_threshold",
|
||||
"decision": "YES",
|
||||
"explanation": "enough disk for shard on node, free: [35.9gb], shard size: [15.1kb], free after allocating shard: [35.9gb]"
|
||||
},
|
||||
{
|
||||
"decider": "throttling",
|
||||
"decision": "YES",
|
||||
"explanation": "below shard recovery limit of outgoing: [0 < 2] incoming: [0 < 2]"
|
||||
},
|
||||
{
|
||||
"decider": "shards_limit",
|
||||
"decision": "YES",
|
||||
"explanation": "total shard limits are disabled: [index: -1, cluster: -1] <= 0"
|
||||
},
|
||||
{
|
||||
"decider": "awareness",
|
||||
"decision": "YES",
|
||||
"explanation": "allocation awareness is not enabled, set cluster setting [cluster.routing.allocation.awareness.attributes] to enable it"
|
||||
}
|
||||
]
|
||||
}]
|
||||
}
|
||||
```
|
||||
@@ -1,73 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Cluster health
|
||||
parent: REST API reference
|
||||
nav_order: 15
|
||||
---
|
||||
|
||||
# Cluster health
|
||||
Introduced 1.0
|
||||
{: .label .label-purple }
|
||||
|
||||
The most basic cluster health request returns a simple status of the health of your cluster. OpenSearch expresses cluster health in three colors: green, yellow, and red. A green status means all primary shards and their replicas are allocated to nodes. A yellow status means all primary shards are allocated to nodes, but some replicas aren't. A red status means at least one primary shard is not allocated to any node.
|
||||
|
||||
To get the status of a specific index, provide the index name.
|
||||
|
||||
## Example
|
||||
|
||||
This request waits 50 seconds for the cluster to reach the yellow status or better:
|
||||
|
||||
```
|
||||
GET _cluster/health?wait_for_status=yellow&timeout=50s
|
||||
```
|
||||
|
||||
If the cluster health becomes yellow or green before 50 seconds elapse, it returns a response immediately. Otherwise it returns a response as soon as it exceeds the timeout.
|
||||
|
||||
## Path and HTTP methods
|
||||
|
||||
```
|
||||
GET _cluster/health
|
||||
GET _cluster/health/<index>
|
||||
```
|
||||
|
||||
## URL parameters
|
||||
|
||||
All cluster health parameters are optional.
|
||||
|
||||
Parameter | Type | Description
|
||||
:--- | :--- | :---
|
||||
expand_wildcards | Enum | Expands wildcard expressions to concrete indices. Combine multiple values with commas. Supported values are `all`, `open`, `closed`, `hidden`, and `none`. Default is `open`.
|
||||
level | Enum | The level of detail for returned health information. Supported values are `cluster`, `indices`, and `shards`. Default is `cluster`.
|
||||
local | Boolean | Whether to return information from the local node only instead of from the master node. Default is false.
|
||||
master_timeout | Time | The amount of time to wait for a connection to the master node. Default is 30 seconds.
|
||||
timeout | Time | The amount of time to wait for a response. If the timeout expires, the request fails. Default is 30 seconds.
|
||||
wait_for_active_shards | String | Wait until the specified number of shards is active before returning a response. `all` for all shards. Default is `0`.
|
||||
wait_for_events | Enum | Wait until all currently queued events with the given priority are processed. Supported values are `immediate`, `urgent`, `high`, `normal`, `low`, and `languid`.
|
||||
wait_for_no_relocating_shards | Boolean | Whether to wait until there are no relocating shards in the cluster. Default is false.
|
||||
wait_for_no_initializing_shards | Boolean | Whether to wait until there are no initializing shards in the cluster. Default is false.
|
||||
wait_for_status | Enum | Wait until the cluster is in a specific state or better. Supported values are `green`, `yellow`, and `red`.
|
||||
|
||||
<!-- wait_for_nodes | string | Wait until the specified number of nodes is available. Also supports operators <=, >=, <, and >
|
||||
# Not working properly when tested -->
|
||||
|
||||
## Response
|
||||
|
||||
```json
|
||||
{
|
||||
"cluster_name" : "opensearch-cluster",
|
||||
"status" : "green",
|
||||
"timed_out" : false,
|
||||
"number_of_nodes" : 2,
|
||||
"number_of_data_nodes" : 2,
|
||||
"active_primary_shards" : 6,
|
||||
"active_shards" : 12,
|
||||
"relocating_shards" : 0,
|
||||
"initializing_shards" : 0,
|
||||
"unassigned_shards" : 0,
|
||||
"delayed_unassigned_shards" : 0,
|
||||
"number_of_pending_tasks" : 0,
|
||||
"number_of_in_flight_fetch" : 0,
|
||||
"task_max_waiting_in_queue_millis" : 0,
|
||||
"active_shards_percent_as_number" : 100.0
|
||||
}
|
||||
```
|
||||
@@ -1,85 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Cluster settings
|
||||
parent: REST API reference
|
||||
nav_order: 20
|
||||
---
|
||||
|
||||
# Cluster settings
|
||||
Introduced 1.0
|
||||
{: .label .label-purple }
|
||||
|
||||
The cluster settings operation lets you check the current settings for your cluster, review default settings, and change settings. When you update a setting using the API, OpenSearch applies it to all nodes in the cluster.
|
||||
|
||||
|
||||
## Examples
|
||||
|
||||
```json
|
||||
GET _cluster/settings?include_defaults=true
|
||||
```
|
||||
|
||||
```json
|
||||
PUT _cluster/settings
|
||||
{
|
||||
"persistent": {
|
||||
"action": {
|
||||
"auto_create_index": false
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
## Path and HTTP methods
|
||||
|
||||
```
|
||||
GET _cluster/settings
|
||||
PUT _cluster/settings
|
||||
```
|
||||
|
||||
|
||||
## URL parameters
|
||||
|
||||
All cluster settings parameters are optional.
|
||||
|
||||
Parameter | Type | Description
|
||||
:--- | :--- | :---
|
||||
flat_settings | Boolean | Whether to return settings in the flat form, which can improve readability, especially for heavily nested settings. For example, the flat form of `"cluster": { "max_shards_per_node": 500 }` is `"cluster.max_shards_per_node": "500"`.
|
||||
include_defaults (GET only) | Boolean | Whether to include default settings as part of the response. This parameter is useful for identifying the names and current values of settings you want to update.
|
||||
master_timeout | Time | The amount of time to wait for a response from the master node. Default is 30 seconds.
|
||||
timeout (PUT only) | Time | The amount of time to wait for a response from the cluster. Default is 30 seconds.
|
||||
|
||||
|
||||
## Request body
|
||||
|
||||
The GET operation has no request body options.
|
||||
|
||||
For a PUT operation, the request body must contain `transient` or `persistent`, along with the setting you want to update:
|
||||
|
||||
```json
|
||||
PUT _cluster/settings
|
||||
{
|
||||
"persistent": {
|
||||
"cluster": {
|
||||
"max_shards_per_node": 500
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
For more information about transient settings, persistent settings, and precedence, see [OpenSearch configuration]({{site.url}}{{site.baseurl}}/opensearch/configuration/).
|
||||
|
||||
|
||||
## Response
|
||||
|
||||
```json
|
||||
{
|
||||
"acknowledged": true,
|
||||
"persistent": {
|
||||
"cluster": {
|
||||
"max_shards_per_node": "500"
|
||||
}
|
||||
},
|
||||
"transient": {}
|
||||
}
|
||||
```
|
||||
@@ -1,103 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Count
|
||||
parent: REST API reference
|
||||
nav_order: 150
|
||||
---
|
||||
|
||||
# Count
|
||||
Introduced 1.0
|
||||
{: .label .label-purple }
|
||||
|
||||
The count API gives you quick access to the number of documents that match a query.
|
||||
You can also use it to check the document count of an index, data stream, or cluster.
|
||||
|
||||
|
||||
## Example
|
||||
|
||||
To see the number of documents that match a query:
|
||||
|
||||
```json
|
||||
GET opensearch_dashboards_sample_data_logs/_count
|
||||
{
|
||||
"query": {
|
||||
"term": {
|
||||
"response": "200"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The following call to the search API produces equivalent results:
|
||||
|
||||
```json
|
||||
GET opensearch_dashboards_sample_data_logs/_search
|
||||
{
|
||||
"query": {
|
||||
"term": {
|
||||
"response": "200"
|
||||
}
|
||||
},
|
||||
"size": 0,
|
||||
"track_total_hits": true
|
||||
}
|
||||
```
|
||||
|
||||
To see the number of documents in an index:
|
||||
|
||||
```json
|
||||
GET opensearch_dashboards_sample_data_logs/_count
|
||||
```
|
||||
|
||||
To check for the number of documents in a [data stream]({{site.url}}{{site.baseurl}}/opensearch/data-streams/), replace the index name with the data stream name.
|
||||
|
||||
To see the number of documents in your cluster:
|
||||
|
||||
```json
|
||||
GET _count
|
||||
```
|
||||
|
||||
Alternatively, you could use the [cat indices]({{site.url}}{{site.baseurl}}/opensearch/rest-api/cat/cat-indices/) and [cat count]({{site.url}}{{site.baseurl}}/opensearch/rest-api/cat/cat-count/) APIs to see the number of documents per index or data stream.
|
||||
{: .note }
|
||||
|
||||
|
||||
## Path and HTTP methods
|
||||
|
||||
```
|
||||
GET <target>/_count/<id>
|
||||
POST <target>/_count/<id>
|
||||
```
|
||||
|
||||
|
||||
## URL parameters
|
||||
|
||||
All count parameters are optional.
|
||||
|
||||
Parameter | Type | Description
|
||||
:--- | :--- | :---
|
||||
`allow_no_indices` | Boolean | If false, the request returns an error if any wildcard expression or index alias targets any closed or missing indices. Default is false.
|
||||
`analyzer` | String | The analyzer to use in the query string.
|
||||
`analyze_wildcard` | Boolean | Specifies whether to analyze wildcard and prefix queries. Default is false.
|
||||
`default_operator` | String | Indicates whether the default operator for a string query should be AND or OR. Default is OR.
|
||||
`df` | String | The default field in case a field prefix is not provided in the query string.
|
||||
`expand_wildcards` | String | Specifies the type of index that wildcard expressions can match. Supports comma-separated values. Valid values are `all` (match any index), `open` (match open, non-hidden indices), `closed` (match closed, non-hidden indices), `hidden` (match hidden indices), and `none` (deny wildcard expressions). Default is `open`.
|
||||
`ignore_unavailable` | Boolean | Specifies whether to include missing or closed indices in the response. Default is false.
|
||||
`lenient` | Boolean | Specifies whether OpenSearch should accept requests if queries have format errors (for example, querying a text field for an integer). Default is false.
|
||||
`min_score` | Float | Include only documents with a minimum `_score` value in the result.
|
||||
`routing` | String | Value used to route the operation to a specific shard.
|
||||
`preference` | String | Specifies which shard or node OpenSearch should perform the count operation on.
|
||||
`terminate_after` | Integer | The maximum number of documents OpenSearch should process before terminating the request.
|
||||
|
||||
## Response
|
||||
|
||||
```json
|
||||
{
|
||||
"count" : 14074,
|
||||
"_shards" : {
|
||||
"total" : 1,
|
||||
"successful" : 1,
|
||||
"skipped" : 0,
|
||||
"failed" : 0
|
||||
}
|
||||
}
|
||||
```
|
||||
@@ -1,163 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Create index
|
||||
parent: REST API reference
|
||||
nav_order: 3
|
||||
---
|
||||
|
||||
# Create index
|
||||
Introduced 1.0
|
||||
{: .label .label-purple }
|
||||
|
||||
While you can create an index by using a document as a base, you can also just create an empty index for use later.
|
||||
|
||||
## Example
|
||||
|
||||
The following example demonstrates how to create an index with a non-default number of primary and replica shards, specifies that `age` is of type `integer`, and assigns a `sample-alias1` alias to the index.
|
||||
|
||||
```json
|
||||
PUT /sample-index1
|
||||
|
||||
{
|
||||
"settings": {
|
||||
"index": {
|
||||
"number_of_shards": 2,
|
||||
"number_of_replicas": 1
|
||||
}
|
||||
},
|
||||
"mappings": {
|
||||
"properties": {
|
||||
"age": {
|
||||
"type": "integer"
|
||||
}
|
||||
}
|
||||
},
|
||||
"aliases": {
|
||||
"sample-alias1": {}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Path and HTTP methods
|
||||
|
||||
```
|
||||
PUT <index-name>
|
||||
```
|
||||
|
||||
## Index naming restrictions
|
||||
|
||||
OpenSearch indices have the following naming restrictions:
|
||||
|
||||
- All letters must be lowercase.
|
||||
- Index names can't begin with underscores (`_`) or hyphens (`-`).
|
||||
- Index names can't contain spaces, commas, or the following characters:
|
||||
|
||||
`:`, `"`, `*`, `+`, `/`, `\`, `|`, `?`, `#`, `>`, or `<`
|
||||
|
||||
## URL parameters
|
||||
|
||||
You can include the following URL parameters in your request. All parameters are optional.
|
||||
|
||||
Parameter | Type | Description
|
||||
:--- | :--- | :---
|
||||
include_type_name | Boolean | If `true`, the request expects a type in the body of mappings. Because OpenSearch indices all have a type of `_doc`, we recommend that this parameter is left as the default of `false.`
|
||||
wait_for_active_shards | String | Specifies the number of active shards that must be available before OpenSearch processes the request. Default is 1 (only the primary shard). Set to `all` or a positive integer. Values greater than 1 require replicas. For example, if you specify a value of 3, the index must have two replicas distributed across two additional nodes for the request to succeed.
|
||||
master_timeout | Time | How long to wait for a connection to the master node. Default is `30s`.
|
||||
timeout | Time | How long to wait for the request to return. Default is `30s`.
|
||||
|
||||
## Request body
|
||||
|
||||
As part of your request, you can supply parameters in your request's body that specify index settings, mappings, and [aliases]({{site.url}}{{site.baseurl}}/opensearch/index-alias/) for your newly created index. The following sections provide more information about index settings and mappings.
|
||||
|
||||
|
||||
### Index settings
|
||||
|
||||
Index settings are separated into two varieties: static index settings and dynamic index settings. Static index settings are settings that you specify at index creation and can't change later. You can change dynamic settings at any time, including at index creation.
|
||||
|
||||
#### Static index settings
|
||||
|
||||
Setting | Description
|
||||
:--- | :---
|
||||
index.number_of_shards | The number of primary shards in the index. Default is 1.
|
||||
index.number_of_routing_shards | The number of routing shards used to split an index.
|
||||
index.shard.check_on_startup | Whether the index's shards should be checked for corruption. Available options are `false` (do not check for corruption), `checksum` (check for physical corruption), and `true` (check for both physical and logical corruption). Default is `false`.
|
||||
index.codec | The compression type to use to compress stored data. Available values are `best_compression` and `default`.
|
||||
index.routing_partition_size | The number of shards a custom routing value can go to. Routing helps an imbalanced cluster by relocating values to a subset of shards rather than just a single shard. To enable, set this value to greater than 1 but less than `index.number_of_shards`. Default is 1.
|
||||
index.soft_deletes.retention_lease.period | The maximum amount of time to retain a shard's history of operations. Default is `12h`.
|
||||
index.load_fixed_bitset_filters_eagerly | Whether OpenSearch should pre-load cached filters. Available options are `true` and `false`. Default is `true`.
|
||||
index.hidden | Whether the index should be hidden. Hidden indices are not returned as part of queries that have wildcards. Available options are `true` and `false`. Default is `false`.
|
||||
|
||||
#### Dynamic index Settings
|
||||
|
||||
Setting | Description
|
||||
:--- | :---
|
||||
index.number_of_replicas | The number of replica shards each primary shard should have. For example, if you have 4 primary shards and set `index.number_of_replicas` to 3, the index has 12 replica shards. Default is 1.
|
||||
index.auto_expand_replicas | Whether the cluster should automatically add replica shards based on the number of data nodes. Specify a lower bound and upper limit (for example, 0-9), or `all` for the upper limit. For example, if you have 5 data nodes and set `index.auto_expand_replicas` to 0-3, then the cluster does not autoamtically add another replica shard. However, if you set this value to `0-all` and add 2 more nodes for a total of 7, the cluster will expand to now have 6 replica shards. Default is disabled.
|
||||
index.search.idle.after | Amount of time a shard should wait for a search or get request until it goes idle. Default is `30s`.
|
||||
index.refresh_interval | How often the index should refresh, which publishes its most recent changes and makes them available for searching. Can be set to `-1` to disable refreshing. Default is `1s`.
|
||||
index.max_result_window | The maximum value of `from` + `size` for searches to the index. `from` is the starting index to search from, and `size` is the amount of results to return. Default: 10000.
|
||||
index.max_inner_result_window | Maximum value of `from` + `size` to return nested search hits and most relevant document aggregated during the query. `from` is the starting index to search from, and `size` is the amount of top hits to return. Default is 100.
|
||||
index.max_rescore_window | The maximum value of `window_size` for rescore requests to the index. Rescore requests reorder the index's documents and return a new score, which can be more precise. Default is the same as index.max_inner_result_window or 10000 by default.
|
||||
index.max_docvalue_fields_search | Maximum amount of `docvalue_fields` allowed in a query. Default is 100.
|
||||
index.max_script_fields | Maximum amount of `script_fields` allowed in a query. Default is 32.
|
||||
index.max_ngram_diff | Maximum difference between `min_gram` and `max_gram` values for `NGramTokenizer` and `NGramTokenFilter` fields. Default is 1.
|
||||
index.max_shingle_diff | Maximum difference between `max_shingle_size` and `min_shingle_size` to feed into the `shingle` token filter. Default is 3.
|
||||
index.max_refresh_listeners | Maximum amount of refresh listeners each shard is allowed to have.
|
||||
index.analyze.max_token_count | Maximum amount of tokens that can return from the `_analyze` API operation. Default is 10000.
|
||||
index.highlight.max_analyzed_offset | The amount of characters a highlight request can analyze. Default is 1000000.
|
||||
index.max_terms_count | The maximum amount of terms a terms query can accept. Default is 65536.
|
||||
index.max_regex_length | The maximum character length of regex that can be in a regexp query. Default is 1000.
|
||||
index.query.default_field | A field or list of fields that OpenSearch uses in queries in case a field isn't specified in the parameters.
|
||||
index.routing.allocation.enable | Specifies options for the index’s shard allocation. Available options are all (allow allocation for all shards), primaries (allow allocation only for primary shards), new_primaries (allow allocation only for new primary shards), and none (do not allow allocation). Default is all.
|
||||
index.routing.rebalance.enable | Enables shard rebalancing for the index. Available options are `all` (allow rebalancing for all shards), `primaries` (allow rebalancing only for primary shards), `replicas` (allow rebalancing only for replicas), and `none` (do not allow rebalancing). Default is `all`.
|
||||
index.gc_deletes | Amount of time to retain a deleted document's version number. Default is `60s`.
|
||||
index.default_pipeline | The default ingest node pipeline for the index. If the default pipeline is set and the pipeline does not exist, then index requests fail. The pipeline name `_none` specifies that the index does not have an ingest pipeline.
|
||||
index.final_pipeline | The final ingest node pipeline for the index. If the final pipeline is set and the pipeline does not exist, then index requests fail. The pipeline name `_none` specifies that the index does not have an ingest pipeline.
|
||||
|
||||
|
||||
### Mappings
|
||||
|
||||
Mappings define how a documents and its fields are stored and indexed. If you're just starting to build out your cluster and data, you may not know exactly how your data should be stored. In those cases, you can use dynamic mappings, which tell OpenSearch to dynamically add data and their fields. However, if you know exactly what types your data fall under and want to enforce that standard, then you can use explicit mappings.
|
||||
|
||||
For example, if you want to indicate that `year` should be of type `text` instead of an `integer`, and `age` should be an `integer`, you can do so with explicit mappings. Using dynamic mapping, OpenSearch might interpret both `year` and `age` as integers.
|
||||
|
||||
#### Dynamic mapping types
|
||||
|
||||
Type | Description
|
||||
:--- | :---
|
||||
null | A `null` field can't be indexed or searched. When a field is set to null, OpenSearch behaves as if that field has no values.
|
||||
boolean | OpenSearch accepts `true` and `false` as boolean values. An empty string is equal to `false.`
|
||||
float | A single-precision 32-bit floating point number.
|
||||
double | A double-precision 64-bit floating point number.
|
||||
integer | A signed 32-bit number.
|
||||
object | Objects are standard JSON objects, which can have fields and mappings of their own. For example, a `movies` object can have additional properties such as `title`, `year`, and `director`.
|
||||
array | Arrays in OpenSearch can only store values of one type, such as an array of just integers or strings. Empty arrays are treated as though they are fields with no values.
|
||||
text | A string sequence of characters that represent full-text values.
|
||||
keyword | A string sequence of structured characters, such as an email or ZIP code.
|
||||
date detection string | Enabled by default, if new string fields match a date's format, then the string is processed as a `date` field. For example, `date: "2012/03/11"` is processed as a date.
|
||||
numeric detection string | If disabled, OpenSearch may automatically process numeric values as strings when they should be processed as numbers. When enabled, OpenSearch can process strings into `long`, `integer`, `short`, `byte`, `double`, `float`, `half_float`, `scaled_float`, `unsigned_long`. Default is disabled.
|
||||
|
||||
#### Explicit mapping
|
||||
|
||||
If you know exactly what your data's typings need to be, you can specify them in your request body when creating your index.
|
||||
|
||||
```json
|
||||
{
|
||||
"mappings": {
|
||||
"properties": {
|
||||
"year": { "type" : "text" },
|
||||
"age": { "type" : "integer" },
|
||||
"director":{ "type" : "text" }
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Response
|
||||
```json
|
||||
{
|
||||
"acknowledged": true,
|
||||
"shards_acknowledged": true,
|
||||
"index": "sample-index1"
|
||||
}
|
||||
```
|
||||
@@ -1,122 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Delete by query
|
||||
parent: Document APIs
|
||||
grand_parent: REST API reference
|
||||
nav_order: 40
|
||||
---
|
||||
|
||||
# Delete by query
|
||||
Introduced 1.0
|
||||
{: .label .label-purple}
|
||||
|
||||
You can include a query as part of your delete request so OpenSearch deletes all documents that match that query.
|
||||
|
||||
## Example
|
||||
|
||||
```json
|
||||
POST sample-index1/_delete_by_query
|
||||
{
|
||||
"query": {
|
||||
"match": {
|
||||
"movie-length": "124"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Path and HTTP methods
|
||||
|
||||
```
|
||||
POST <index>/_delete_by_query
|
||||
```
|
||||
|
||||
## URL parameters
|
||||
|
||||
All URL parameters are optional.
|
||||
|
||||
Parameter | Type | Description
|
||||
:--- | :--- | :--- | :---
|
||||
<index> | String | Name or list of the data streams, indices, or aliases to delete from. Supports wildcards. If left blank, OpenSearch searches all indices.
|
||||
allow_no_indices | Boolean | Whether to ignore wildcards that don’t match any indices. Default is `true`.
|
||||
analyzer | String | The analyzer to use in the query string.
|
||||
analyze_wildcard | Boolean | Specifies whether to analyze wildcard and prefix queries. Default is false.
|
||||
conflicts | String | Indicates to OpenSearch what should happen if the delete by query operation runs into a version conflict. Valid options are `abort` and `proceed`. Default is `abort`.
|
||||
default_operator | String | Indicates whether the default operator for a string query should be AND or OR. Default is OR.
|
||||
df | String | The default field in case a field prefix is not provided in the query string.
|
||||
expand_wildcards | String | Specifies the type of index that wildcard expressions can match. Supports comma-separated values. Valid values are `all` (match any index), `open` (match open, non-hidden indices), `closed` (match closed, non-hidden indices), `hidden` (match hidden indices), and `none` (deny wildcard expressions). Default is `open`.
|
||||
from | Integer | The starting index to search from. Default is 0.
|
||||
ignore_unavailable | Boolean | Specifies whether to include missing or closed indices in the response. Default is false.
|
||||
lenient | Boolean | Specifies whether OpenSearch should accept requests if queries have format errors (for example, querying a text field for an integer). Default is false.
|
||||
max_docs | Integer | How many documents the delete by query operation should process at most. Default is all documents.
|
||||
preference | String | Specifies which shard or node OpenSearch should perform the delete by query operation on.
|
||||
q | String | Lucene query string's query.
|
||||
request_cache | Boolean | Specifies whether OpenSearch should use the request cache. Default is whether it’s enabled in the index’s settings.
|
||||
refresh | Boolean | If true, OpenSearch refreshes shards to make the delete by query operation available to search results. Valid options are `true`, `false`, and `wait_for`, which tells OpenSearch to wait for a refresh before executing the operation. Default is `false`.
|
||||
requests_per_second | Integer | Specifies the request's throttling in sub-requests per second. Default is -1, which means no throttling.
|
||||
routing | String | Value used to route the operation to a specific shard.
|
||||
scroll | Time | Amount of time the search context should be open.
|
||||
scroll_size | Integer | Size of the operation's scroll requests. Default is 1000.
|
||||
search_type | String | Whether OpenSearch should use global term and document frequencies calculating revelance scores. Valid choices are `query_then_fetch` and `dfs_query_then_fetch`. `query_then_fetch` scores documents using local term and document frequencies for the shard. It’s usually faster but less accurate. `dfs_query_then_fetch` scores documents using global term and document frequencies across all shards. It’s usually slower but more accurate. Default is `query_then_fetch`.
|
||||
search_timeout | Time | How long to wait until OpenSearch deems the request timed out. Default is no timeout.
|
||||
sort | String | A comma-separated list of <field> : <direction> pairs to sort by.
|
||||
_source | String | Specifies whether to include the `_source` field in the response.
|
||||
_source_excludes | String | A comma-separated list of source fields to exclude from the response.
|
||||
_source_includes | String | A comma-separated list of source fields to include in the response.
|
||||
stats | String | Value to associate with the request for additional logging.
|
||||
terminate_after | Integer | The maximum number of documents OpenSearch should process before terminating the request.
|
||||
timeout | Time | How long the operation should wait from a response from active shards. Default is `1m`.
|
||||
version | Boolean | Whether to include the document version as a match.
|
||||
wait_for_active_shards | String | The number of shards that must be active before OpenSearch executes the operation. Valid values are `all` or any integer up to the total number of shards in the index. Default is 1, which is the primary shard.
|
||||
|
||||
## Request body
|
||||
|
||||
To search your index for specific documents, you must include a [query]({{site.url}}{{site.baseurl}}/opensearch/query-dsl/index) in the request body that OpenSearch uses to match documents. If you don't use a query, OpenSearch treats your delete request as a simple [delete document operation]({{site.url}}{{site.baseurl}}/opensearch/rest-api/document-apis/delete-document).
|
||||
|
||||
```json
|
||||
{
|
||||
"query": {
|
||||
"match": {
|
||||
"movie-length": "124"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Response
|
||||
```json
|
||||
{
|
||||
"took": 143,
|
||||
"timed_out": false,
|
||||
"total": 1,
|
||||
"deleted": 1,
|
||||
"batches": 1,
|
||||
"version_conflicts": 0,
|
||||
"noops": 0,
|
||||
"retries": {
|
||||
"bulk": 0,
|
||||
"search": 0
|
||||
},
|
||||
"throttled_millis": 0,
|
||||
"requests_per_second": -1.0,
|
||||
"throttled_until_millis": 0,
|
||||
"failures": []
|
||||
}
|
||||
```
|
||||
|
||||
## Response body fields
|
||||
|
||||
Field | Description
|
||||
:--- | :---
|
||||
took | The amount of time in milliseconds OpenSearch needed to complete the operation.
|
||||
timed_out | Whether any delete requests during the operation timed out.
|
||||
total | Total number of documents processed.
|
||||
deleted | Total number of documents deleted.
|
||||
batches | Number of scroll responses the request processed.
|
||||
version_conflicts | Number of conflicts the request ran into.
|
||||
noops | How many delete requests OpenSearch ignored during the operation. This field always returns 0.
|
||||
retries | The number of bulk and search retry requests.
|
||||
throttled_millis | Number of throttled milliseconds during the request.
|
||||
requests_per_second | Number of requests executed per second during the operation.
|
||||
throttled_until_millis | The amount of time until OpenSearch executes the next throttled request. Always equal to 0 in a delete by query request.
|
||||
failures | Any failures that occur during the request.
|
||||
@@ -1,75 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Delete document
|
||||
parent: Document APIs
|
||||
grand_parent: REST API reference
|
||||
nav_order: 15
|
||||
---
|
||||
|
||||
# Delete document
|
||||
Introduced 1.0
|
||||
{: .label .label-purple }
|
||||
|
||||
If you no longer need a document in your index, you can use the delete document API operation to delete it.
|
||||
|
||||
## Example
|
||||
|
||||
```
|
||||
DELETE /sample-index1/_doc/1
|
||||
```
|
||||
|
||||
## Path and HTTP methods
|
||||
|
||||
```
|
||||
DELETE /<index>/_doc/<_id>
|
||||
```
|
||||
|
||||
## URL parameters
|
||||
|
||||
Parameter | Type | Description | Required
|
||||
:--- | :--- | :--- | :---
|
||||
<index> | String | The index to delete from. | Yes
|
||||
<_id> | String | The ID of the document to delete. | Yes
|
||||
if_seq_no | Integer | Only perform the delete operation if the document's version number matches the specified number. | No
|
||||
if_primary_term | Integer | Only perform the delete operation if the document has the specified primary term. | No
|
||||
refresh | Enum | If true, OpenSearch refreshes shards to make the delete operation available to search results. Valid options are `true`, `false`, and `wait_for`, which tells OpenSearch to wait for a refresh before executing the operation. Default is `false`. | No
|
||||
routing | String | Value used to route the operation to a specific shard. | No
|
||||
timeout | Time | How long to wait for a response from the cluster. Default is `1m`. | No
|
||||
version | Integer | The version of the document to delete, which must match the last updated version of the document. | No
|
||||
version_type | Enum | Retrieves a specifically typed document. Available options are `external` (retrieve the document if the specified version number is greater than the document's current version) and `external_gte` (retrieve the document if the specified version number is greater than or equal to the document's current version). For example, to delete version 3 of a document, use `/_doc/1?version=3&version_type=external`. | No
|
||||
wait_for_active_shards | String | The number of active shards that must be available before OpenSearch processes the delete request. Default is 1 (only the primary shard). Set to `all` or a positive integer. Values greater than 1 require replicas. For example, if you specify a value of 3, the index must have two replicas distributed across two additional nodes for the operation to succeed. | No
|
||||
|
||||
|
||||
## Response
|
||||
```json
|
||||
{
|
||||
"_index": "sample-index1",
|
||||
"_type": "_doc",
|
||||
"_id": "1",
|
||||
"_version": 2,
|
||||
"result": "deleted",
|
||||
"_shards": {
|
||||
"total": 2,
|
||||
"successful": 2,
|
||||
"failed": 0
|
||||
},
|
||||
"_seq_no": 1,
|
||||
"_primary_term": 15
|
||||
}
|
||||
```
|
||||
|
||||
## Response body fields
|
||||
|
||||
Field | Description
|
||||
:--- | :---
|
||||
_index | The name of the index.
|
||||
_type | The document's type. OpenSearch only supports one type, which is `_doc`.
|
||||
_id | The document's ID.
|
||||
_version | The document's version.
|
||||
_result | The result of the delete operation.
|
||||
_shards | Detailed information about the cluster's shards.
|
||||
total | The total number of shards.
|
||||
successful | The number of shards OpenSearch succssfully deleted the document from.
|
||||
failed | The number of shards OpenSearch failed to delete the document from.
|
||||
_seq_no | The sequence number assigned when the document was indexed.
|
||||
_primary_term | The primary term assigned when the document was indexed.
|
||||
@@ -1,79 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Get document
|
||||
parent: Document APIs
|
||||
grand_parent: REST API reference
|
||||
nav_order: 5
|
||||
---
|
||||
|
||||
# Get document
|
||||
Introduced 1.0
|
||||
{: .label .label-purple }
|
||||
|
||||
After adding a JSON document to your index, you can use the get document API operation to retrieve the document's information and data.
|
||||
|
||||
## Example
|
||||
|
||||
```json
|
||||
GET sample-index1/_doc/1
|
||||
```
|
||||
|
||||
## Path and HTTP methods
|
||||
|
||||
```
|
||||
GET <index>/_doc/<_id>
|
||||
HEAD <index>/_doc/<_id>
|
||||
```
|
||||
```
|
||||
GET <index>/_source/<_id>
|
||||
HEAD <index>/_source/<_id>
|
||||
```
|
||||
|
||||
## URL parameters
|
||||
|
||||
All get document URL parameters are optional.
|
||||
|
||||
Parameter | Type | Description
|
||||
:--- | :--- | :---
|
||||
preference | String | Specifies a preference of which shard to retrieve results from. Available options are `_local`, which tells the operation to retrieve results from a locally allocated shard replica, and a custom string value assigned to a specific shard replica. By default, OpenSearch executes get document operations on random shards.
|
||||
realtime | Boolean | Specifies whether the operation should run in realtime. If false, the operation waits for the index to refresh to analyze the source to retrieve data, which makes the operation near-realtime. Default is true.
|
||||
refresh | Boolean | If true, OpenSearch refreshes shards to make the get operation available to search results. Valid options are `true`, `false`, and `wait_for`, which tells OpenSearch to wait for a refresh before executing the operation. Default is `false`.
|
||||
routing | String | A value used to route the operation to a specific shard.
|
||||
stored_fields | Boolean | Whether the get operation should retrieve fields stored in the index. Default is false.
|
||||
_source | String | Whether to include the `_source` field in the response body. Default is true.
|
||||
_source_excludes | String | A comma-separated list of source fields to exclude in the query response.
|
||||
_source_includes | String | A comma-separated list of source fields to include in the query response.
|
||||
version | Integer | The version of the document to return, which must match the current version of the document.
|
||||
version_type | Enum | Retrieves a specifically typed document. Available options are `external` (retrieve the document if the specified version number is greater than the document's current version) and `external_gte` (retrieve the document if the specified version number is greater than or equal to the document's current version). For example, to retrieve version 3 of a document, use `/_doc/1?version=3&version_type=external`.
|
||||
|
||||
|
||||
## Response
|
||||
```json
|
||||
{
|
||||
"_index": "sample-index1",
|
||||
"_type": "_doc",
|
||||
"_id": "1",
|
||||
"_version": 1,
|
||||
"_seq_no": 0,
|
||||
"_primary_term": 9,
|
||||
"found": true,
|
||||
"_source": {
|
||||
"text": "This is just some sample text."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Response body fields
|
||||
|
||||
Field | Description
|
||||
:--- | :---
|
||||
_index | The name of the index.
|
||||
_type | The document's type. OpenSearch only supports one type, which is `_doc`.
|
||||
_id | The document's ID.
|
||||
_version | The document's version number. Updated whenever the document changes.
|
||||
_seq_no | The sequnce number assigned when the document is indexed.
|
||||
primary_term | The primary term assigned when the document is indexed.
|
||||
found | Whether the document exists.
|
||||
_routing | The shard that the document is routed to. If the document is not routed to a particular shard, this field is omitted.
|
||||
_source | Contains the document's data if `found` is true. If `_source` is set to false or `stored_fields` is set to true in the URL parameters, this field is omitted.
|
||||
_fields | Contains the document's data that's stored in the index. Only returned if both `stored_fields` and `found` are true.
|
||||
@@ -1,95 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Index document
|
||||
parent: Document APIs
|
||||
grand_parent: REST API reference
|
||||
nav_order: 1
|
||||
---
|
||||
|
||||
# Index document
|
||||
Introduced 1.0
|
||||
{: .label .label-purple}
|
||||
|
||||
Before you can search for data, you must first add documents. This operation adds a single document to your index.
|
||||
|
||||
## Example
|
||||
|
||||
```json
|
||||
PUT sample-index/_doc/1
|
||||
{
|
||||
"Description": "To be or not to be, that is the question."
|
||||
}
|
||||
```
|
||||
|
||||
## Path and HTTP methods
|
||||
|
||||
```
|
||||
PUT <index>/_doc/<_id>
|
||||
POST <index>/_doc
|
||||
|
||||
PUT <index>/_create/<_id>
|
||||
POST <index>/_create/<_id>
|
||||
```
|
||||
|
||||
## URL parameters
|
||||
|
||||
In your request, you must specify the index you want to add your document to. If the index doesn't already exist, OpenSearch automatically creates the index and adds in your document. All other URL parameters are optional.
|
||||
|
||||
Parameter | Type | Description | Required
|
||||
:--- | :--- | :--- | :---
|
||||
<index> | String | Name of the index. | Yes
|
||||
<_id> | String | A unique identifier to attach to the document. To automatically generate an ID, use `POST <target>/doc` in your request instead of PUT. | No
|
||||
if_seq_no | Integer | Only perform the index operation if the document has the specified sequence number. | No
|
||||
if_primary_term | Integer | Only perform the index operation if the document has the specified primary term.| No
|
||||
op_type | Enum | Specifies the type of operation to complete with the document. Valid values are `create` (create the index if it doesn't exist) and `index`. If a document ID is included in the request, then the default is `index`. Otherwise, the default is `create`. | No
|
||||
pipeline | String | Route the index operation to a certain pipeline. | No
|
||||
routing | String | value used to assign the index operation to a specific shard. | No
|
||||
timeout | Time | How long to wait for a response from the cluster. Default is `1m`. | No
|
||||
version | Integer | The document's version number. | No
|
||||
version_type | Enum | Assigns a specific type to the document. Valid options are `external` (retrieve the document if the specified version number is greater than the document's current version) and `external_gte` (retrieve the document if the specified version number is greater than or equal to the document's current version). For example, to index version 3 of a document, use `/_doc/1?version=3&version_type=external`. | No
|
||||
wait_for_active_shards | String | The number of active shards that must be available before OpenSearch processes the request. Default is 1 (only the primary shard). Set to `all` or a positive integer. Values greater than 1 require replicas. For example, if you specify a value of 3, the index must have two replicas distributed across two additional nodes for the operation to succeed. | No
|
||||
require_alias | Boolean | Specifies whether the target index must be an index alias. Default is false. | No
|
||||
|
||||
## Request body
|
||||
|
||||
Your request body must contain the information you want to index.
|
||||
|
||||
```json
|
||||
{
|
||||
"Description": "This is just a sample document"
|
||||
}
|
||||
```
|
||||
|
||||
## Response
|
||||
```json
|
||||
{
|
||||
"_index": "sample-index",
|
||||
"_type": "_doc",
|
||||
"_id": "1",
|
||||
"_version": 1,
|
||||
"result": "created",
|
||||
"_shards": {
|
||||
"total": 2,
|
||||
"successful": 1,
|
||||
"failed": 0
|
||||
},
|
||||
"_seq_no": 0,
|
||||
"_primary_term": 1
|
||||
}
|
||||
```
|
||||
|
||||
## Response body fields
|
||||
|
||||
Field | Description
|
||||
:--- | :---
|
||||
_index | The name of the index.
|
||||
_type | The document's type. OpenSearch supports only one type, which is `_doc`.
|
||||
_id | The document's ID.
|
||||
_version | The document's version.
|
||||
result | The result of the index operation.
|
||||
_shards | Detailed information about the cluster's shards.
|
||||
total | The total number of shards.
|
||||
successful | The number of shards OpenSearch succssfully added the document to.
|
||||
failed | The number of shards OpenSearch failed to added the document to.
|
||||
_seq_no | The sequence number assigned when the document was indexed.
|
||||
_primary_term | The primary term assigned when the document was indexed.
|
||||
@@ -1,30 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Document APIs
|
||||
parent: REST API reference
|
||||
has_children: true
|
||||
nav_order: 7
|
||||
redirect_from:
|
||||
- /opensearch/rest-api/document-apis/
|
||||
---
|
||||
|
||||
# Document APIs
|
||||
|
||||
The document APIs allow you to handle documents relative to your index, such as adding, updating, and deleting documents.
|
||||
|
||||
Document APIs are separated into two categories: single document operations and multi-document operations. Multi-document operations offer performance advantages over submitting many individual requests, so whenever practical, we recommend that you use multi-document operations.
|
||||
|
||||
## Single document operations
|
||||
|
||||
- Index
|
||||
- Get
|
||||
- Delete
|
||||
- Update
|
||||
|
||||
## Multi-document operations
|
||||
|
||||
- Bulk
|
||||
- Multi get
|
||||
- Delete by query
|
||||
- Update by query
|
||||
- Reindex
|
||||
@@ -1,142 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Multi-get document
|
||||
parent: Document APIs
|
||||
grand_parent: REST API reference
|
||||
nav_order: 30
|
||||
---
|
||||
|
||||
# Multi-get documents
|
||||
Introduced 1.0
|
||||
{: .label .label-purple }
|
||||
|
||||
The multi-get operation allows you to execute multiple GET operations in one request, so you can get back all documents that match your criteria.
|
||||
|
||||
## Example without specifying index in URL
|
||||
|
||||
```json
|
||||
GET _mget
|
||||
{
|
||||
"docs": [
|
||||
{
|
||||
"_index": "sample-index1",
|
||||
"_id": "1"
|
||||
},
|
||||
{
|
||||
"_index": "sample-index2",
|
||||
"_id": "1",
|
||||
"_source": {
|
||||
"include": ["Length"]
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Example of specifying index in URL
|
||||
|
||||
```json
|
||||
GET sample-index1/_mget
|
||||
|
||||
{
|
||||
"docs": [
|
||||
{
|
||||
"_type": "_doc",
|
||||
"_id": "1",
|
||||
"_source": false
|
||||
},
|
||||
{
|
||||
"_type": "_doc",
|
||||
"_id": "2",
|
||||
"_source": [ "Director", "Title" ]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Path and HTTP methods
|
||||
|
||||
```
|
||||
GET _mget
|
||||
GET <index>/_mget
|
||||
```
|
||||
|
||||
## URL parameters
|
||||
|
||||
All multi-get URL parameters are optional.
|
||||
|
||||
Parameter | Type | Description
|
||||
:--- | :--- | :--- | :---
|
||||
<index> | String | Name of the index to retrieve documents from.
|
||||
preference | String | Specifies the nodes or shards OpenSearch should execute the multi-get operation on. Default is random.
|
||||
realtime | Boolean | Specifies whether the operation should run in realtime. If false, the operation waits for the index to refresh to analyze the source to retrieve data, which makes the operation near-realtime. Default is `true`.
|
||||
refresh | Boolean | If true, OpenSearch refreshes shards to make the multi-get operation available to search results. Valid options are `true`, `false`, and `wait_for`, which tells OpenSearch to wait for a refresh before executing the operation. Default is `false`.
|
||||
routing | String | Value used to route the multi-get operation to a specific shard.
|
||||
stored_fields | Boolean | Specifies whether OpenSearch should retrieve documents fields from the index instead of the document's `_source`. Default is `false`.
|
||||
_source | String | Whether to include the `_source` field in the query response. Default is `true`.
|
||||
_source_excludes | String | A comma-separated list of source fields to exclude in the query response.
|
||||
_source_includes | String | A comma-separated list of source fields to include in the query response.
|
||||
|
||||
## Request body
|
||||
|
||||
If you don't specify an index in your request's URL, you must specify your target indices and the relevant document IDs in the request body. Other fields are optional.
|
||||
|
||||
Field | Type | Description | Required
|
||||
:--- | :--- | :--- | :---
|
||||
docs | Array | The documents you want to retrieve data from. Can contain the attributes: `_id`, `_index`, `_routing`, `_source`, and `_stored_fields`. If you specify an index in the URL, you can omit this field and add IDs of the documents to retrieve. | Yes if an index is not specified in the URL
|
||||
_id | String | The ID of the document. | Yes if `docs` is specified in the request body
|
||||
_index | String | Name of the index. | Yes if an index is not specified in the URL
|
||||
_routing | String | The value of the shard that has the document. | Yes if a routing value was used when indexing the document
|
||||
_source | Object | Specifies whether to return the `_source` field from an index (boolean), whether to return specific fields (array), or whether to include or exclude certain fields. | No
|
||||
_source.includes | Array | Specifies which fields to include in the query response. For example, `"_source": { "include": ["Title"] }` retrieves `Title` from the index. | No
|
||||
_source.excludes | Array | Specifies which fields to exclude in the query response. For example, `"_source": { "exclude": ["Director"] }` excludes `Director` from the query response. | No
|
||||
ids | Array | IDs of the documents to retrieve. Only allowed when an index is specified in the URL. | No
|
||||
|
||||
## Response
|
||||
```json
|
||||
{
|
||||
"docs": [
|
||||
{
|
||||
"_index": "sample-index1",
|
||||
"_type": "_doc",
|
||||
"_id": "1",
|
||||
"_version": 4,
|
||||
"_seq_no": 5,
|
||||
"_primary_term": 19,
|
||||
"found": true,
|
||||
"_source": {
|
||||
"Title": "Batman Begins",
|
||||
"Director": "Christopher Nolan"
|
||||
}
|
||||
},
|
||||
{
|
||||
"_index": "sample-index2",
|
||||
"_type": "_doc",
|
||||
"_id": "1",
|
||||
"_version": 1,
|
||||
"_seq_no": 6,
|
||||
"_primary_term": 19,
|
||||
"found": true,
|
||||
"_source": {
|
||||
"Title": "The Dark Knight",
|
||||
"Director": "Christopher Nolan"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Response body fields
|
||||
|
||||
Field | Description
|
||||
:--- | :---
|
||||
_index | The name of the index.
|
||||
_type | The document's type. OpenSearch only supports one type, which is `_doc`.
|
||||
_id | The document's ID.
|
||||
_version | The document's version number. Updated whenever the document changes.
|
||||
_seq_no | The sequnce number assigned when the document is indexed.
|
||||
primary_term | The primary term assigned when the document is indexed.
|
||||
found | Whether the document exists.
|
||||
_routing | The shard that the document is routed to. If the document is not routed to a particular shard, this field is omitted.
|
||||
_source | Contains the document's data if `found` is true. If `_source` is set to false or `stored_fields` is set to true in the URL parameters, this field is omitted.
|
||||
_fields | Contains the document's data that's stored in the index. Only returned if both `stored_fields` and `found` are true.
|
||||
@@ -1,121 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Reindex
|
||||
parent: Document APIs
|
||||
grand_parent: REST API reference
|
||||
nav_order: 60
|
||||
---
|
||||
|
||||
# Index document
|
||||
Introduced 1.0
|
||||
{: .label .label-purple}
|
||||
|
||||
The reindex API operation lets you copy all or a subset of your data from a source index into a destination index.
|
||||
|
||||
## Example
|
||||
|
||||
```json
|
||||
POST /_reindex
|
||||
{
|
||||
"source":{
|
||||
"index":"my-source-index"
|
||||
},
|
||||
"dest":{
|
||||
"index":"my-destination-index"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Path and HTTP methods
|
||||
|
||||
```
|
||||
POST /_reindex
|
||||
```
|
||||
|
||||
## URL parameters
|
||||
|
||||
All URL parameters are optional.
|
||||
|
||||
Parameter | Type | Description
|
||||
:--- | :--- | :---
|
||||
refresh | Boolean | If true, OpenSearch refreshes shards to make the reindex operation available to search results. Valid options are `true`, `false`, and `wait_for`, which tells OpenSearch to wait for a refresh before executing the operation. Default is `false`.
|
||||
timeout | Time | How long to wait for a response from the cluster. Default is `30s`.
|
||||
wait_for_active_shards | String | The number of active shards that must be available before OpenSearch processes the reindex request. Default is 1 (only the primary shard). Set to `all` or a positive integer. Values greater than 1 require replicas. For example, if you specify a value of 3, the index must have two replicas distributed across two additional nodes for the operation to succeed.
|
||||
wait_for_completion | Boolean | Waits for the matching tasks to complete. Default is `false`.
|
||||
requests_per_second | Integer | Specifies the request’s throttling in sub-requests per second. Default is -1, which means no throttling.
|
||||
require_alias | Boolean | Whether the destination index must be an index alias. Default is false.
|
||||
scroll | Time | How long to keep the search context open. Default is `5m`.
|
||||
slices | Integer | Number of sub-tasks OpenSearch should divide this task into. Default is 1, which means OpenSearch should not divide this task. Setting this parameter to `auto` indicates to OpenSearch that it should automatically decide how many slices to split the task into.
|
||||
max_docs | Integer | How many documents the update by query operation should process at most. Default is all documents.
|
||||
|
||||
## Request body
|
||||
|
||||
Your request body must contain the names of the source index and destination index. All other fields are optional.
|
||||
|
||||
Field | Description
|
||||
:--- | :---
|
||||
conflicts | Indicates to OpenSearch what should happen if the delete by query operation runs into a version conflict. Valid options are `abort` and `proceed`. Default is abort.
|
||||
source | Information about the source index to include. Valid fields are `index`, `max_docs`, `query`, `remote`, `size`, `slice`, and `_source`.
|
||||
index | The name of the source index to copy data from.
|
||||
max_docs | The maximum number of documents to reindex.
|
||||
query | The search query to use for the reindex operation.
|
||||
remote | Information about a remote OpenSearch cluster to copy data from. Valid fields are `host`, `username`, `password`, `socket_timeout`, and `connect_timeout`.
|
||||
host | Host URL of the OpenSearch cluster to copy data from.
|
||||
username | Username to authenticate with the remote cluster.
|
||||
password | Password to authenticate with the remote cluster.
|
||||
socket_timeout | The wait time for socket reads. Default is 30s.
|
||||
connect_timeout | The wait time for remote connection timeouts. Default is 30s.
|
||||
size | The number of documents to reindex.
|
||||
slice | Whether to manually or automatically slice the reindex operation so it executes in parallel.
|
||||
_source | Whether to reindex source fields. Speicfy a list of fields to reindex or true to reindex all fields. Default is true.
|
||||
id | The ID to associate with manual slicing.
|
||||
max | Maximum number of slices.
|
||||
dest | Information about the destination index. Valid values are `index`, `version_type`, and `op_type`.
|
||||
index | Name of the destination index.
|
||||
version_type | The indexing operation's version type. Valid values are `internal`, `external`, `external_gt` (retrieve the document if the specified version number is greater than the document’s current version), and `external_gte` (retrieve the document if the specified version number is greater or equal to than the document’s current version).
|
||||
op_type | Whether to copy over documents that are missing in the destination index. Valid values are `create` (ignore documents with the same ID from the source index) and `index` (copy everything from the source index).
|
||||
script | A script that OpenSearch uses to apply transformations to the data during the reindex operation.
|
||||
source | The actual script that OpenSearch runs.
|
||||
lang | The scripting language. Valid options are `painless`, `expression`, `mustache`, and `java`.
|
||||
|
||||
## Response
|
||||
```json
|
||||
{
|
||||
"took": 28829,
|
||||
"timed_out": false,
|
||||
"total": 111396,
|
||||
"updated": 0,
|
||||
"created": 111396,
|
||||
"deleted": 0,
|
||||
"batches": 112,
|
||||
"version_conflicts": 0,
|
||||
"noops": 0,
|
||||
"retries": {
|
||||
"bulk": 0,
|
||||
"search": 0
|
||||
},
|
||||
"throttled_millis": 0,
|
||||
"requests_per_second": -1.0,
|
||||
"throttled_until_millis": 0,
|
||||
"failures": []
|
||||
}
|
||||
```
|
||||
|
||||
## Response body fields
|
||||
|
||||
Field | Description
|
||||
:--- | :---
|
||||
took | How long the operation took in milliseconds.
|
||||
timed_out | Whether the operation timed out.
|
||||
total | The total number of documents processed.
|
||||
updated | The number of documents updated in the destination index.
|
||||
created | The number of documents created in the destination index.
|
||||
deleted | The number of documents deleted.
|
||||
batches | Number of scroll responses.
|
||||
version_conflicts | Number of version conflicts.
|
||||
noops | How many documents OpenSearch ignored during the operation.
|
||||
retries | Number of bulk and search retry requests.
|
||||
throttled_millis | Number of throttled milliseconds during the request.
|
||||
requests_per_second | Number of requests executed per second during the operation.
|
||||
throttled_until_millis | The amount of time until OpenSearch executes the next throttled request.
|
||||
failures | Any failures that occurred during the operation.
|
||||
@@ -1,139 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Update by query
|
||||
parent: Document APIs
|
||||
grand_parent: REST API reference
|
||||
nav_order: 50
|
||||
---
|
||||
|
||||
# Update by query
|
||||
Introduced 1.0
|
||||
{: .label .label-purple}
|
||||
|
||||
You can include a query and a script as part of your update request so OpenSearch can run the script to update all of the documents that match the query.
|
||||
|
||||
## Example
|
||||
|
||||
```json
|
||||
POST test-index1/_update_by_query
|
||||
{
|
||||
"query": {
|
||||
"term": {
|
||||
"oldValue": 10
|
||||
}
|
||||
},
|
||||
"script" : {
|
||||
"source": "ctx._source.oldValue += params.newValue",
|
||||
"lang": "painless",
|
||||
"params" : {
|
||||
"newValue" : 20
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Path and HTTP methods
|
||||
|
||||
```
|
||||
POST <target-index1>, <target-index2>/_update_by_query
|
||||
```
|
||||
|
||||
## URL parameters
|
||||
|
||||
All URL parameters are optional.
|
||||
|
||||
Parameter | Type | Description
|
||||
:--- | :--- | :--- | :---
|
||||
<index> | String | Comma-separated list of indices to update. To update all indices, use * or omit this parameter.
|
||||
allow_no_indices | Boolean | Whether to ignore wildcards that don’t match any indices. Default is `true`.
|
||||
analyzer | String | Analyzer to use in the query string.
|
||||
analyze_wildcard | Boolean | Whether the update operation should include wildcard and prefix queries in the analysis. Default is false.
|
||||
conflicts | String | Indicates to OpenSearch what should happen if the update by query operation runs into a version conflict. Valid options are `abort` and `proceed`. Default is `abort`.
|
||||
default_operator | String | Indicates whether the default operator for a string query should be `AND` or `OR`. Default is `OR`.
|
||||
df | String | The default field if a field prefix is not provided in the query string.
|
||||
expand_wildcards | String | Specifies the type of index that wildcard expressions can match. Supports comma-separated values. Valid values are `all` (match any index), `open` (match open, non-hidden indices), `closed` (match closed, non-hidden indices), `hidden` (match hidden indices), and `none` (deny wildcard expressions). Default is `open`.
|
||||
from | Integer | The starting index to search from. Default is 0.
|
||||
ignore_unavailable | Boolean | Whether to exclude missing or closed indices in the response. Default is false.
|
||||
lenient | Boolean | Specifies whether OpenSearch should accept requests if queries have format errors (for example, querying a text field for an integer). Default is false.
|
||||
max_docs | Integer | How many documents the update by query operation should process at most. Default is all documents.
|
||||
pipeline | String | ID of the pipeline to use to process documents.
|
||||
preference | String | Specifies which shard or node OpenSearch should perform the update by query operation on.
|
||||
q | String | Lucene query string's query.
|
||||
request_cache | Boolean | Specifies whether OpenSearch should use the request cache. Default is whether it’s enabled in the index’s settings.
|
||||
refresh | Boolean | If true, OpenSearch refreshes shards to make the update by query operation available to search results. Valid options are `true`, `false`, and `wait_for`, which tells OpenSearch to wait for a refresh before executing the operation. Default is `false`.
|
||||
requests_per_second | Integer | Specifies the request's throttling in sub-requests per second. Default is -1, which means no throttling.
|
||||
routing | String | Value used to route the update by query operation to a specific shard.
|
||||
scroll | Time | How long to keep the search context open.
|
||||
scroll_size | Integer | Size of the operation's scroll request. Default is 1000.
|
||||
search_type | String | Whether OpenSearch should use global term and document frequencies calculating revelance scores. Valid choices are `query_then_fetch` and `dfs_query_then_fetch`. `query_then_fetch` scores documents using local term and document frequencies for the shard. It’s usually faster but less accurate. `dfs_query_then_fetch` scores documents using global term and document frequencies across all shards. It’s usually slower but more accurate. Default is `query_then_fetch`.
|
||||
search_timeout | Time | How long to wait until OpenSearch deems the request timed out. Default is no timeout.
|
||||
slices | Integer | Number of sub-tasks OpenSearch should divide this task into. Default is 1, which means OpenSearch should not divide this task.
|
||||
sort | List | A comma-separated list of <field> : <direction> pairs to sort by.
|
||||
_source | String | Whether to include the `_source` field in the response.
|
||||
_source_excludes | String | A comma-separated list of source fields to exclude from the response.
|
||||
_source_includes | String | A comma-separated list of source fields to include in the response.
|
||||
stats | String | Value to associate with the request for additional logging.
|
||||
terminate_after | Integer | The maximum number of documents OpenSearch should process before terminating the request.
|
||||
timeout | Time | How long the operation should wait from a response from active shards. Default is `1m`.
|
||||
version | Boolean | Whether to include the document version as a match.
|
||||
wait_for_active_shards | String | The number of shards that must be active before OpenSearch executes the operation. Valid values are `all` or any integer up to the total number of shards in the index. Default is 1, which is the primary shard.
|
||||
|
||||
## Request body
|
||||
|
||||
To update your indices and documents by query, you must include a [query]({{site.url}}{{site.baseurl}}/opensearch/query-dsl/index) and a script in the request body that OpenSearch can run to update your documents. If you don't specify a query, then every document in the index gets updated.
|
||||
|
||||
```json
|
||||
{
|
||||
"query": {
|
||||
"term": {
|
||||
"oldValue": 20
|
||||
}
|
||||
},
|
||||
"script" : {
|
||||
"source": "ctx._source.oldValue += params.newValue",
|
||||
"lang": "painless",
|
||||
"params" : {
|
||||
"newValue" : 10
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Response
|
||||
```json
|
||||
{
|
||||
"took": 21,
|
||||
"timed_out": false,
|
||||
"total": 1,
|
||||
"updated": 1,
|
||||
"deleted": 0,
|
||||
"batches": 1,
|
||||
"version_conflicts": 0,
|
||||
"noops": 0,
|
||||
"retries": {
|
||||
"bulk": 0,
|
||||
"search": 0
|
||||
},
|
||||
"throttled_millis": 0,
|
||||
"requests_per_second": -1.0,
|
||||
"throttled_until_millis": 0,
|
||||
"failures": []
|
||||
}
|
||||
```
|
||||
|
||||
## Response body fields
|
||||
|
||||
Field | Description
|
||||
:--- | :---
|
||||
took | The amount of time in milliseconds OpenSearch needed to complete the operation.
|
||||
timed_out | Whether any update requests during the operation timed out.
|
||||
total | Total number of documents processed.
|
||||
updated | Total number of documents updated.
|
||||
batches | Number of scroll responses the request processed.
|
||||
version_conflicts | Number of conflicts the request ran into.
|
||||
noops | How many update requests OpenSearch ignored during the operation. This field always returns 0.
|
||||
retries | The number of bulk and search retry requests.
|
||||
throttled_millis | Number of throttled milliseconds during the request.
|
||||
requests_per_second | Number of requests executed per second during the operation.
|
||||
throttled_until_millis | The amount of time until OpenSearch executes the next throttled request. Always equal to 0 in an update by query request.
|
||||
failures | Any failures that occur during the request.
|
||||
@@ -1,122 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Update document
|
||||
parent: Document APIs
|
||||
grand_parent: REST API reference
|
||||
nav_order: 10
|
||||
---
|
||||
|
||||
# Update document
|
||||
Introduced 1.0
|
||||
{: .label .label-purple }
|
||||
|
||||
If you need to update a document's fields in your index, you can use the update document API operation. You can do so by specifying the new data you want in your index or by including a script in your request body, which OpenSearch runs to update the document.
|
||||
|
||||
## Example
|
||||
|
||||
```json
|
||||
POST /sample-index1/_update/1
|
||||
{
|
||||
"doc": {
|
||||
"first_name" : "Bruce",
|
||||
"last_name" : "Wayne"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Script example
|
||||
|
||||
```json
|
||||
POST /test-index1/_update/1
|
||||
{
|
||||
"script" : {
|
||||
"source": "ctx._source.secret_identity = \"Batman\""
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Path and HTTP methods
|
||||
|
||||
```
|
||||
POST /<index>/_update/<_id>
|
||||
```
|
||||
|
||||
## URL parameters
|
||||
|
||||
Parameter | Type | Description | Required
|
||||
:--- | :--- | :--- | :---
|
||||
<index> | String | Name of the index. | Yes
|
||||
<_id> | String | The ID of the document to update. | Yes
|
||||
if_seq_no | Integer | Only perform the delete operation if the document's version number matches the specified number. | No
|
||||
if_primary_term | Integer | Perform the update operation if the document has the specified primary term. | No
|
||||
lang | String | Language of the script. Default is `painless`. | No
|
||||
require_alias | Boolean | Specifies whether the destination must be an index alias. Default is false. | No
|
||||
refresh | Enum | If true, OpenSearch refreshes shards to make the operation visible to searching. Valid options are `true`, `false`, and `wait_for`, which tells OpenSearch to wait for a refresh before executing the operation. Default is `false`. | No
|
||||
retry_on_conflict | Integer | The amount of times OpenSearch should retry the operation if there's a document conflict. Default is 0. | No
|
||||
routing | String | Value to route the update operation to a specific shard. | No
|
||||
_source | List | Whether to include the `_source` field in the response body. Default is true. | No
|
||||
_source_excludes | List | A comma-separated list of source fields to exclude in the query response. | No
|
||||
_source_includes | List | A comma-separated list of source fields to include in the query response. | No
|
||||
timeout | Time | How long to wait for a response from the cluster. | No
|
||||
wait_for_active_shards | String | The number of active shards that must be available before OpenSearch processes the update request. Default is 1 (only the primary shard). Set to `all` or a positive integer. Values greater than 1 require replicas. For example, if you specify a value of 3, the index must have two replicas distributed across two additional nodes for the operation to succeed. | No
|
||||
|
||||
## Request body
|
||||
|
||||
Your request body must contain the information you want to update your document with. If you just want to replace certain fields in your document, your request body must include a `doc` object, which has the fields you want to update.
|
||||
|
||||
```json
|
||||
{
|
||||
"doc": {
|
||||
"first_name": "Thomas",
|
||||
"last_name": "Wayne"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
You can also use a script to tell OpenSearch how to update your document.
|
||||
|
||||
```json
|
||||
{
|
||||
"script" : {
|
||||
"source": "ctx._source.oldValue += params.newValue",
|
||||
"lang": "painless",
|
||||
"params" : {
|
||||
"newValue" : 10
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Response
|
||||
```json
|
||||
{
|
||||
"_index": "sample-index1",
|
||||
"_type": "_doc",
|
||||
"_id": "1",
|
||||
"_version": 3,
|
||||
"result": "updated",
|
||||
"_shards": {
|
||||
"total": 2,
|
||||
"successful": 2,
|
||||
"failed": 0
|
||||
},
|
||||
"_seq_no": 4,
|
||||
"_primary_term": 17
|
||||
}
|
||||
```
|
||||
|
||||
## Response body fields
|
||||
|
||||
Field | Description
|
||||
:--- | :---
|
||||
_index | The name of the index.
|
||||
_type | The document's type. OpenSearch only supports one type, which is `_doc`.
|
||||
_id | The document's ID.
|
||||
_version | The document's version.
|
||||
_result | The result of the delete operation.
|
||||
_shards | Detailed information about the cluster's shards.
|
||||
total | The total number of shards.
|
||||
successful | The number of shards OpenSearch succssfully deleted the document from.
|
||||
failed | The number of shards OpenSearch failed to delete the document from.
|
||||
_seq_no | The sequence number assigned when the document was indexed.
|
||||
_primary_term | The primary term assigned when the document was indexed.
|
||||
@@ -1,163 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Explain
|
||||
parent: REST API reference
|
||||
nav_order: 140
|
||||
---
|
||||
|
||||
# Explain
|
||||
Introduced 1.0
|
||||
{: .label .label-purple }
|
||||
|
||||
Wondering why a specific document ranks higher (or lower) for a query? You can use the explain API for an explanation of how the relevance score (`_score`) is calculated for every result.
|
||||
|
||||
OpenSearch uses a probabilistic ranking framework called [Okapi BM25](https://en.wikipedia.org/wiki/Okapi_BM25) to calculate relevance scores. Okapi BM25 is based on the original [TF/IDF](http://lucene.apache.org/core/{{site.lucene_version}}/core/org/apache/lucene/search/package-summary.html#scoring) framework used by Apache Lucene.
|
||||
|
||||
The explain API is an expensive operation in terms of both resources and time. On production clusters, we recommend using it sparingly for the purpose of troubleshooting.
|
||||
{: .warning }
|
||||
|
||||
|
||||
## Example
|
||||
|
||||
To see the explain output for all results, set the `explain` flag to `true` either in the URL or in the body of the request:
|
||||
|
||||
```json
|
||||
POST kibana_sample_data_ecommerce/_search?explain=true
|
||||
{
|
||||
"query": {
|
||||
"match": {
|
||||
"customer_first_name": "Mary"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
More often, you want the output for a single document. In that case, specify the document ID in the URL:
|
||||
|
||||
```json
|
||||
POST kibana_sample_data_ecommerce/_explain/EVz1Q3sBgg5eWQP6RSte
|
||||
{
|
||||
"query": {
|
||||
"match": {
|
||||
"customer_first_name": "Mary"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Path and HTTP methods
|
||||
|
||||
```
|
||||
GET <target>/_explain/<id>
|
||||
POST <target>/_explain/<id>
|
||||
```
|
||||
|
||||
## URL parameters
|
||||
|
||||
You must specify the index and document ID. All other URL parameters are optional.
|
||||
|
||||
Parameter | Type | Description | Required
|
||||
:--- | :--- | :--- | :---
|
||||
`<index>` | String | Name of the index. You can only specify a single index. | Yes
|
||||
`<_id>` | String | A unique identifier to attach to the document. | Yes
|
||||
`analyzer` | String | The analyzer to use in the query string. | No
|
||||
`analyze_wildcard` | Boolean | Specifies whether to analyze wildcard and prefix queries. Default is false. | No
|
||||
`default_operator` | String | Indicates whether the default operator for a string query should be AND or OR. Default is OR. | No
|
||||
`df` | String | The default field in case a field prefix is not provided in the query string. | No
|
||||
`lenient` | Boolean | Specifies whether OpenSearch should ignore format-based query failures (for example, querying a text field for an integer). Default is false. | No
|
||||
`preference` | String | Specifies a preference of which shard to retrieve results from. Available options are `_local`, which tells the operation to retrieve results from a locally allocated shard replica, and a custom string value assigned to a specific shard replica. By default, OpenSearch executes the explain operation on random shards. | No
|
||||
`q` | String | Query in the Lucene query string syntax. | No
|
||||
`stored_fields` | Boolean | If true, the operation retrieves document fields stored in the index rather than the document’s `_source`. Default is false. | No
|
||||
`routing` | String | Value used to route the operation to a specific shard. | No
|
||||
`_source` | String | Whether to include the `_source` field in the response body. Default is true. | No
|
||||
`_source_excludes` | String | A comma-separated list of source fields to exclude in the query response. | No
|
||||
`_source_includes` | String | A comma-separated list of source fields to include in the query response. | No
|
||||
|
||||
## Response
|
||||
|
||||
```json
|
||||
{
|
||||
"_index" : "kibana_sample_data_ecommerce",
|
||||
"_type" : "_doc",
|
||||
"_id" : "EVz1Q3sBgg5eWQP6RSte",
|
||||
"matched" : true,
|
||||
"explanation" : {
|
||||
"value" : 3.5671005,
|
||||
"description" : "weight(customer_first_name:mary in 1) [PerFieldSimilarity], result of:",
|
||||
"details" : [
|
||||
{
|
||||
"value" : 3.5671005,
|
||||
"description" : "score(freq=1.0), computed as boost * idf * tf from:",
|
||||
"details" : [
|
||||
{
|
||||
"value" : 2.2,
|
||||
"description" : "boost",
|
||||
"details" : [ ]
|
||||
},
|
||||
{
|
||||
"value" : 3.4100041,
|
||||
"description" : "idf, computed as log(1 + (N - n + 0.5) / (n + 0.5)) from:",
|
||||
"details" : [
|
||||
{
|
||||
"value" : 154,
|
||||
"description" : "n, number of documents containing term",
|
||||
"details" : [ ]
|
||||
},
|
||||
{
|
||||
"value" : 4675,
|
||||
"description" : "N, total number of documents with field",
|
||||
"details" : [ ]
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"value" : 0.47548598,
|
||||
"description" : "tf, computed as freq / (freq + k1 * (1 - b + b * dl / avgdl)) from:",
|
||||
"details" : [
|
||||
{
|
||||
"value" : 1.0,
|
||||
"description" : "freq, occurrences of term within document",
|
||||
"details" : [ ]
|
||||
},
|
||||
{
|
||||
"value" : 1.2,
|
||||
"description" : "k1, term saturation parameter",
|
||||
"details" : [ ]
|
||||
},
|
||||
{
|
||||
"value" : 0.75,
|
||||
"description" : "b, length normalization parameter",
|
||||
"details" : [ ]
|
||||
},
|
||||
{
|
||||
"value" : 1.0,
|
||||
"description" : "dl, length of field",
|
||||
"details" : [ ]
|
||||
},
|
||||
{
|
||||
"value" : 1.1206417,
|
||||
"description" : "avgdl, average length of field",
|
||||
"details" : [ ]
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Response body fields
|
||||
|
||||
Field | Description
|
||||
:--- | :---
|
||||
`matched` | Indicates if the document is a match for the query.
|
||||
`explanation` | The `explanation` object has three properties: `value`, `description`, and `details`. The `value` shows the result of the calculation, the `description` explains what type of calculation is performed, and the `details` shows any subcalculations performed.
|
||||
Term frequency (`tf`) | How many times the term appears in a field for a given document. The more times the term occurs the higher is the relevance score.
|
||||
Inverse document frequency (`idf`) | How often the term appears within the index (across all the documents). The more often the term appears the lower is the relevance score.
|
||||
Field normalization factor (`fieldNorm`) | The length of the field. OpenSearch assigns a higher relevance score to a term appearing in a relatively short field.
|
||||
|
||||
The `tf`, `idf`, and `fieldNorm` values are calculated and stored at index time when a document is added or updated. The values might have some (typically small) inaccuracies as it’s based on summing the samples returned from each shard.
|
||||
|
||||
Individual queries include other factors for calculating the relevance score, such as term proximity, fuzziness, and so on.
|
||||
@@ -1,277 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Multi-search
|
||||
parent: REST API reference
|
||||
nav_order: 130
|
||||
---
|
||||
|
||||
# Multi-search
|
||||
Introduced 1.0
|
||||
{: .label .label-purple }
|
||||
|
||||
As the name suggests, the multi-search operation lets you bundle multiple search requests into a single request. OpenSearch then executes the searches in parallel, so you get back the response more quickly compared to sending one request per search. OpenSearch executes each search independently, so the failure of one doesn't affect the others.
|
||||
|
||||
|
||||
## Example
|
||||
|
||||
```json
|
||||
GET _msearch
|
||||
{ "index": "opensearch_dashboards_sample_data_logs"}
|
||||
{ "query": { "match_all": {} }, "from": 0, "size": 10}
|
||||
{ "index": "opensearch_dashboards_sample_data_ecommerce", "search_type": "dfs_query_then_fetch"}
|
||||
{ "query": { "match_all": {} } }
|
||||
|
||||
```
|
||||
|
||||
|
||||
## Path and HTTP methods
|
||||
|
||||
```
|
||||
GET _msearch
|
||||
GET <indices>/_msearch
|
||||
POST _msearch
|
||||
POST <indices>/_msearch
|
||||
```
|
||||
|
||||
|
||||
## Request body
|
||||
|
||||
The multi-search request body follows this pattern:
|
||||
|
||||
```
|
||||
Metadata\n
|
||||
Query\n
|
||||
Metadata\n
|
||||
Query\n
|
||||
|
||||
```
|
||||
|
||||
- Metadata lines include options, such as which indices to search and the type of search.
|
||||
- Query lines use the [query DSL]({{site.url}}{{site.baseurl}}/opensearch/query-dsl/).
|
||||
|
||||
Just like the [bulk]({{site.url}}{{site.baseurl}}/opensearch/rest-api/document-apis/bulk/) operation, the JSON doesn't need to be minified---spaces are fine---but it does need to be on a single line. OpenSearch uses newline characters to parse multi-search requests and requires that the request body end with a newline character.
|
||||
|
||||
|
||||
## URL parameters and metadata options
|
||||
|
||||
All multi-search URL parameters are optional. Some can also be applied per-search as part of each metadata line.
|
||||
|
||||
Parameter | Type | Description | Supported in metadata line
|
||||
:--- | :--- | :---
|
||||
allow_no_indices | Boolean | Whether to ignore wildcards that don't match any indices. Default is `true`. | Yes
|
||||
css_minimize_roundtrips | Boolean | Whether OpenSearch should try to minimize the number of network round trips between the coordinating node and remote clusters (only applicable to cross-cluster search requests). Default is `true`. | No
|
||||
expand_wildcards | Enum | Expands wildcard expressions to concrete indices. Combine multiple values with commas. Supported values are `all`, `open`, `closed`, `hidden`, and `none`. Default is `open`. | Yes
|
||||
ignore_unavailable | Boolean | If an index from the indices list doesn’t exist, whether to ignore it rather than fail the query. Default is `false`. | Yes
|
||||
max_concurrent_searches | Integer | The maximum number of concurrent searches. The default depends on your node count and search thread pool size. Higher values can improve performance, but risk overloading the cluster. | No
|
||||
max_concurrent_shard_requests | Integer | Maximum number of concurrent shard requests that each search executes per node. Default is 5. Higher values can improve performance, but risk overloading the cluster. | No
|
||||
pre_filter_shard_size | Integer | Default is 128. | No
|
||||
rest_total_hits_as_int | String | Whether the `hits.total` property is returned as an integer (`true`) or an object (`false`). Default is `false`. | No
|
||||
search_type | String | Affects relevance score. Valid options are `query_then_fetch` and `dfs_query_then_fetch`. `query_then_fetch` scores documents using term and document frequencies for the shard (faster, less accurate), whereas `dfs_query_then_fetch` uses term and document frequencies across all shards (slower, more accurate). Default is `query_then_fetch`. | Yes
|
||||
typed_keys | Boolean | Whether to prefix aggregation names with their internal types in the response. Default is `false`. | No
|
||||
|
||||
{% comment %}Regarding `pre_filter_shard_size`: The description from the REST API specification is unintelligible---to me, anyway. I wasn't able to learn anything from reading the source code, either, so I've included the default value and nothing else in the table above. - aetter
|
||||
|
||||
From the REST API specification: A threshold that enforces a pre-filter round trip to prefilter search shards based on query rewriting if the number of shards the search request expands to exceeds the threshold. This filter roundtrip can limit the number of shards significantly if for instance a shard can not match any documents based on its rewrite method ie. if date filters are mandatory to match but the shard bounds and the query are disjoint.{% endcomment %}
|
||||
|
||||
|
||||
## Metadata-only options
|
||||
|
||||
Some options can't be applied as URL parameters to the entire request. Instead, you can apply them per-search as part of each metadata line. All are optional.
|
||||
|
||||
Option | Type | Description
|
||||
:--- | :--- | :---
|
||||
index | String, string array | If you don't specify an index or multiple indices as part of the URL (or want to override the URL value for an individual search), you can include it here. Examples include `"logs-*"` and `["my-store", "sample_data_ecommerce"]`.
|
||||
preference | String | The nodes or shards that you'd like to perform the search. This setting can be useful for testing, but in most situations, the default behavior provides the best search latencies. Options include `_local`, `_only_local`, `_prefer_nodes`, `_only_nodes`, and `_shards`. These last three options accept a list of nodes or shards. Examples include `"_only_nodes:data-node1,data-node2"` and `"_shards:0,1`.
|
||||
request_cache | Boolean | Whether to cache results, which can improve latency for repeat searches. Default is to use the `index.requests.cache.enable` setting for the index (which defaults to `true` for new indices).
|
||||
routing | String | Comma-separated custom routing values (e.g. `"routing": "value1,value2,value3"`.
|
||||
|
||||
|
||||
## Response
|
||||
|
||||
OpenSearch returns an array with the results of each search in the same order as the multi-search request.
|
||||
|
||||
```json
|
||||
{
|
||||
"took" : 2150,
|
||||
"responses" : [
|
||||
{
|
||||
"took" : 2149,
|
||||
"timed_out" : false,
|
||||
"_shards" : {
|
||||
"total" : 1,
|
||||
"successful" : 1,
|
||||
"skipped" : 0,
|
||||
"failed" : 0
|
||||
},
|
||||
"hits" : {
|
||||
"total" : {
|
||||
"value" : 10000,
|
||||
"relation" : "gte"
|
||||
},
|
||||
"max_score" : 1.0,
|
||||
"hits" : [
|
||||
{
|
||||
"_index" : "opensearch_dashboards_sample_data_logs",
|
||||
"_type" : "_doc",
|
||||
"_id" : "_fnhBXsBgv2Zxgu9dZ8Y",
|
||||
"_score" : 1.0,
|
||||
"_source" : {
|
||||
"agent" : "Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1; .NET CLR 1.1.4322)",
|
||||
"bytes" : 4657,
|
||||
"clientip" : "213.116.129.196",
|
||||
"extension" : "zip",
|
||||
"geo" : {
|
||||
"srcdest" : "CN:US",
|
||||
"src" : "CN",
|
||||
"dest" : "US",
|
||||
"coordinates" : {
|
||||
"lat" : 42.35083333,
|
||||
"lon" : -86.25613889
|
||||
}
|
||||
},
|
||||
"host" : "artifacts.opensearch.org",
|
||||
"index" : "opensearch_dashboards_sample_data_logs",
|
||||
"ip" : "213.116.129.196",
|
||||
"machine" : {
|
||||
"ram" : 16106127360,
|
||||
"os" : "ios"
|
||||
},
|
||||
"memory" : null,
|
||||
"message" : "213.116.129.196 - - [2018-07-30T14:12:11.387Z] \"GET /opensearch_dashboards/opensearch_dashboards-1.0.0-windows-x86_64.zip HTTP/1.1\" 200 4657 \"-\" \"Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1; .NET CLR 1.1.4322)\"",
|
||||
"phpmemory" : null,
|
||||
"referer" : "http://twitter.com/success/ellison-onizuka",
|
||||
"request" : "/opensearch_dashboards/opensearch_dashboards-1.0.0-windows-x86_64.zip",
|
||||
"response" : 200,
|
||||
"tags" : [
|
||||
"success",
|
||||
"info"
|
||||
],
|
||||
"timestamp" : "2021-08-02T14:12:11.387Z",
|
||||
"url" : "https://artifacts.opensearch.org/downloads/opensearch_dashboards/opensearch_dashboards-1.0.0-windows-x86_64.zip",
|
||||
"utc_time" : "2021-08-02T14:12:11.387Z",
|
||||
"event" : {
|
||||
"dataset" : "sample_web_logs"
|
||||
}
|
||||
}
|
||||
},
|
||||
...
|
||||
]
|
||||
},
|
||||
"status" : 200
|
||||
},
|
||||
{
|
||||
"took" : 1473,
|
||||
"timed_out" : false,
|
||||
"_shards" : {
|
||||
"total" : 1,
|
||||
"successful" : 1,
|
||||
"skipped" : 0,
|
||||
"failed" : 0
|
||||
},
|
||||
"hits" : {
|
||||
"total" : {
|
||||
"value" : 4675,
|
||||
"relation" : "eq"
|
||||
},
|
||||
"max_score" : 1.0,
|
||||
"hits" : [
|
||||
{
|
||||
"_index" : "opensearch_dashboards_sample_data_ecommerce",
|
||||
"_type" : "_doc",
|
||||
"_id" : "efnhBXsBgv2Zxgu9ap7e",
|
||||
"_score" : 1.0,
|
||||
"_source" : {
|
||||
"category" : [
|
||||
"Women's Clothing"
|
||||
],
|
||||
"currency" : "EUR",
|
||||
"customer_first_name" : "Gwen",
|
||||
"customer_full_name" : "Gwen Dennis",
|
||||
"customer_gender" : "FEMALE",
|
||||
"customer_id" : 26,
|
||||
"customer_last_name" : "Dennis",
|
||||
"customer_phone" : "",
|
||||
"day_of_week" : "Tuesday",
|
||||
"day_of_week_i" : 1,
|
||||
"email" : "gwen@dennis-family.zzz",
|
||||
"manufacturer" : [
|
||||
"Tigress Enterprises",
|
||||
"Gnomehouse mom"
|
||||
],
|
||||
"order_date" : "2021-08-10T16:24:58+00:00",
|
||||
"order_id" : 576942,
|
||||
"products" : [
|
||||
{
|
||||
"base_price" : 32.99,
|
||||
"discount_percentage" : 0,
|
||||
"quantity" : 1,
|
||||
"manufacturer" : "Tigress Enterprises",
|
||||
"tax_amount" : 0,
|
||||
"product_id" : 22182,
|
||||
"category" : "Women's Clothing",
|
||||
"sku" : "ZO0036600366",
|
||||
"taxless_price" : 32.99,
|
||||
"unit_discount_amount" : 0,
|
||||
"min_price" : 14.85,
|
||||
"_id" : "sold_product_576942_22182",
|
||||
"discount_amount" : 0,
|
||||
"created_on" : "2016-12-20T16:24:58+00:00",
|
||||
"product_name" : "Jersey dress - black/red",
|
||||
"price" : 32.99,
|
||||
"taxful_price" : 32.99,
|
||||
"base_unit_price" : 32.99
|
||||
},
|
||||
{
|
||||
"base_price" : 28.99,
|
||||
"discount_percentage" : 0,
|
||||
"quantity" : 1,
|
||||
"manufacturer" : "Gnomehouse mom",
|
||||
"tax_amount" : 0,
|
||||
"product_id" : 14230,
|
||||
"category" : "Women's Clothing",
|
||||
"sku" : "ZO0234902349",
|
||||
"taxless_price" : 28.99,
|
||||
"unit_discount_amount" : 0,
|
||||
"min_price" : 13.05,
|
||||
"_id" : "sold_product_576942_14230",
|
||||
"discount_amount" : 0,
|
||||
"created_on" : "2016-12-20T16:24:58+00:00",
|
||||
"product_name" : "Blouse - june bug",
|
||||
"price" : 28.99,
|
||||
"taxful_price" : 28.99,
|
||||
"base_unit_price" : 28.99
|
||||
}
|
||||
],
|
||||
"sku" : [
|
||||
"ZO0036600366",
|
||||
"ZO0234902349"
|
||||
],
|
||||
"taxful_total_price" : 61.98,
|
||||
"taxless_total_price" : 61.98,
|
||||
"total_quantity" : 2,
|
||||
"total_unique_products" : 2,
|
||||
"type" : "order",
|
||||
"user" : "gwen",
|
||||
"geoip" : {
|
||||
"country_iso_code" : "US",
|
||||
"location" : {
|
||||
"lon" : -118.2,
|
||||
"lat" : 34.1
|
||||
},
|
||||
"region_name" : "California",
|
||||
"continent_name" : "North America",
|
||||
"city_name" : "Los Angeles"
|
||||
},
|
||||
"event" : {
|
||||
"dataset" : "sample_ecommerce"
|
||||
}
|
||||
}
|
||||
},
|
||||
...
|
||||
]
|
||||
},
|
||||
"status" : 200
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
@@ -1,40 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Remote cluster information
|
||||
parent: REST API reference
|
||||
nav_order: 25
|
||||
---
|
||||
|
||||
# Remote cluster information
|
||||
Introduced 1.0
|
||||
{: .label .label-purple }
|
||||
|
||||
This operation provides connection information for any remote OpenSearch clusters that you've configured for the local cluster, such as the remote cluster alias, connection mode (`sniff` or `proxy`), IP addresses for seed nodes, and timeout settings.
|
||||
|
||||
The response is more comprehensive and useful than a call to `_cluster/settings`, which only includes the cluster alias and seed nodes.
|
||||
|
||||
|
||||
## Path and HTTP methods
|
||||
|
||||
```
|
||||
GET _remote/info
|
||||
```
|
||||
|
||||
|
||||
## Response
|
||||
|
||||
```json
|
||||
{
|
||||
"opensearch-cluster2": {
|
||||
"connected": true,
|
||||
"mode": "sniff",
|
||||
"seeds": [
|
||||
"172.28.0.2:9300"
|
||||
],
|
||||
"num_nodes_connected": 1,
|
||||
"max_connections_per_cluster": 3,
|
||||
"initial_connect_timeout": "30s",
|
||||
"skip_unavailable": false
|
||||
}
|
||||
}
|
||||
```
|
||||
@@ -1,110 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Scroll
|
||||
parent: REST API reference
|
||||
nav_order: 120
|
||||
---
|
||||
|
||||
# Scroll
|
||||
Introduced 1.0
|
||||
{: .label .label-purple }
|
||||
|
||||
You can use the `scroll` operation to retrieve a large number of results. For example, for machine learning jobs, you can request an unlimited number of results in batches.
|
||||
|
||||
To use the `scroll` operation, add a `scroll` parameter to the request header with a search context to tell OpenSearch how long you need to keep scrolling. This search context needs to be long enough to process a single batch of results.
|
||||
|
||||
Because search contexts consume a lot of memory, we suggest you don't use the `scroll` operation for frequent user queries. Instead, use the `sort` parameter with the `search_after` parameter to scroll responses for user queries.
|
||||
{: .note }
|
||||
|
||||
## Example
|
||||
|
||||
To set the number of results that you want returned for each batch, use the `size` parameter:
|
||||
|
||||
```json
|
||||
GET shakespeare/_search?scroll=10m
|
||||
{
|
||||
"size": 10000
|
||||
}
|
||||
```
|
||||
|
||||
OpenSearch caches the results and returns a scroll ID to access them in batches:
|
||||
|
||||
```json
|
||||
"_scroll_id" : "DXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAAAUWdmpUZDhnRFBUcWFtV21nMmFwUGJEQQ=="
|
||||
```
|
||||
|
||||
Pass this scroll ID to the `scroll` operation to get back the next batch of results:
|
||||
|
||||
```json
|
||||
GET _search/scroll
|
||||
{
|
||||
"scroll": "10m",
|
||||
"scroll_id": "DXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAAAUWdmpUZDhnRFBUcWFtV21nMmFwUGJEQQ=="
|
||||
}
|
||||
```
|
||||
|
||||
Using this scroll ID, you get results in batches of 10,000 as long as the search context is still open. Typically, the scroll ID does not change between requests, but it *can* change, so make sure to always use the latest scroll ID. If you don't send the next scroll request within the set search context, the `scroll` operation does not return any results.
|
||||
|
||||
If you expect billions of results, use a sliced scroll. Slicing allows you to perform multiple scroll operations for the same request, but in parallel.
|
||||
Set the ID and the maximum number of slices for the scroll:
|
||||
|
||||
```json
|
||||
GET shakespeare/_search?scroll=10m
|
||||
{
|
||||
"slice": {
|
||||
"id": 0,
|
||||
"max": 10
|
||||
},
|
||||
"query": {
|
||||
"match_all": {}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
With a single scroll ID, you get back 10 results.
|
||||
You can have up to 10 IDs.
|
||||
|
||||
Close the search context when you’re done scrolling, because the `scroll` operation continues to consume computing resources until the timeout:
|
||||
|
||||
```json
|
||||
DELETE _search/scroll/DXF1ZXJ5QW5kRmV0Y2gBAAAAAAAAAAcWdmpUZDhnRFBUcWFtV21nMmFwUGJEQQ==
|
||||
```
|
||||
|
||||
To close all open scroll contexts:
|
||||
|
||||
```json
|
||||
DELETE _search/scroll/_all
|
||||
```
|
||||
|
||||
The `scroll` operation corresponds to a specific timestamp. It doesn't consider documents added after that timestamp as potential results.
|
||||
|
||||
|
||||
## Path and HTTP methods
|
||||
|
||||
```
|
||||
GET _search/scroll
|
||||
POST _search/scroll
|
||||
```
|
||||
```
|
||||
GET _search/scroll/<scroll-id>
|
||||
POST _search/scroll/<scroll-id>
|
||||
```
|
||||
|
||||
## URL parameters
|
||||
|
||||
All scroll parameters are optional.
|
||||
|
||||
Parameter | Type | Description
|
||||
:--- | :--- | :---
|
||||
scroll | Time | Specifies the amount of time the search context is maintained.
|
||||
scroll_id | String | The scroll ID for the search.
|
||||
rest_total_hits_as_int | Boolean | Whether the `hits.total` property is returned as an integer (`true`) or an object (`false`). Default is `false`.
|
||||
|
||||
## Response
|
||||
|
||||
```json
|
||||
{
|
||||
"succeeded": true,
|
||||
"num_freed": 1
|
||||
}
|
||||
```
|
||||
@@ -1,80 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Update mapping
|
||||
parent: REST API reference
|
||||
nav_order: 6
|
||||
---
|
||||
|
||||
# Update mapping
|
||||
|
||||
If you want to update an index's mappings to add or update field types after index creation, you can do so with the update mapping API operation.
|
||||
|
||||
Note that you cannot use this operation to update mappings that already map to existing data in the index. You must first create a new index with your desired mappings, and then use the [reindex API operation]({{site.url}}{{site.baseurl}}/opensearch/reindex-data) to map all the documents from your old index to the new index. If you don't want any downtime while reindexing your indices, you can use [aliases]({{site.url}}{{site.baseurl}}/opensearch/index-alias).
|
||||
|
||||
## Example
|
||||
|
||||
```json
|
||||
PUT /sample-index/_mapping
|
||||
|
||||
{
|
||||
"properties": {
|
||||
"age": {
|
||||
"type": "integer"
|
||||
},
|
||||
"occupation":{
|
||||
"type": "text"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
## Path and HTTP methods
|
||||
|
||||
```
|
||||
PUT /<target-index>/_mapping
|
||||
```
|
||||
|
||||
You can also use the update mapping operation to update multiple indices with one request.
|
||||
|
||||
```
|
||||
PUT /<target-index1>,<target-index2>/_mapping
|
||||
```
|
||||
|
||||
## URL parameters
|
||||
|
||||
All update mapping parameters are optional.
|
||||
|
||||
Parameter | Data Type | Description
|
||||
:--- | :--- | :---
|
||||
allow_no_indices | Boolean | Whether to ignore wildcards that don’t match any indices. Default is `true`.
|
||||
expand_wildcards | String | Expands wildcard expressions to different indices. Combine multiple values with commas. Available values are `all` (match all indices), `open` (match open indices), `closed` (match closed indices), `hidden` (match hidden indices), and `none` (do not accept wildcard expressions), which must be used with `open`, `closed`, or both. Default is `open`.
|
||||
ignore_unavailable | Boolean | If true, OpenSearch does not include missing or closed indices in the response.
|
||||
master_timeout | Time | How long to wait for a connection to the master node. Default is `30s`.
|
||||
timeout | Time | How long to wait for the response to return. Default is `30s`.
|
||||
write_index_only | Boolean | Whether OpenSearch should apply mapping updates only to the write index.
|
||||
|
||||
## Request body
|
||||
|
||||
The request body must contain `properties`, which has all of the mappings that you want to update.
|
||||
|
||||
```json
|
||||
{
|
||||
"properties":{
|
||||
"color":{
|
||||
"type": "text"
|
||||
},
|
||||
"year":{
|
||||
"type": "integer"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Response
|
||||
|
||||
```json
|
||||
{
|
||||
"acknowledged": true
|
||||
}
|
||||
```
|
||||
@@ -1,232 +0,0 @@
|
||||
# frozen_string_literal: true
|
||||
|
||||
require "jekyll/hooks"
|
||||
require "jekyll/document"
|
||||
require "json"
|
||||
require "set"
|
||||
require "uri"
|
||||
require "pathname"
|
||||
|
||||
##
|
||||
# This singleton checks links during build to warn or fail upon finding dead links.
|
||||
#
|
||||
# `JEKYLL_CHECK_EXTERNAL_LINKS`, set on the environment, will cause verification of external links, irrespective of its
|
||||
# value. Usage: `JEKYLL_CHECK_EXTERNAL_LINKS= bundle exec jekyll build --trace`
|
||||
#
|
||||
# `JEKYLL_FATAL_LINK_CHECKER`, set on the environment, will cause the build to fail if an internal dead link is found.
|
||||
# If set as `JEKYLL_FATAL_LINK_CHECKER=2`, the build will fail for internal and external dead links; in this case, there
|
||||
# is no need to set `JEKYLL_CHECK_EXTERNAL_LINKS`.
|
||||
|
||||
module Jekyll::LinkChecker
|
||||
|
||||
##
|
||||
# The collection that will get stores as the output
|
||||
|
||||
@urls = {}
|
||||
|
||||
##
|
||||
# Pattern to identify documents that should be excluded based on their URL
|
||||
|
||||
@excluded_paths = /(\.(css|js|json|map|xml|txt|yml)$)/i.freeze
|
||||
|
||||
##
|
||||
# Pattern to identify certain HTML tags whose content should be excluded from indexing
|
||||
|
||||
@href_matcher = /<a[^>]+href=(['"])(.+?)\1/im.freeze
|
||||
|
||||
##
|
||||
# Pattern to check for external URLs
|
||||
|
||||
@external_matcher = /^https?:\/\//.freeze
|
||||
|
||||
##
|
||||
# List of domains to ignore
|
||||
@ignored_domains = %w[localhost]
|
||||
|
||||
##
|
||||
# Pattern of local paths to ignore
|
||||
@ignored_paths = /(^\/javadocs\/)/.freeze
|
||||
|
||||
##
|
||||
# Valid response codes for successful links
|
||||
@success_codes = %w[200 302]
|
||||
|
||||
##
|
||||
# Questionable response codes for successful links
|
||||
@questionable_codes = %w[301 403 429]
|
||||
|
||||
##
|
||||
# Holds the list of failures
|
||||
@failures = []
|
||||
|
||||
##
|
||||
# Driven by environment variables, it indicates a need to check external links
|
||||
@check_external_links
|
||||
|
||||
##
|
||||
# Driven by environment variables, it indicates the need to fail the build for dead links
|
||||
@should_build_fatally
|
||||
|
||||
|
||||
##
|
||||
# Initializes the singleton by recording the site
|
||||
|
||||
def self.init(site)
|
||||
@site = site
|
||||
@urls = {}
|
||||
@failures = []
|
||||
end
|
||||
|
||||
##
|
||||
# Processes a Document or Page and adds the links to a collection
|
||||
# It also checks for anchors to parts of the same page/doc
|
||||
|
||||
def self.process(page)
|
||||
return if @excluded_paths.match(page.path)
|
||||
|
||||
hrefs = page.content.scan(@href_matcher)
|
||||
hrefs.each do |(_, href)|
|
||||
relative_path = page.path[0] == '/' ? Pathname.new(page.path).relative_path_from(Dir.getwd) : page.path
|
||||
|
||||
if href.start_with? '#'
|
||||
p relative_path if (page.content =~ /<[a-z0-9-]+[^>]+id="#{href[1..]}"/i).nil?
|
||||
@failures << "##{href[1..]}, linked in ./#{relative_path}" if (page.content =~ /<[a-z0-9-]+[^>]+id="#{href[1..]}"/i).nil?
|
||||
else
|
||||
@urls[href] = Set[] unless @urls.key?(href)
|
||||
@urls[href] << relative_path
|
||||
end
|
||||
end
|
||||
end
|
||||
|
||||
##
|
||||
# Saves the collection as a JSON file
|
||||
|
||||
def self.verify(site)
|
||||
if ENV.key?('JEKYLL_CHECK_EXTERNAL_LINKS')
|
||||
@check_external_links = true
|
||||
puts "LinkChecker: [Notice] Will verify external links"
|
||||
end
|
||||
|
||||
if ENV.key?('JEKYLL_FATAL_LINK_CHECKER')
|
||||
@should_build_fatally = true
|
||||
if ENV['JEKYLL_FATAL_LINK_CHECKER'] == '2'
|
||||
@check_external_links = true
|
||||
puts "LinkChecker: [Notice] The build will fail if any dead links are found"
|
||||
else
|
||||
puts "LinkChecker: [Notice] The build will fail if a dead internal link is found"
|
||||
end
|
||||
end
|
||||
|
||||
@base_url_matcher = /^#{@site.config["url"]}#{@site.baseurl}(\/.*)$/.freeze
|
||||
|
||||
@urls.each do |url, pages|
|
||||
@failures << "#{url}, linked to in ./#{pages.to_a.join(", ./")}" unless self.check(url)
|
||||
end
|
||||
|
||||
msg = "Found #{@failures.size} dead link#{@failures.size > 1 ? 's' : ''}:\n#{@failures.join("\n")}" unless @failures.empty?
|
||||
|
||||
if @should_build_fatally
|
||||
raise msg
|
||||
else
|
||||
puts "\nLinkChecker: [Warning] #{msg}\n"
|
||||
end
|
||||
end
|
||||
|
||||
##
|
||||
# Check if URL is accessible
|
||||
|
||||
def self.check(url)
|
||||
match = @base_url_matcher.match(url)
|
||||
unless match.nil?
|
||||
url = match[1]
|
||||
end
|
||||
|
||||
if @external_matcher =~ url
|
||||
return true unless @check_external_links
|
||||
return self.check_external(url)
|
||||
end
|
||||
|
||||
return self.check_internal(url)
|
||||
end
|
||||
|
||||
##
|
||||
# Check if an external URL is accessible by making a HEAD call
|
||||
|
||||
def self.check_external(url)
|
||||
uri = URI(url)
|
||||
return true if @ignored_domains.include? uri.host
|
||||
|
||||
(Net::HTTP.new uri.host, uri.port).tap do |http|
|
||||
http.use_ssl = true
|
||||
end.start do |http|
|
||||
http.use_ssl = (uri.scheme == "https")
|
||||
|
||||
request = Net::HTTP::Get.new(uri)
|
||||
|
||||
http.request(request) do |response|
|
||||
return true if @success_codes.include? response.code
|
||||
|
||||
puts "LinkChecker: [Warning] Got #{response.code} from #{url}"
|
||||
return @questionable_codes.include? response.code
|
||||
end
|
||||
end
|
||||
end
|
||||
|
||||
##
|
||||
# Check if an internal link is accessible
|
||||
|
||||
def self.check_internal(url)
|
||||
return true if @ignored_paths =~ url
|
||||
|
||||
path, hash = url.split('#')
|
||||
|
||||
unless path.end_with? 'index.html'
|
||||
path << '/' unless path.end_with? '/'
|
||||
path << 'index.html' unless path.end_with? 'index.html'
|
||||
end
|
||||
|
||||
filename = File.join(@site.config["destination"], path)
|
||||
|
||||
return false unless File.file?(filename)
|
||||
|
||||
content = File.read(filename)
|
||||
unless content.include? "<title>Redirecting"
|
||||
return true if hash.nil? || hash.empty?
|
||||
return !(content =~ /<[a-z0-9-]+[^>]+id="#{hash}"/i).nil?
|
||||
end
|
||||
|
||||
match = content.match(@href_matcher)
|
||||
if match.nil?
|
||||
puts "LinkChecker: [Warning] Cannot check #{url} due to an unfollowable redirect"
|
||||
return true
|
||||
end
|
||||
|
||||
redirect = match[2]
|
||||
redirect << '#' + hash unless hash.nil? || hash.empty?
|
||||
return self.check(redirect)
|
||||
end
|
||||
end
|
||||
|
||||
# Before any Document or Page is processed, initialize the LinkChecker
|
||||
|
||||
Jekyll::Hooks.register :site, :pre_render do |site|
|
||||
Jekyll::LinkChecker.init(site)
|
||||
end
|
||||
|
||||
# Process a Page as soon as its content is ready
|
||||
|
||||
Jekyll::Hooks.register :pages, :post_convert do |page|
|
||||
Jekyll::LinkChecker.process(page)
|
||||
end
|
||||
|
||||
# Process a Document as soon as its content is ready
|
||||
|
||||
Jekyll::Hooks.register :documents, :post_convert do |document|
|
||||
Jekyll::LinkChecker.process(document)
|
||||
end
|
||||
|
||||
# Verify gathered links after Jekyll is done writing all its stuff
|
||||
|
||||
Jekyll::Hooks.register :site, :post_write do |site|
|
||||
Jekyll::LinkChecker.verify(site)
|
||||
end
|
||||
@@ -1,5 +1,3 @@
|
||||
$content-width: 900px;
|
||||
|
||||
//
|
||||
// Brand colors
|
||||
//
|
||||
|
||||
+28
-916
@@ -1,39 +1,5 @@
|
||||
@import "../../assets/fonts/open-sans/webfont.css";
|
||||
@import "../../assets/fonts/open-sans-condensed/webfont.css";
|
||||
@import "../../assets/fonts/noto-serif/webfont.css";
|
||||
@import "../../assets/fonts/fira-mono/webfont.css";
|
||||
|
||||
// Font Family Mixins
|
||||
@mixin serif {
|
||||
font-family: "Noto Serif", 'Iowan Old Style', 'Apple Garamond', 'Baskerville', 'Times New Roman', serif;
|
||||
}
|
||||
|
||||
@mixin sans-serif {
|
||||
font-family: "Open Sans", "Segoe UI", Tahoma, sans-serif;
|
||||
|
||||
}
|
||||
|
||||
@mixin monospace {
|
||||
font-family: "Fira Mono", Consolas, Menlo, Monaco, "Courier New", Courier, monospace;
|
||||
font-variant-ligatures: no-common-ligatures; // disables the common ligatures only
|
||||
text-rendering: optimizeSpeed; // for Safari 7.x
|
||||
}
|
||||
|
||||
@mixin heading-sans-serif {
|
||||
font-family: "Open Sans Condensed", Impact, "Franklin Gothic Bold", sans-serif;
|
||||
}
|
||||
|
||||
// Font Sizing Mixin (http://css-tricks.com/snippets/css/less-mixin-for-rem-font-sizing/)
|
||||
@mixin font-size ( $size: 16, $important: false ) {
|
||||
@if $important {
|
||||
font-size: $size + px !important;
|
||||
font-size: $size/16 + rem !important;
|
||||
}
|
||||
@else {
|
||||
font-size: $size + px;
|
||||
font-size: $size/16 + rem;
|
||||
}
|
||||
}
|
||||
@import url('https://fonts.googleapis.com/css?family=Open+Sans:400,400i,600,700');
|
||||
@import url('https://fonts.googleapis.com/css2?family=Open+Sans+Condensed:wght@700&display=swap');
|
||||
|
||||
// Additional variables
|
||||
$table-border-color: $grey-lt-300;
|
||||
@@ -49,22 +15,20 @@ $media-queries: (
|
||||
);
|
||||
|
||||
body {
|
||||
@include serif;
|
||||
padding-bottom: 6rem;
|
||||
font-family: 'Open Sans', sans-serif;
|
||||
@include mq(md) {
|
||||
padding-bottom: 0;
|
||||
}
|
||||
}
|
||||
|
||||
code {
|
||||
@include monospace;
|
||||
font-family: "SFMono-Regular", Menlo, "DejaVu Sans Mono", "Droid Sans Mono", Consolas, monospace;
|
||||
font-size: 0.75rem;
|
||||
-webkit-font-smoothing: subpixel-antialiased;
|
||||
-moz-osx-font-smoothing: auto;
|
||||
}
|
||||
|
||||
.site-nav {
|
||||
padding-top: 1rem;
|
||||
}
|
||||
|
||||
.nav-category {
|
||||
text-align: start;
|
||||
padding-top: 2rem;
|
||||
}
|
||||
|
||||
.main-content {
|
||||
@@ -83,14 +47,10 @@ code {
|
||||
}
|
||||
}
|
||||
h1, h2, h3, h4, h5, h6 {
|
||||
@include heading-sans-serif;
|
||||
font-weight: 700;
|
||||
font-family: "Open Sans Condensed", "Open Sans", sans-serif;
|
||||
font-weight: 400;
|
||||
margin-top: 2.4rem;
|
||||
margin-bottom: 0.8rem;
|
||||
|
||||
a {
|
||||
text-decoration: none;
|
||||
}
|
||||
}
|
||||
h4 {
|
||||
font-size: 14px !important;
|
||||
@@ -205,23 +165,20 @@ td {
|
||||
}
|
||||
|
||||
// Keeps labels high and tight next to headers
|
||||
h1 + p.label, h1 + p.label + p.label,
|
||||
h2 + p.label, h2 + p.label + p.label,
|
||||
h3 + p.label, h3 + p.label + p.label,
|
||||
h4 + p.label, h4 + p.label + p.label,
|
||||
h5 + p.label, h5 + p.label + p.label,
|
||||
h6 + p.label, h6 + p.label + p.label {
|
||||
margin: -20px 0 0 0;
|
||||
h1 + p.label {
|
||||
margin: -23px 0 0 0;
|
||||
}
|
||||
|
||||
p.label {
|
||||
a {
|
||||
color: inherit;
|
||||
background-image: none;
|
||||
&:hover { background-image: none; }
|
||||
}
|
||||
h2 + p.label {
|
||||
margin: -15px 0 0 0;
|
||||
}
|
||||
h3 + p.label {
|
||||
margin: -10px 0 0 0;
|
||||
}
|
||||
h4 + p.label,
|
||||
h5 + p.label,
|
||||
h6 + p.label {
|
||||
margin: -7px 0 0 0;
|
||||
}
|
||||
|
||||
|
||||
// Modifies margins in xl layout to support TOC
|
||||
.side-bar {
|
||||
@@ -238,28 +195,16 @@ p.label {
|
||||
}
|
||||
|
||||
// Adds TOC to righthand side in xl layout
|
||||
.main-content-wrap {
|
||||
max-width: 100%;
|
||||
}
|
||||
.toc-wrap {
|
||||
width: 0;
|
||||
display: none;
|
||||
|
||||
@include mq(xl) {
|
||||
display: block;
|
||||
padding: 2rem 0;
|
||||
}
|
||||
}
|
||||
.toc {
|
||||
display: none;
|
||||
|
||||
@include mq(xl) {
|
||||
z-index: 1;
|
||||
z-index: 0;
|
||||
display: block;
|
||||
position: sticky;
|
||||
top: 2rem;
|
||||
position: fixed;
|
||||
top: 59px;
|
||||
right: calc((100% - #{$nav-width + $content-width + $toc-width}) / 2);
|
||||
width: $toc-width;
|
||||
max-height: calc(100vh - 4rem);
|
||||
max-height: calc(100% - 118px);
|
||||
overflow: auto;
|
||||
}
|
||||
}
|
||||
@@ -290,836 +235,3 @@ p.label {
|
||||
padding-top: .25rem;
|
||||
padding-bottom: .25rem;
|
||||
}
|
||||
|
||||
/* Website Header & Footer */
|
||||
$logo_width: 170px;
|
||||
|
||||
$attention-light: #4fb3e3;
|
||||
$attention: #00a3e0; //formerly $green-medium, open sky
|
||||
$attention-dark: #0082b3; //formerly $green-medium-dark, open sky, tent 1
|
||||
$core: #0053b8; //pacific blue
|
||||
|
||||
$warning-light: #ffc460; //golden poppy, tint 2
|
||||
$warning: #ffb81c; //golden poppy
|
||||
$warning-dark: #cc9316; //golden poppy, shade 1
|
||||
|
||||
$background-darkest: #D9E1E2;
|
||||
$background-darker: #f5f7f7; //SF Fog, tint 1
|
||||
$background-lightest: #fff; //pure white
|
||||
|
||||
$line: #ccd3d6; //sf fog, shade 1
|
||||
$line-lighter: #f6f8f8; // sf fog, tint 1
|
||||
$highlight: #b9d9eb; //pacific sky, formerly $green-very-light
|
||||
$highlight-lighter: #c7dfee;
|
||||
$highlight-lightest: #f4f8fb;
|
||||
|
||||
$accent: #2cd5c4; //seafoam mint, formerly $green-light
|
||||
$accent-dark: #003b5c; //deep blue sea, formerly $green-dark, $green-dark-text unused
|
||||
$accent-light: #7b96a9; //deep blue sea, tint 2
|
||||
|
||||
$text: #002a3a; //midnight sky
|
||||
$text-visited: #1d3c4b; //midnight sky, tint 1
|
||||
$text-hover: #4c636f; //midnight sky, tint 2
|
||||
$text-light: #647782; //midnight sky, tint 3
|
||||
$text-light-darker: #4c636f; //midnight sky, tint 2
|
||||
$text-light-darkest: #1d3c4b; //midnight sky, tint 1
|
||||
|
||||
$text-link-alternate: #0053b8; //pacific blue
|
||||
$text-link-alternate-lighter: #137cc1; //pacific blue tint 1
|
||||
$text-link-alternate-darker: #00529e;
|
||||
|
||||
@mixin respond-min($width) {
|
||||
@media screen and (min-width: $width) {
|
||||
@content;
|
||||
}
|
||||
}
|
||||
|
||||
// Boilerplate Helper mixins (https://github.com/h5bp/html5-boilerplate/blob/v4.1.0/doc/css.md)
|
||||
@mixin visuallyhidden {
|
||||
border: 0;
|
||||
clip: rect(0 0 0 0);
|
||||
height: 1px;
|
||||
margin: -1px;
|
||||
overflow: hidden;
|
||||
padding: 0;
|
||||
position: absolute;
|
||||
width: 1px;
|
||||
}
|
||||
|
||||
@mixin clearfix {
|
||||
&:before,
|
||||
&:after {
|
||||
content: "";
|
||||
display: table;
|
||||
}
|
||||
&:after {
|
||||
clear: both;
|
||||
}
|
||||
}
|
||||
|
||||
// Green Link Mixin
|
||||
@mixin link-alternate { //todo make non-colour oriented
|
||||
color: $text-link-alternate;
|
||||
text-decoration: none;
|
||||
&:visited {
|
||||
color: $text-link-alternate;
|
||||
}
|
||||
&:hover,
|
||||
&:active,
|
||||
&:focus {
|
||||
color: $text-link-alternate-lighter;
|
||||
text-decoration: none;
|
||||
}
|
||||
}
|
||||
|
||||
@mixin stripes {
|
||||
background-image: -webkit-linear-gradient(-45deg, rgba(0, 0, 0, .04) 25%, transparent 25%, transparent 50%, rgba(0, 0, 0, .04) 50%, rgba(0, 0, 0, .04) 75%, transparent 75%, transparent);
|
||||
background-image: -moz-linear-gradient(-45deg, rgba(0, 0, 0, .04) 25%, transparent 25%, transparent 50%, rgba(0, 0, 0, .04) 50%, rgba(0, 0, 0, .04) 75%, transparent 75%, transparent);
|
||||
background-image: linear-gradient(135deg, rgba(0, 0, 0, .04) 25%, transparent 25%, transparent 50%, rgba(0, 0, 0, .04) 50%, rgba(0, 0, 0, .04) 75%, transparent 75%, transparent);
|
||||
}
|
||||
|
||||
@mixin warning-stripes {
|
||||
background-color: $warning;
|
||||
background-image: linear-gradient(135deg, $warning-light 25%, transparent 25%, transparent 50%, $warning-light 50%, $warning-light 75%, transparent 75%, transparent);
|
||||
}
|
||||
|
||||
html {
|
||||
background: $accent-dark;
|
||||
}
|
||||
|
||||
body {
|
||||
@include serif;
|
||||
@include font-size(16);
|
||||
background: $background-lightest;
|
||||
color: $text;
|
||||
line-height: 1.6;
|
||||
-webkit-font-smoothing: antialiased;
|
||||
-moz-osx-font-smoothing: grayscale;
|
||||
|
||||
.layout-secondary,
|
||||
[role="complementary"] {
|
||||
@include sans-serif; // reverse font style on sidebar and secondary areas
|
||||
}
|
||||
|
||||
// don't activate mobile styles for larger screens
|
||||
@include mq(md) {
|
||||
min-width: 768px;
|
||||
}
|
||||
}
|
||||
|
||||
main {
|
||||
display: flex;
|
||||
flex-flow: row nowrap;
|
||||
align-content: stretch;
|
||||
height: 100%;
|
||||
position: relative;
|
||||
|
||||
@include mq(md) {
|
||||
padding-top: calc(4rem + 9px);
|
||||
}
|
||||
|
||||
.side-bar {
|
||||
@include sans-serif;
|
||||
position: static;
|
||||
height: auto;
|
||||
}
|
||||
|
||||
.main {
|
||||
margin-left: 0;
|
||||
display: flex;
|
||||
flex-flow: row nowrap;
|
||||
overflow: hidden;
|
||||
|
||||
@include mq(xl) {
|
||||
overflow: visible;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
.container {
|
||||
box-sizing: content-box;
|
||||
|
||||
@include mq(md) {
|
||||
margin: 0 auto;
|
||||
max-width: 1400px;
|
||||
padding: 0 (32/768) * 100%;
|
||||
}
|
||||
|
||||
&.sidebar-right {
|
||||
.mdzr-boxshadow & {
|
||||
box-shadow: -1200px 0 0 0px $background-lightest;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
.toc,
|
||||
.breadcrumb-nav {
|
||||
@include sans-serif;
|
||||
-webkit-font-smoothing: subpixel-antialiased;
|
||||
-moz-osx-font-smoothing: auto;
|
||||
}
|
||||
|
||||
.main-content {
|
||||
h1, h2, h3, h4, h5, h6 {
|
||||
a {
|
||||
@include link-alternate;
|
||||
}
|
||||
}
|
||||
h2 {
|
||||
@include font-size(24, true);
|
||||
}
|
||||
}
|
||||
|
||||
.btn {
|
||||
@include sans-serif;
|
||||
@include font-size(16);
|
||||
-webkit-font-smoothing: subpixel-antialiased;
|
||||
-moz-osx-font-smoothing: auto;
|
||||
}
|
||||
|
||||
[role="banner"] {
|
||||
// Includes global navigation, logo, and tagline at top of document
|
||||
@include clearfix;
|
||||
background: $accent-dark;
|
||||
overflow: hidden;
|
||||
margin: 0;
|
||||
padding: 10px 0 6px;
|
||||
position: relative;
|
||||
z-index: 0;
|
||||
|
||||
.container {
|
||||
@include mq(md) {
|
||||
position: relative;
|
||||
}
|
||||
}
|
||||
|
||||
.meta {
|
||||
@include font-size(13);
|
||||
color: $attention;
|
||||
font-weight: 700;
|
||||
width: auto;
|
||||
float: left;
|
||||
margin: 8px 0 0 10px;
|
||||
display: none;
|
||||
|
||||
@include respond-min(1150px) {
|
||||
float: left;
|
||||
width: 200px;
|
||||
display: block;
|
||||
}
|
||||
|
||||
|
||||
}
|
||||
|
||||
|
||||
.logo {
|
||||
@include font-size(40);
|
||||
@include sans-serif;
|
||||
/*background: url(../img/logo-search.png) 0 0 no-repeat;*/
|
||||
color: $background-lightest;
|
||||
display: block;
|
||||
float: left;
|
||||
font-weight: 700;
|
||||
margin: 10px;
|
||||
overflow: hidden;
|
||||
text-decoration: none;
|
||||
text-indent: 100%;
|
||||
width: 170px;
|
||||
height: 36px;
|
||||
position: relative;
|
||||
svg {
|
||||
position: absolute;
|
||||
top: 1px;
|
||||
left: 1px
|
||||
}
|
||||
.mdzr-svg & { // deliver svg logo if applicable
|
||||
/*background: url(../img/opensearch-logo-monochrome.svg) center center no-repeat;*/
|
||||
}
|
||||
|
||||
@include mq(md) {
|
||||
margin-left: 0;
|
||||
}
|
||||
}
|
||||
|
||||
.menu-button {
|
||||
@include font-size(20);
|
||||
background: $accent-dark;
|
||||
border-radius: 23px;
|
||||
color: $background-lightest;
|
||||
cursor: pointer;
|
||||
display: block;
|
||||
float: right;
|
||||
height: 45px;
|
||||
line-height: 48px;
|
||||
margin: 4px 10px;
|
||||
text-align: center;
|
||||
text-decoration: none;
|
||||
width: 45px;
|
||||
|
||||
@include mq(md) {
|
||||
display: none;
|
||||
}
|
||||
|
||||
&:active {
|
||||
color: $attention;
|
||||
}
|
||||
|
||||
span {
|
||||
@include visuallyhidden;
|
||||
}
|
||||
|
||||
&.active {
|
||||
opacity: 0.5;
|
||||
|
||||
& ~ .nav-menu-on {
|
||||
max-height: 500px;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
.nav-menu-on {
|
||||
max-height: 0;
|
||||
overflow: hidden;
|
||||
|
||||
-webkit-transition: all 0.3s ease-out;
|
||||
transition: all 0.3s ease-out;
|
||||
|
||||
@include mq(md) {
|
||||
// turn off animations if on a desktop width
|
||||
max-height: none;
|
||||
|
||||
-webkit-transition: none;
|
||||
transition: none;
|
||||
}
|
||||
}
|
||||
|
||||
[role="navigation"] {
|
||||
background: $accent-dark;
|
||||
|
||||
width: 100%;
|
||||
|
||||
@include mq(md) {
|
||||
width: auto;
|
||||
float: right;
|
||||
}
|
||||
|
||||
ul {
|
||||
margin: 10px 0 0;
|
||||
padding: 0;
|
||||
|
||||
@include mq(md) {
|
||||
margin: 0;
|
||||
}
|
||||
}
|
||||
|
||||
li {
|
||||
@include sans-serif;
|
||||
@include font-size(13);
|
||||
display: block;
|
||||
font-weight: 700;
|
||||
line-height: 16px;
|
||||
text-align: left;
|
||||
text-transform: uppercase;
|
||||
margin: 0 10px;
|
||||
|
||||
@include mq(md) {
|
||||
margin: 0;
|
||||
border: 0;
|
||||
float: left;
|
||||
text-align: left;
|
||||
}
|
||||
|
||||
&.active a {
|
||||
color: $attention;
|
||||
}
|
||||
}
|
||||
|
||||
a {
|
||||
color: $background-lightest;
|
||||
display: block;
|
||||
@include mq(md) {
|
||||
padding: 20px 0px;
|
||||
}
|
||||
text-decoration: none;
|
||||
background: none;
|
||||
|
||||
&:active, &:hover {
|
||||
color: $highlight;
|
||||
}
|
||||
}
|
||||
|
||||
.nav-primary {
|
||||
@include mq(md) {
|
||||
position: absolute;
|
||||
right: 0;
|
||||
top: 45px;
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
[role="banner"] [role="navigation"] {
|
||||
margin-top: 17px;
|
||||
|
||||
li {
|
||||
color: $attention;
|
||||
text-transform: none;
|
||||
margin-right: 0.5em;
|
||||
|
||||
}
|
||||
li a {
|
||||
display: inline;
|
||||
color: white;
|
||||
}
|
||||
li a.in-category {
|
||||
color: $attention;
|
||||
}
|
||||
|
||||
li + li:before {
|
||||
content: "·";
|
||||
color: $text-light;
|
||||
display: inline-block;
|
||||
margin-right: 0.25em;
|
||||
}
|
||||
}
|
||||
|
||||
[role="contentinfo"] {
|
||||
// Global Footer at bottom of page
|
||||
@include clearfix;
|
||||
@include sans-serif;
|
||||
position: relative;
|
||||
background: $attention;
|
||||
clear: both;
|
||||
margin-top: 0px;
|
||||
|
||||
& * {
|
||||
box-sizing: content-box;
|
||||
}
|
||||
|
||||
.container {
|
||||
overflow: hidden;
|
||||
}
|
||||
|
||||
.subfooter {
|
||||
@include clearfix;
|
||||
padding: 0 10px;
|
||||
|
||||
@include mq(md) {
|
||||
padding: 0;
|
||||
}
|
||||
|
||||
.col {
|
||||
&:first-child {
|
||||
h2 {
|
||||
border-top: 0;
|
||||
}
|
||||
}
|
||||
@include mq(md) {
|
||||
float: left;
|
||||
margin-bottom: -999px;
|
||||
padding: 0 3% 999px 0;
|
||||
width: 23%;
|
||||
}
|
||||
|
||||
&:first-child {
|
||||
margin-left: 0;
|
||||
padding-left: 0;
|
||||
}
|
||||
&.last-child {
|
||||
margin-right: 0;
|
||||
padding-right: 0;
|
||||
}
|
||||
}
|
||||
|
||||
}
|
||||
|
||||
h2 {
|
||||
@include heading-sans-serif;
|
||||
@include font-size(16, true);
|
||||
border-top: 1px solid $line;
|
||||
color: $background-lightest;
|
||||
font-weight: 700;
|
||||
margin: 20px 0 .83em 0;
|
||||
padding: 30px 0 10px;
|
||||
line-height: 1.6;
|
||||
|
||||
@include mq(md) {
|
||||
border: none;
|
||||
margin-top: 0;
|
||||
}
|
||||
}
|
||||
|
||||
ul {
|
||||
@include font-size(14);
|
||||
font-weight: 400;
|
||||
list-style: none;
|
||||
margin: 15px 0 0 0;
|
||||
padding: 0 0 30px;
|
||||
|
||||
li {
|
||||
margin: 10px 0 0;
|
||||
padding: 0;
|
||||
}
|
||||
|
||||
a {
|
||||
color: $white;
|
||||
text-decoration: none;
|
||||
background: none;
|
||||
|
||||
&:hover,
|
||||
&:active,
|
||||
&:focus {
|
||||
text-decoration: underline;
|
||||
background: none;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
.footer {
|
||||
background: $accent-dark;
|
||||
margin-top: 20px;
|
||||
padding: 10px 0 30px;
|
||||
color: $white;
|
||||
a {
|
||||
color: $accent-light;
|
||||
background: none;
|
||||
text-decoration: underline;
|
||||
|
||||
&:hover,
|
||||
&:active,
|
||||
&:focus {
|
||||
text-decoration: underline;
|
||||
background: none;
|
||||
}
|
||||
}
|
||||
svg {
|
||||
float: left;
|
||||
height: 50px;
|
||||
padding-top: 40px;
|
||||
padding-right: 30px;
|
||||
color: $accent-light;
|
||||
}
|
||||
.copyright {
|
||||
float: left;
|
||||
@include font-size(12);
|
||||
margin: 20px 0 0 10px;
|
||||
@include mq(md) {
|
||||
max-width: 80%;
|
||||
padding-top: 30px;
|
||||
margin: 0;
|
||||
}
|
||||
}
|
||||
.logo {
|
||||
margin-right: 0;
|
||||
margin-top: 28px;
|
||||
.mdzr-svg & {
|
||||
background-position: left center;
|
||||
margin-right: 0;
|
||||
margin-top: 20px;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
.logo {
|
||||
@include font-size(40);
|
||||
@include sans-serif;
|
||||
color: $accent-dark;
|
||||
display: block;
|
||||
font-weight: 700;
|
||||
height: 50px;
|
||||
margin: 10px;
|
||||
overflow: hidden;
|
||||
text-decoration: none;
|
||||
text-indent: 100%;
|
||||
width: 142px;
|
||||
@include mq(md) {
|
||||
float: left;
|
||||
margin: 20px 90px 0 0;
|
||||
}
|
||||
}
|
||||
|
||||
.thanks {
|
||||
@include font-size(12);
|
||||
color: $attention-dark;
|
||||
margin: 0;
|
||||
padding: 0;
|
||||
@include mq(md) {
|
||||
border: none;
|
||||
}
|
||||
|
||||
li {
|
||||
@include clearfix;
|
||||
margin: 0;
|
||||
padding: 17px 10px 11px;
|
||||
display: block;
|
||||
clear: both;
|
||||
@include mq(md) {
|
||||
background: none;
|
||||
float: left;
|
||||
clear: none;
|
||||
padding: 0 3% 0 0;
|
||||
width: 30%;
|
||||
|
||||
&.design {
|
||||
|
||||
span.ampersand, a {
|
||||
display: inline-block;
|
||||
vertical-align: top;
|
||||
&.threespot {
|
||||
clear: both;
|
||||
}
|
||||
|
||||
&.ampersand {
|
||||
position: relative;
|
||||
top: 6px;
|
||||
margin: 0 6px;
|
||||
line-height: 36px;
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
span.ampersand {
|
||||
line-height: 24px;
|
||||
}
|
||||
}
|
||||
|
||||
span {
|
||||
display: block;
|
||||
height: 24px;
|
||||
line-height: 36px;
|
||||
padding-right: 12px;
|
||||
white-space: nowrap;
|
||||
}
|
||||
|
||||
a {
|
||||
display: block;
|
||||
height: 33px;
|
||||
overflow: hidden;
|
||||
text-indent: -200px;
|
||||
width: 94px;
|
||||
|
||||
@include mq(md) {
|
||||
clear: both;
|
||||
margin-top: 5px;
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
.visuallyhidden {
|
||||
@include visuallyhidden;
|
||||
}
|
||||
.clearfix, .group-container {
|
||||
@include clearfix;
|
||||
}
|
||||
|
||||
@media screen and (max-width: 799px) {
|
||||
[role="banner"] .nav-menu-on .small-nav {
|
||||
|
||||
li {
|
||||
line-height: 1.5em;
|
||||
font-size: 1em;
|
||||
}
|
||||
li + li:before {
|
||||
display: none;
|
||||
}
|
||||
}
|
||||
|
||||
.icon-reorder {
|
||||
display: inline-block;
|
||||
background: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 96 96'%3E%3Cpath d='M96 20v-8c0-1.1-.4-2-1.2-2.8S93.1 8 92 8H4c-1.1 0-2 .4-2.8 1.2S0 10.9 0 12v8c0 1.1.4 2 1.2 2.8S2.9 24 4 24h88c1.1 0 2-.4 2.8-1.2S96 21.1 96 20zm0 32v-8c0-1.1-.4-2-1.2-2.8S93.1 40 92 40H4c-1.1 0-2 .4-2.8 1.2S0 42.9 0 44v8c0 1.1.4 2 1.2 2.8S2.9 56 4 56h88c1.1 0 2-.4 2.8-1.2S96 53.1 96 52zm0 32v-8c0-1.1-.4-2-1.2-2.8S93.1 72 92 72H4c-1.1 0-2 .4-2.8 1.2S0 74.9 0 76v8c0 1.1.4 2 1.2 2.8S2.9 88 4 88h88c1.1 0 2-.4 2.8-1.2S96 85.1 96 84z' fill='%23fff'/%3E%3C/svg%3E") center / contain no-repeat;
|
||||
width: 17px;
|
||||
vertical-align: middle;
|
||||
margin-bottom: 6px;
|
||||
}
|
||||
|
||||
main {
|
||||
flex-flow: column nowrap;
|
||||
}
|
||||
}
|
||||
|
||||
.copy-banner {
|
||||
background: $background-darkest;
|
||||
padding: 1px 10px;
|
||||
display: none;
|
||||
|
||||
@include mq(md) {
|
||||
display: block;
|
||||
padding: 1px 0;
|
||||
position: absolute;
|
||||
left: 0;
|
||||
right: 0;
|
||||
z-index: 2;
|
||||
top: 0;
|
||||
}
|
||||
|
||||
h1 {
|
||||
@include sans-serif;
|
||||
@include font-size(24, true);
|
||||
color: $core;
|
||||
font-weight: 300;
|
||||
line-height: 1.3;
|
||||
padding: 1px 0 6px;
|
||||
margin: .45em 0 .35em;
|
||||
letter-spacing: -1px;
|
||||
|
||||
@include mq(md) {
|
||||
@include font-size(32, true);
|
||||
|
||||
margin: .35em 0 .35em;
|
||||
color: $highlight;
|
||||
padding: 1px 0 6px;
|
||||
|
||||
}
|
||||
|
||||
a {
|
||||
font-weight: 300;
|
||||
background: none;
|
||||
color: $text-link-alternate;
|
||||
|
||||
&:hover, :active {
|
||||
background: none;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
.container {
|
||||
display: flex;
|
||||
flex-flow: row nowrap;
|
||||
align-items: center;
|
||||
}
|
||||
|
||||
.search {
|
||||
display: none;
|
||||
|
||||
@include mq(md) {
|
||||
display: block;
|
||||
height: 3rem !important;
|
||||
margin-left: 3rem;
|
||||
}
|
||||
}
|
||||
|
||||
@include mq(md) {
|
||||
.search-input-wrap {
|
||||
height: 3rem !important;
|
||||
right: 0;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
.search-active {
|
||||
.main {
|
||||
position: relative !important;
|
||||
}
|
||||
|
||||
.search-results {
|
||||
@include mq(md) {
|
||||
right: 0;
|
||||
left: auto;
|
||||
|
||||
max-height: calc(100vh - 200% - 60px) !important;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
.site-header {
|
||||
background: #D9E1E2;
|
||||
font-weight: 300;
|
||||
line-height: 1.3;
|
||||
@include font-size(24);
|
||||
|
||||
@include mq(md) {
|
||||
display: none;
|
||||
}
|
||||
|
||||
a {
|
||||
padding: 12.8px 10px 14.8px;
|
||||
|
||||
&:hover {
|
||||
background: none;
|
||||
}
|
||||
}
|
||||
|
||||
.icon {
|
||||
margin-left: 5px;
|
||||
}
|
||||
}
|
||||
|
||||
#main-header {
|
||||
display: none;
|
||||
|
||||
&.nav-open {
|
||||
&~ .side-bar .site-header {
|
||||
background: none;
|
||||
}
|
||||
|
||||
&~ .copy-banner {
|
||||
background: #F5F7F7;
|
||||
display: block;
|
||||
|
||||
& h1 {
|
||||
display: none;
|
||||
}
|
||||
|
||||
& .search {
|
||||
display: block;
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
.site-nav.nav-open {
|
||||
padding-top: .5rem;
|
||||
@include mq(md) {
|
||||
padding-top: 2rem;
|
||||
}
|
||||
}
|
||||
|
||||
.label {
|
||||
@include sans-serif;
|
||||
}
|
||||
|
||||
.banner-alert {
|
||||
@include sans-serif;
|
||||
@include warning-stripes;
|
||||
|
||||
/* To match the website */
|
||||
font-size: 1.125rem;
|
||||
text-decoration-thickness: 0.5px;
|
||||
text-underline-offset: 1px;
|
||||
|
||||
a {
|
||||
color: $text;
|
||||
|
||||
&:active,
|
||||
&:focus,
|
||||
&:hover {
|
||||
color: $text-hover;
|
||||
}
|
||||
|
||||
&:active,
|
||||
&:hover {
|
||||
outline: 0;
|
||||
}
|
||||
|
||||
&:not([class]) {
|
||||
text-decoration: underline;
|
||||
background: none;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
.version-wrapper {
|
||||
text-align: center;
|
||||
margin-bottom: 1rem;
|
||||
}
|
||||
|
||||
version-selector {
|
||||
z-index: 1;
|
||||
font-size: .9rem;
|
||||
|
||||
--normal-bg: linear-gradient(#{lighten($blue-300, 5%)}, #{darken($blue-300, 2%)});
|
||||
--hover-bg: linear-gradient(#{lighten($blue-300, 2%)}, #{darken($blue-300, 4%)});
|
||||
--link-color: #{$blue-300};
|
||||
}
|
||||
|
||||
@@ -1,59 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: k-NN Index
|
||||
nav_order: 1
|
||||
parent: k-NN
|
||||
has_children: false
|
||||
---
|
||||
|
||||
# k-NN Index
|
||||
|
||||
## knn_vector data type
|
||||
|
||||
The k-NN plugin introduces a custom data type, the `knn_vector`, that allows users to ingest their k-NN vectors
|
||||
into an OpenSearch index.
|
||||
|
||||
```json
|
||||
"my_vector": {
|
||||
"type": "knn_vector",
|
||||
"dimension": 4,
|
||||
"method": {
|
||||
"name": "hnsw",
|
||||
"space_type": "l2",
|
||||
"engine": "nmslib",
|
||||
"parameters": {
|
||||
"ef_construction": 128,
|
||||
"m": 24
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Mapping Pararameter | Required | Default | Updateable | Description
|
||||
:--- | :--- | :--- | :--- | :---
|
||||
`type` | true | n/a | false | The type of the field
|
||||
`dimension` | true | n/a | false | The vector dimension for the field
|
||||
`method` | false | null | false | The configuration for the Approximate nearest neighbor method
|
||||
`method.name` | true, if `method` is specified | n/a | false | The identifier for the nearest neighbor method. Currently, "hnsw" is the only valid method.
|
||||
`method.space_type` | false | "l2" | false | The vector space used to calculate the distance between vectors. Refer to [here]({{site.url}}{{site.baseurl}}/search-plugins/knn/approximate-knn#spaces)) to see available spaces.
|
||||
`method.engine` | false | "nmslib" | false | The approximate k-NN library to use for indexing and search. Currently, "nmslib" is the only valid engine.
|
||||
`method.parameters` | false | null | false | The parameters used for the nearest neighbor method.
|
||||
`method.parameters.ef_construction` | false | 512 | false | The size of the dynamic list used during k-NN graph creation. Higher values lead to a more accurate graph, but slower indexing speed. Only valid for "hnsw" method.
|
||||
`method.parameters.m` | false | 16 | false | The number of bidirectional links that the plugin creates for each new element. Increasing and decreasing this value can have a large impact on memory consumption. Keep this value between 2-100. Only valid for "hnsw" method
|
||||
|
||||
## Index settings
|
||||
|
||||
Additionally, the k-NN plugin introduces several index settings that can be used to configure the k-NN structure as well.
|
||||
|
||||
At the moment, several parameters defined in the settings are in the deprecation process. Those parameters should be set
|
||||
in the mapping instead of the index settings. Parameters set in the mapping will override the parameters set in the
|
||||
index settings. Setting the parameters in the mapping allows an index to have multiple `knn_vector` fields with
|
||||
different parameters.
|
||||
|
||||
Setting | Default | Updateable | Description
|
||||
:--- | :--- | :--- | :---
|
||||
`index.knn` | false | false | Whether the index should build hnsw graphs for the `knn_vector` fields. If set to false, the `knn_vector` fields will be stored in doc values, but Approximate k-NN search functionality will be disabled.
|
||||
`index.knn.algo_param.ef_search` | 512 | true | The size of the dynamic list used during k-NN searches. Higher values lead to more accurate but slower searches.
|
||||
`index.knn.algo_param.ef_construction` | 512 | false | (Deprecated in 1.0.0. Use the mapping parameters to set this value instead.) Refer to mapping definition.
|
||||
`index.knn.algo_param.m` | 16 | false | (Deprecated in 1.0.0. Use the mapping parameters to set this value instead.) Refer to mapping definition.
|
||||
`index.knn.space_type` | "l2" | false | (Deprecated in 1.0.0. Use the mapping parameters to set this value instead.) Refer to mapping definition.
|
||||
@@ -1,49 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Settings
|
||||
parent: Piped processing language
|
||||
nav_order: 3
|
||||
---
|
||||
|
||||
# Settings
|
||||
|
||||
The PPL plugin adds a few settings to the standard OpenSearch cluster settings. Most are dynamic, so you can change the default behavior of the plugin without restarting your cluster.
|
||||
|
||||
You can update these settings like any other cluster setting:
|
||||
|
||||
```json
|
||||
PUT _cluster/settings
|
||||
{
|
||||
"transient": {
|
||||
"plugins": {
|
||||
"ppl": {
|
||||
"enabled": "false"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Similarly, you can also update the settings by sending request to the plugin setting endpoint `_plugins/_query/settings` :
|
||||
```json
|
||||
PUT _plugins/_query/settings
|
||||
{
|
||||
"transient": {
|
||||
"plugins": {
|
||||
"ppl": {
|
||||
"enabled": "false"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Requests to `_plugins/_ppl` include index names in the request body, so they have the same access policy considerations as the `bulk`, `mget`, and `msearch` operations. If you set the `rest.action.multi.allow_explicit_index` parameter to `false`, the PPL plugin is disabled.
|
||||
|
||||
You can specify the settings shown in the following table:
|
||||
|
||||
Setting | Description | Default
|
||||
:--- | :--- | :---
|
||||
`plugins.ppl.enabled` | Change to `false` to disable the PPL component. | True
|
||||
`plugins.query.memory_limit` | Set heap memory usage limit. If a query crosses this limit, it's terminated. | 85%
|
||||
`plugins.query.size_limit` | Set the maximum number of results that you want to see. This impacts the accuracy of aggregation operations. For example, if you have 1000 documents in an index, by default, only 200 documents are extracted from the index for aggregation. | 200
|
||||
@@ -1,39 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Settings
|
||||
parent: SQL
|
||||
nav_order: 16
|
||||
---
|
||||
|
||||
# Settings
|
||||
|
||||
The SQL plugin adds a few settings to the standard OpenSearch cluster settings. Most are dynamic, so you can change the default behavior of the plugin without restarting your cluster.
|
||||
|
||||
You can update these settings like any other cluster setting:
|
||||
|
||||
```json
|
||||
PUT _cluster/settings
|
||||
{
|
||||
"transient" : {
|
||||
"plugins.sql.enabled" : false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Similarly, you can also update the settings by sending the request to the plugin setting endpoint `_plugins/_query/setting`:
|
||||
```json
|
||||
PUT _plugins/_query/settings
|
||||
{
|
||||
"transient" : {
|
||||
"plugins.sql.enabled" : false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Setting | Default | Description
|
||||
:--- | :--- | :---
|
||||
`plugins.sql.enabled` | True | Change to `false` to disable the plugin.
|
||||
`plugins.sql.slowlog` | 2 seconds | Configure the time limit (in seconds) for slow queries. The plugin logs slow queries as `Slow query: elapsed=xxx (ms)` in `opensearch.log`.
|
||||
`plugins.sql.cursor.keep_alive` | 1 minute | This value configures how long the cursor context is kept open. Cursor contexts are resource heavy, so we recommend a low value.
|
||||
`plugins.query.memory_limit` | 85% | This setting configures the heap memory usage limit for the circuit breaker of the query engine.
|
||||
`plugins.query.size_limit` | 200 | The setting sets the default size of index that the query engine fetches from OpenSearch.
|
||||
@@ -1,244 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Permissions
|
||||
parent: Access control
|
||||
nav_order: 50
|
||||
---
|
||||
|
||||
# Permissions
|
||||
|
||||
Each permission in the security plugin controls access to some action that the OpenSearch cluster can perform, such as indexing a document or checking cluster health.
|
||||
|
||||
Most permissions are self-describing. For example, `cluster:admin/ingest/pipeline/get` lets you retrieve information about ingest pipelines. _In many cases_, a permission correlates to a specific REST API operation, such as `GET _ingest/pipeline`.
|
||||
|
||||
Despite this correlation, permissions do **not** directly map to REST API operations. Operations such as `POST _bulk` and `GET _msearch` can access many indices and perform many actions in a single request. Even a simple request, such as `GET _cat/nodes`, performs several actions in order to generate its response.
|
||||
|
||||
In short, controlling access to the REST API is insufficient. Instead, the security plugin controls access to the underlying OpenSearch actions.
|
||||
|
||||
For example, consider the following `_bulk` request:
|
||||
|
||||
```json
|
||||
POST _bulk
|
||||
{ "delete": { "_index": "test-index", "_id": "tt2229499" } }
|
||||
{ "index": { "_index": "test-index", "_id": "tt1979320" } }
|
||||
{ "title": "Rush", "year": 2013 }
|
||||
{ "create": { "_index": "test-index", "_id": "tt1392214" } }
|
||||
{ "title": "Prisoners", "year": 2013 }
|
||||
{ "update": { "_index": "test-index", "_id": "tt0816711" } }
|
||||
{ "doc" : { "title": "World War Z" } }
|
||||
|
||||
```
|
||||
|
||||
For this request to succeed, you must have the following permissions for `test-index`:
|
||||
|
||||
- indices:data/write/bulk*
|
||||
- indices:data/write/delete
|
||||
- indices:data/write/index
|
||||
- indices:data/write/update
|
||||
|
||||
These permissions also allow you add, update, or delete documents (e.g. `PUT test-index/_doc/tt0816711`), because they govern the underlying OpenSearch actions of indexing and deleting documents rather than a specific API path and HTTP method.
|
||||
|
||||
|
||||
## Test permissions
|
||||
|
||||
If you want a user to have the absolute minimum set of permissions necessary to perform some function---the [principle of least privilege](https://en.wikipedia.org/wiki/Principle_of_least_privilege)----the best way is to send representative requests to your cluster as a new test user. In the case of a permissions error, the security plugin is very explicit about which permissions are missing. Consider this request and response:
|
||||
|
||||
```json
|
||||
GET _cat/shards?v
|
||||
|
||||
{
|
||||
"error": {
|
||||
"root_cause": [{
|
||||
"type": "security_exception",
|
||||
"reason": "no permissions for [indices:monitor/stats] and User [name=test-user, backend_roles=[], requestedTenant=null]"
|
||||
}]
|
||||
},
|
||||
"status": 403
|
||||
}
|
||||
```
|
||||
|
||||
[Create a user and a role]({{site.url}}{{site.baseurl}}/security-plugin/access-control/users-roles/), map the role to the user, and start sending signed requests using curl, Postman, or any other client. Then gradually add permissions to the role as you encounter errors. Even after you resolve one permissions error, the same request might generate new errors; the plugin only returns the first error it encounters, so keep trying until the request succeeds.
|
||||
|
||||
Rather than individual permissions, you can often achieve your desired security posture using a combination of the default action groups. See [Default action groups]({{site.url}}{{site.baseurl}}/security-plugin/access-control/default-action-groups/) for descriptions of the permissions that each group grants.
|
||||
{: .tip }
|
||||
|
||||
|
||||
## Cluster permissions
|
||||
|
||||
These permissions are for the cluster and can't be applied granularly. For example, you either have permissions to take snapshots (`cluster:admin/snapshot/create`) or you don't. You can't have permissions to take snapshots only for certain indices.
|
||||
|
||||
- cluster:admin/ingest/pipeline/delete
|
||||
- cluster:admin/ingest/pipeline/get
|
||||
- cluster:admin/ingest/pipeline/put
|
||||
- cluster:admin/ingest/pipeline/simulate
|
||||
- cluster:admin/ingest/processor/grok/get
|
||||
- cluster:admin/opendistro/ad/detector/delete
|
||||
- cluster:admin/opendistro/ad/detector/info
|
||||
- cluster:admin/opendistro/ad/detector/jobmanagement
|
||||
- cluster:admin/opendistro/ad/detector/preview
|
||||
- cluster:admin/opendistro/ad/detector/run
|
||||
- cluster:admin/opendistro/ad/detector/search
|
||||
- cluster:admin/opendistro/ad/detector/stats
|
||||
- cluster:admin/opendistro/ad/detector/write
|
||||
- cluster:admin/opendistro/ad/detectors/get
|
||||
- cluster:admin/opendistro/ad/result/search
|
||||
- cluster:admin/opendistro/ad/tasks/search
|
||||
- cluster:admin/opendistro/alerting/alerts/ack (acknowledge)
|
||||
- cluster:admin/opendistro/alerting/alerts/get
|
||||
- cluster:admin/opendistro/alerting/destination/delete
|
||||
- cluster:admin/opendistro/alerting/destination/email_account/delete
|
||||
- cluster:admin/opendistro/alerting/destination/email_account/get
|
||||
- cluster:admin/opendistro/alerting/destination/email_account/search
|
||||
- cluster:admin/opendistro/alerting/destination/email_account/write
|
||||
- cluster:admin/opendistro/alerting/destination/email_group/delete
|
||||
- cluster:admin/opendistro/alerting/destination/email_group/get
|
||||
- cluster:admin/opendistro/alerting/destination/email_group/search
|
||||
- cluster:admin/opendistro/alerting/destination/email_group/write
|
||||
- cluster:admin/opendistro/alerting/destination/get
|
||||
- cluster:admin/opendistro/alerting/destination/write
|
||||
- cluster:admin/opendistro/alerting/monitor/delete
|
||||
- cluster:admin/opendistro/alerting/monitor/execute
|
||||
- cluster:admin/opendistro/alerting/monitor/get
|
||||
- cluster:admin/opendistro/alerting/monitor/search
|
||||
- cluster:admin/opendistro/alerting/monitor/write
|
||||
- cluster:admin/opendistro/asynchronous_search/stats
|
||||
- cluster:admin/opendistro/asynchronous_search/delete
|
||||
- cluster:admin/opendistro/asynchronous_search/get
|
||||
- cluster:admin/opendistro/asynchronous_search/submit
|
||||
- cluster:admin/opendistro/ism/managedindex/add
|
||||
- cluster:admin/opendistro/ism/managedindex/change
|
||||
- cluster:admin/opendistro/ism/managedindex/remove
|
||||
- cluster:admin/opendistro/ism/managedindex/explain
|
||||
- cluster:admin/opendistro/ism/managedindex/retry
|
||||
- cluster:admin/opendistro/ism/policy/write
|
||||
- cluster:admin/opendistro/ism/policy/get
|
||||
- cluster:admin/opendistro/ism/policy/search
|
||||
- cluster:admin/opendistro/ism/policy/delete
|
||||
- cluster:admin/opendistro/rollup/index
|
||||
- cluster:admin/opendistro/rollup/get
|
||||
- cluster:admin/opendistro/rollup/search
|
||||
- cluster:admin/opendistro/rollup/delete
|
||||
- cluster:admin/opendistro/rollup/start
|
||||
- cluster:admin/opendistro/rollup/stop
|
||||
- cluster:admin/opendistro/rollup/explain
|
||||
- cluster:admin/opendistro/reports/definition/create
|
||||
- cluster:admin/opendistro/reports/definition/update
|
||||
- cluster:admin/opendistro/reports/definition/on_demand
|
||||
- cluster:admin/opendistro/reports/definition/delete
|
||||
- cluster:admin/opendistro/reports/definition/get
|
||||
- cluster:admin/opendistro/reports/definition/list
|
||||
- cluster:admin/opendistro/reports/instance/list
|
||||
- cluster:admin/opendistro/reports/instance/get
|
||||
- cluster:admin/opendistro/reports/menu/download
|
||||
- cluster:admin/reindex/rethrottle
|
||||
- cluster:admin/repository/delete
|
||||
- cluster:admin/repository/get
|
||||
- cluster:admin/repository/put
|
||||
- cluster:admin/repository/verify
|
||||
- cluster:admin/reroute
|
||||
- cluster:admin/script/delete
|
||||
- cluster:admin/script/get
|
||||
- cluster:admin/script/put
|
||||
- cluster:admin/settings/update
|
||||
- cluster:admin/snapshot/create
|
||||
- cluster:admin/snapshot/delete
|
||||
- cluster:admin/snapshot/get
|
||||
- cluster:admin/snapshot/restore
|
||||
- cluster:admin/snapshot/status
|
||||
- cluster:admin/snapshot/status*
|
||||
- cluster:admin/tasks/cancel
|
||||
- cluster:admin/tasks/test
|
||||
- cluster:admin/tasks/testunblock
|
||||
- cluster:monitor/allocation/explain
|
||||
- cluster:monitor/health
|
||||
- cluster:monitor/main
|
||||
- cluster:monitor/nodes/hot_threads
|
||||
- cluster:monitor/nodes/info
|
||||
- cluster:monitor/nodes/liveness
|
||||
- cluster:monitor/nodes/stats
|
||||
- cluster:monitor/nodes/usage
|
||||
- cluster:monitor/remote/info
|
||||
- cluster:monitor/state
|
||||
- cluster:monitor/stats
|
||||
- cluster:monitor/task
|
||||
- cluster:monitor/task/get
|
||||
- cluster:monitor/tasks/list
|
||||
|
||||
|
||||
## Index permissions
|
||||
|
||||
These permissions apply to an index or index pattern. You might want a user to have read access to all indices (i.e. `*`), but write access to only a few (e.g. `web-logs` and `product-catalog`).
|
||||
|
||||
- indices:admin/aliases
|
||||
- indices:admin/aliases/exists
|
||||
- indices:admin/aliases/get
|
||||
- indices:admin/analyze
|
||||
- indices:admin/cache/clear
|
||||
- indices:admin/close
|
||||
- indices:admin/close*
|
||||
- indices:admin/create (create indices)
|
||||
- indices:admin/data_stream/create
|
||||
- indices:admin/data_stream/delete
|
||||
- indices:admin/data_stream/get
|
||||
- indices:admin/delete (delete indices)
|
||||
- indices:admin/exists
|
||||
- indices:admin/flush
|
||||
- indices:admin/flush*
|
||||
- indices:admin/forcemerge
|
||||
- indices:admin/get (retrieve index and mapping)
|
||||
- indices:admin/index_template/delete
|
||||
- indices:admin/index_template/get
|
||||
- indices:admin/index_template/put
|
||||
- indices:admin/index_template/simulate
|
||||
- indices:admin/index_template/simulate_index
|
||||
- indices:admin/mapping/put
|
||||
- indices:admin/mappings/fields/get
|
||||
- indices:admin/mappings/fields/get*
|
||||
- indices:admin/mappings/get
|
||||
- indices:admin/open
|
||||
- indices:admin/refresh
|
||||
- indices:admin/refresh*
|
||||
- indices:admin/resolve/index
|
||||
- indices:admin/rollover
|
||||
- indices:admin/seq_no/global_checkpoint_sync
|
||||
- indices:admin/settings/update
|
||||
- indices:admin/shards/search_shards
|
||||
- indices:admin/shrink
|
||||
- indices:admin/synced_flush
|
||||
- indices:admin/template/delete
|
||||
- indices:admin/template/get
|
||||
- indices:admin/template/put
|
||||
- indices:admin/types/exists
|
||||
- indices:admin/upgrade
|
||||
- indices:admin/validate/query
|
||||
- indices:data/read/explain
|
||||
- indices:data/read/field_caps
|
||||
- indices:data/read/field_caps*
|
||||
- indices:data/read/get
|
||||
- indices:data/read/mget
|
||||
- indices:data/read/mget*
|
||||
- indices:data/read/msearch
|
||||
- indices:data/read/msearch/template
|
||||
- indices:data/read/mtv (multi-term vectors)
|
||||
- indices:data/read/mtv*
|
||||
- indices:data/read/scroll
|
||||
- indices:data/read/scroll/clear
|
||||
- indices:data/read/search
|
||||
- indices:data/read/search*
|
||||
- indices:data/read/search/template
|
||||
- indices:data/read/tv (term vectors)
|
||||
- indices:data/write/bulk
|
||||
- indices:data/write/bulk*
|
||||
- indices:data/write/delete (delete documents)
|
||||
- indices:data/write/delete/byquery
|
||||
- indices:data/write/index (add documents to existing indices)
|
||||
- indices:data/write/reindex
|
||||
- indices:data/write/update
|
||||
- indices:data/write/update/byquery
|
||||
- indices:monitor/data_stream/stats
|
||||
- indices:monitor/recovery
|
||||
- indices:monitor/segments
|
||||
- indices:monitor/settings/get
|
||||
- indices:monitor/shard_stores
|
||||
- indices:monitor/stats
|
||||
- indices:monitor/upgrade
|
||||
@@ -1,108 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Audit log storage types
|
||||
parent: Audit Logs
|
||||
nav_order: 10
|
||||
---
|
||||
|
||||
# Audit log storage types
|
||||
|
||||
Audit logs can take up quite a bit of space, so the security plugin offers several options for storage locations.
|
||||
|
||||
Setting | Description
|
||||
:--- | :---
|
||||
debug | Outputs to stdout. Useful for testing and debugging.
|
||||
internal_opensearch | Writes to an audit index on the current OpenSearch cluster.
|
||||
external_opensearch | Writes to an audit index on a remote OpenSearch cluster.
|
||||
webhook | Sends events to an arbitrary HTTP endpoint.
|
||||
log4j | Writes the events to a Log4j logger. You can use any Log4j [appender](https://logging.apache.org/log4j/2.x/manual/appenders.html), such as SNMP, JDBC, Cassandra, and Kafka.
|
||||
|
||||
You configure the output location in `opensearch.yml`:
|
||||
|
||||
```
|
||||
plugins.security.audit.type: <debug|internal_opensearch|external_opensearch|webhook|log4j>
|
||||
```
|
||||
|
||||
`external_opensearch`, `webhook`, and `log4j` all have additional configuration options. Details follow.
|
||||
|
||||
|
||||
## External OpenSearch
|
||||
|
||||
The `external_opensearch` storage type requires one or more OpenSearch endpoints with a host/IP address and port. Optionally, provide the index name and a document type.
|
||||
|
||||
```yml
|
||||
plugins.security.audit.type: external_opensearch
|
||||
plugins.security.audit.config.http_endpoints: [<endpoints>]
|
||||
plugins.security.audit.config.index: <indexname>
|
||||
plugins.security.audit.config.type: _doc
|
||||
```
|
||||
|
||||
The security plugin uses the OpenSearch REST API to send events, just like any other indexing request. For `plugins.security.audit.config.http_endpoints`, use a comma-separated list of hosts/IP addresses and the REST port (default 9200).
|
||||
|
||||
```
|
||||
plugins.security.audit.config.http_endpoints: [192.168.178.1:9200,192.168.178.2:9200]
|
||||
```
|
||||
|
||||
If you use `external_opensearch` and the remote cluster also uses the security plugin, you must supply some additional parameters for authentication. These parameters depend on which authentication type you configured for the remote cluster.
|
||||
|
||||
|
||||
### TLS settings
|
||||
|
||||
Name | Data Type | Description
|
||||
:--- | :--- | :---
|
||||
`plugins.security.audit.config.enable_ssl` | Boolean | If you enabled SSL/TLS on the receiving cluster, set to true. The default is false.
|
||||
`plugins.security.audit.config.verify_hostnames` | Boolean | Whether to verify the hostname of the SSL/TLS certificate of the receiving cluster. Default is true.
|
||||
`plugins.security.audit.config.pemtrustedcas_filepath` | String | The trusted root certificate of the external OpenSearch cluster, relative to the `config` directory.
|
||||
`plugins.security.audit.config.pemtrustedcas_content` | String | Instead of specifying the path (`plugins.security.audit.config.pemtrustedcas_filepath`), you can configure the Base64-encoded certificate content directly.
|
||||
`plugins.security.audit.config.enable_ssl_client_auth` | Boolean | Whether to enable SSL/TLS client authentication. If you set this to true, the audit log module sends the node's certificate along with the request. The receiving cluster can use this certificate to verify the identity of the caller.
|
||||
`plugins.security.audit.config.pemcert_filepath` | String | The path to the TLS certificate to send to the external OpenSearch cluster, relative to the `config` directory.
|
||||
`plugins.security.audit.config.pemcert_content` | String | Instead of specifying the path (`plugins.security.audit.config.pemcert_filepath`), you can configure the Base64-encoded certificate content directly.
|
||||
`plugins.security.audit.config.pemkey_filepath` | String | The path to the private key of the TLS certificate to send to the external OpenSearch cluster, relative to the `config` directory.
|
||||
`plugins.security.audit.config.pemkey_content` | String | Instead of specifying the path (`plugins.security.audit.config.pemkey_filepath`), you can configure the Base64-encoded certificate content directly.
|
||||
`plugins.security.audit.config.pemkey_password` | String | The password of the private key.
|
||||
|
||||
|
||||
### Basic auth settings
|
||||
|
||||
If you enabled HTTP basic authentication on the receiving cluster, use these settings to specify the username and password:
|
||||
|
||||
```yml
|
||||
plugins.security.audit.config.username: <username>
|
||||
plugins.security.audit.config.password: <password>
|
||||
```
|
||||
|
||||
|
||||
## Webhook
|
||||
|
||||
Use the following keys to configure the `webhook` storage type.
|
||||
|
||||
Name | Data Type | Description
|
||||
:--- | :--- | :---
|
||||
`plugins.security.audit.config.webhook.url` | String | The HTTP or HTTPS URL to send the logs to.
|
||||
`plugins.security.audit.config.webhook.ssl.verify` | Boolean | If true, the TLS certificate provided by the endpoint (if any) will be verified. If set to false, no verification is performed. You can disable this check if you use self-signed certificates.
|
||||
`plugins.security.audit.config.webhook.ssl.pemtrustedcas_filepath` | String | The path to the trusted certificate against which the webhook's TLS certificate is validated.
|
||||
`plugins.security.audit.config.webhook.ssl.pemtrustedcas_content` | String | Same as `plugins.security.audit.config.webhook.ssl.pemtrustedcas_content`, but you can configure the base 64 encoded certificate content directly.
|
||||
`plugins.security.audit.config.webhook.format` | String | The format in which the audit log message is logged, can be one of `URL_PARAMETER_GET`, `URL_PARAMETER_POST`, `TEXT`, `JSON`, `SLACK`. See [Formats](#formats).
|
||||
|
||||
|
||||
### Formats
|
||||
|
||||
Format | Description
|
||||
:--- | :---
|
||||
`URL_PARAMETER_GET` | Uses HTTP GET to send logs to the webhook URL. All logged information is appended to the URL as request parameters.
|
||||
`URL_PARAMETER_POST` | Uses HTTP POST to send logs to the webhook URL. All logged information is appended to the URL as request parameters.
|
||||
`TEXT` | Uses HTTP POST to send logs to the webhook URL. The request body contains the audit log message in plain text format.
|
||||
`JSON` | Uses HTTP POST to send logs to the webhook URL. The request body contains the audit log message in JSON format.
|
||||
`SLACK` | Uses HTTP POST to send logs to the webhook URL. The request body contains the audit log message in JSON format suitable for consumption by Slack. The default implementation returns `"text": "<AuditMessage#toText>"`.
|
||||
|
||||
|
||||
## Log4j
|
||||
|
||||
The `log4j` storage type lets you specify the name of the logger and log level.
|
||||
|
||||
```yml
|
||||
plugins.security.audit.config.log4j.logger_name: audit
|
||||
plugins.security.audit.config.log4j.level: INFO
|
||||
```
|
||||
|
||||
By default, the security plugin uses the logger name `audit` and logs the events on `INFO` level. Audit events are stored in JSON format.
|
||||
@@ -1,200 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Generate certificates
|
||||
parent: Configuration
|
||||
nav_order: 11
|
||||
---
|
||||
|
||||
# Generate certificates
|
||||
|
||||
If you don't have access to a certificate authority (CA) for your organization and want to use OpenSearch for non-demo purposes, you can generate your own self-signed certificates using [OpenSSL](https://www.openssl.org/){:target='\_blank'}.
|
||||
|
||||
You can probably find OpenSSL in the package manager for your operating system.
|
||||
|
||||
On CentOS, use Yum:
|
||||
|
||||
```bash
|
||||
sudo yum install openssl
|
||||
```
|
||||
|
||||
On macOS, use [Homebrew](https://brew.sh/){:target='\_blank'}:
|
||||
|
||||
```bash
|
||||
brew install openssl
|
||||
```
|
||||
|
||||
|
||||
## Generate a private key
|
||||
|
||||
The first step in this process is to generate a private key using the `genrsa` command. As the name suggests, you should keep this file private.
|
||||
|
||||
Private keys must be of sufficient length to be secure, so specify `2048`:
|
||||
|
||||
```bash
|
||||
openssl genrsa -out root-ca-key.pem 2048
|
||||
```
|
||||
|
||||
You can optionally add the `-aes256` option to encrypt the key using the AES-256 standard. This option requires a password.
|
||||
|
||||
|
||||
## Generate a root certificate
|
||||
|
||||
Next, use the key to generate a self-signed certificate for the root CA:
|
||||
|
||||
```bash
|
||||
openssl req -new -x509 -sha256 -key root-ca-key.pem -out root-ca.pem -days 730
|
||||
```
|
||||
|
||||
The default `-days` value of 30 is only useful for testing purposes. This sample command specifies 730 (two years) for the certificate expiration date, but use whatever value makes sense for your organization.
|
||||
|
||||
- The `-x509` option specifies that you want a self-signed certificate rather than a certificate request.
|
||||
- The `-sha256` option sets the hash algorithm to SHA-256. SHA-256 is the default in later versions of OpenSSL, but earlier versions might use SHA-1.
|
||||
|
||||
Follow the prompts to specify details for your organization. Together, these details form the distinguished name (DN) of your CA.
|
||||
|
||||
|
||||
## Generate an admin certificate
|
||||
|
||||
To generate an admin certificate, first create a new key:
|
||||
|
||||
```bash
|
||||
openssl genrsa -out admin-key-temp.pem 2048
|
||||
```
|
||||
|
||||
Then convert that key to PKCS#8 format for use in Java using a PKCS#12-compatible algorithm (3DES):
|
||||
|
||||
```bash
|
||||
openssl pkcs8 -inform PEM -outform PEM -in admin-key-temp.pem -topk8 -nocrypt -v1 PBE-SHA1-3DES -out admin-key.pem
|
||||
```
|
||||
|
||||
Next, create a certificate signing request (CSR). This file acts as an application to a CA for a signed certificate:
|
||||
|
||||
```bash
|
||||
openssl req -new -key admin-key.pem -out admin.csr
|
||||
```
|
||||
|
||||
Follow the prompts to fill in the details. You don't need to specify a challenge password. As noted in the [OpenSSL Cookbook](https://www.feistyduck.com/books/openssl-cookbook/){:target='\_blank'}, "Having a challenge password does not increase the security of the CSR in any way."
|
||||
|
||||
Finally, generate the certificate itself:
|
||||
|
||||
```bash
|
||||
openssl x509 -req -in admin.csr -CA root-ca.pem -CAkey root-ca-key.pem -CAcreateserial -sha256 -out admin.pem -days 730
|
||||
```
|
||||
|
||||
Just like the root certificate, use the `-days` option to specify an expiration date of longer than 30 days.
|
||||
|
||||
|
||||
## (Optional) Generate node and client certificates
|
||||
|
||||
Follow the steps in [Generate an admin certificate](#generate-an-admin-certificate) with new file names to generate a new certificate for each node and as many client certificates as you need. For example, you might generate one client certificate for OpenSearch Dashboards and another for a Python client. Each certificate should use its own private key.
|
||||
|
||||
If you generate node certificates and have `plugins.security.ssl.transport.enforce_hostname_verification` set to `true` (default), be sure to specify a common name (CN) for the certificate that matches the hostname of the intended node. If you want to use the same node certificate on all nodes (not recommended), set hostname verification to `false`. For more information, see [Configure TLS certificates]({{site.url}}{{site.baseurl}}/security-plugin/configuration/tls#advanced-hostname-verification-and-dns-lookup).
|
||||
|
||||
|
||||
## Sample script
|
||||
|
||||
If you already know the certificate details and don't want to specify them interactively, use the `-subj` option in your `root-ca.pem` and CSR commands. This script creates a root certificate, admin certificate, two node certificates, and a client certificate, all with an expiration dates of two years (730 days):
|
||||
|
||||
```bash
|
||||
#!/bin/sh
|
||||
# Root CA
|
||||
openssl genrsa -out root-ca-key.pem 2048
|
||||
openssl req -new -x509 -sha256 -key root-ca-key.pem -subj "/C=CA/ST=ONTARIO/L=TORONTO/O=ORG/OU=UNIT/CN=ROOT" -out root-ca.pem -days 730
|
||||
# Admin cert
|
||||
openssl genrsa -out admin-key-temp.pem 2048
|
||||
openssl pkcs8 -inform PEM -outform PEM -in admin-key-temp.pem -topk8 -nocrypt -v1 PBE-SHA1-3DES -out admin-key.pem
|
||||
openssl req -new -key admin-key.pem -subj "/C=CA/ST=ONTARIO/L=TORONTO/O=ORG/OU=UNIT/CN=ADMIN" -out admin.csr
|
||||
openssl x509 -req -in admin.csr -CA root-ca.pem -CAkey root-ca-key.pem -CAcreateserial -sha256 -out admin.pem -days 730
|
||||
# Node cert 1
|
||||
openssl genrsa -out node1-key-temp.pem 2048
|
||||
openssl pkcs8 -inform PEM -outform PEM -in node1-key-temp.pem -topk8 -nocrypt -v1 PBE-SHA1-3DES -out node1-key.pem
|
||||
openssl req -new -key node1-key.pem -subj "/C=CA/ST=ONTARIO/L=TORONTO/O=ORG/OU=UNIT/CN=node1.example.com" -out node1.csr
|
||||
openssl x509 -req -in node1.csr -CA root-ca.pem -CAkey root-ca-key.pem -CAcreateserial -sha256 -out node1.pem -days 730
|
||||
# Node cert 2
|
||||
openssl genrsa -out node2-key-temp.pem 2048
|
||||
openssl pkcs8 -inform PEM -outform PEM -in node2-key-temp.pem -topk8 -nocrypt -v1 PBE-SHA1-3DES -out node2-key.pem
|
||||
openssl req -new -key node2-key.pem -subj "/C=CA/ST=ONTARIO/L=TORONTO/O=ORG/OU=UNIT/CN=node2.example.com" -out node2.csr
|
||||
openssl x509 -req -in node2.csr -CA root-ca.pem -CAkey root-ca-key.pem -CAcreateserial -sha256 -out node2.pem -days 730
|
||||
# Client cert
|
||||
openssl genrsa -out client-key-temp.pem 2048
|
||||
openssl pkcs8 -inform PEM -outform PEM -in client-key-temp.pem -topk8 -nocrypt -v1 PBE-SHA1-3DES -out client-key.pem
|
||||
openssl req -new -key client-key.pem -subj "/C=CA/ST=ONTARIO/L=TORONTO/O=ORG/OU=UNIT/CN=CLIENT" -out client.csr
|
||||
openssl x509 -req -in client.csr -CA root-ca.pem -CAkey root-ca-key.pem -CAcreateserial -sha256 -out client.pem -days 730
|
||||
# Cleanup
|
||||
rm admin-key-temp.pem
|
||||
rm admin.csr
|
||||
rm node1-key-temp.pem
|
||||
rm node1.csr
|
||||
rm node2-key-temp.pem
|
||||
rm node2.csr
|
||||
rm client-key-temp.pem
|
||||
rm client.csr
|
||||
```
|
||||
|
||||
|
||||
## Add distinguished names to opensearch.yml
|
||||
|
||||
You must specify the distinguished names (DNs) for all admin and node certificates in `opensearch.yml` on all nodes. Using the certificates from the sample script above, part of `opensearch.yml` might look like this:
|
||||
|
||||
```yml
|
||||
plugins.security.authcz.admin_dn:
|
||||
- 'CN=ADMIN,OU=UNIT,O=ORG,L=TORONTO,ST=ONTARIO,C=CA'
|
||||
plugins.security.nodes_dn:
|
||||
- 'CN=node1.example.com,OU=UNIT,O=ORG,L=TORONTO,ST=ONTARIO,C=CA'
|
||||
- 'CN=node2.example.com,OU=UNIT,O=ORG,L=TORONTO,ST=ONTARIO,C=CA'
|
||||
```
|
||||
|
||||
But if you look at the `subject` of the certificate after creating it, you might see different formatting:
|
||||
|
||||
```
|
||||
subject=/C=CA/ST=ONTARIO/L=TORONTO/O=ORG/OU=UNIT/CN=node1.example.com
|
||||
```
|
||||
|
||||
If you compare this string to the ones above, you can see that you need to invert the order of elements and use commas rather than slashes. Enter this command to get the correct string:
|
||||
|
||||
```bash
|
||||
openssl x509 -subject -nameopt RFC2253 -noout -in node.pem
|
||||
```
|
||||
|
||||
Then copy and paste the output into `opensearch.yml`.
|
||||
|
||||
|
||||
## Add certificate files to opensearch.yml
|
||||
|
||||
This process generates many files, but these are the ones you need to add to each node:
|
||||
|
||||
- `root-ca.pem`
|
||||
- `admin.pem`
|
||||
- `admin-key.pem`
|
||||
- (Optional) `one-node-cert.pem`
|
||||
- (Optional) `one-node-key.pem`
|
||||
|
||||
On one node, the security configuration portion of `opensearch.yml` might look like this:
|
||||
|
||||
```yml
|
||||
plugins.security.ssl.transport.pemcert_filepath: node1.pem
|
||||
plugins.security.ssl.transport.pemkey_filepath: node1-key.pem
|
||||
plugins.security.ssl.transport.pemtrustedcas_filepath: root-ca.pem
|
||||
plugins.security.ssl.transport.enforce_hostname_verification: false
|
||||
plugins.security.ssl.http.enabled: true
|
||||
plugins.security.ssl.http.pemcert_filepath: node1.pem
|
||||
plugins.security.ssl.http.pemkey_filepath: node1-key.pem
|
||||
plugins.security.ssl.http.pemtrustedcas_filepath: root-ca.pem
|
||||
plugins.security.authcz.admin_dn:
|
||||
- 'CN=ADMIN,OU=UNIT,O=ORG,L=TORONTO,ST=ONTARIO,C=CA'
|
||||
plugins.security.nodes_dn:
|
||||
- 'CN=node1.example.com,OU=UNIT,O=ORG,L=TORONTO,ST=ONTARIO,C=CA'
|
||||
- 'CN=node2.example.com,OU=UNIT,O=ORG,L=TORONTO,ST=ONTARIO,C=CA'
|
||||
```
|
||||
|
||||
For more information about adding and using these certificates in your own setup, see [Docker security configuration]({{site.url}}{{site.baseurl}}//opensearch/install/docker-security/), [Configure TLS certificates]({{site.url}}{{site.baseurl}}/security-plugin/configuration/tls/), and [Client certificate authentication]({{site.url}}{{site.baseurl}}/security-plugin/configuration/client-auth/).
|
||||
|
||||
|
||||
## Run securityadmin.sh
|
||||
|
||||
After configuring your certificates and starting OpenSearch, run `securityadmin.sh` to initialize the security plugin. For information about how to use this script, see [Apply configuration changes]({{site.url}}{{site.baseurl}}/security-plugin/configuration/security-admin/).
|
||||
|
||||
|
||||
## OpenSearch Dashboards
|
||||
|
||||
For information on using your root CA and a client certificate to enable TLS for OpenSearch Dashboards, see [Configure TLS for OpenSearch Dashboards]({{site.url}}{{site.baseurl}}/dashboards/install/tls/).
|
||||
@@ -1,24 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Configuration
|
||||
nav_order: 5
|
||||
has_children: true
|
||||
has_toc: false
|
||||
redirect_from:
|
||||
- /security-plugin/configuration/
|
||||
---
|
||||
|
||||
# Security configuration
|
||||
|
||||
The plugin includes demo certificates so that you can get up and running quickly, but before using OpenSearch in a production environment, you must configure it manually:
|
||||
|
||||
1. [Replace the demo certificates]({{site.url}}{{site.baseurl}}/opensearch/install/docker-security).
|
||||
1. [Reconfigure opensearch.yml to use your certificates]({{site.url}}{{site.baseurl}}/security-plugin/configuration/tls).
|
||||
1. [Reconfigure config.yml to use your authentication backend]({{site.url}}{{site.baseurl}}/security-plugin/configuration/configuration/) (if you don't plan to use the internal user database).
|
||||
1. [Modify the configuration YAML files]({{site.url}}{{site.baseurl}}/security-plugin/configuration/yaml).
|
||||
1. If you plan to use the internal user database, [set a password policy in opensearch.yml]({{site.url}}{{site.baseurl}}/security-plugin/configuration/yaml/#opensearchyml).
|
||||
1. [Apply changes using securityadmin.sh]({{site.url}}{{site.baseurl}}/security-plugin/configuration/security-admin).
|
||||
1. Start OpenSearch.
|
||||
1. [Add users, roles, role mappings, and tenants]({{site.url}}{{site.baseurl}}/security-plugin/access-control/index/).
|
||||
|
||||
If you don't want to use the plugin, see [Disable security]({{site.url}}{{site.baseurl}}/security-plugin/configuration/disable).
|
||||
@@ -1,25 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: System indices
|
||||
parent: Configuration
|
||||
nav_order: 15
|
||||
---
|
||||
|
||||
# System indices
|
||||
|
||||
By default, OpenSearch has a protected system index, `.opendistro_security`, which you create using [securityadmin.sh]({{site.url}}{{site.baseurl}}/security-plugin/configuration/security-admin/). Even if your user account has read permissions for all indices, you can't directly access the data in this system index.
|
||||
|
||||
You can add additional system indices in in `opensearch.yml`. In addition to automatically creating `.opendistro_security`, the demo configuration adds several indices for the various OpenSearch plugins that integrate with the security plugin:
|
||||
|
||||
```yml
|
||||
plugins.security.system_indices.enabled: true
|
||||
plugins.security.system_indices.indices: [".opendistro-alerting-config", ".opendistro-alerting-alert*", ".opendistro-anomaly-results*", ".opendistro-anomaly-detector*", ".opendistro-anomaly-checkpoints", ".opendistro-anomaly-detection-state", ".opendistro-reports-*", ".opendistro-notifications-*", ".opendistro-notebooks", ".opendistro-asynchronous-search-response*"]
|
||||
```
|
||||
|
||||
To access these indices, you must authenticate with an [admin certificate]({{site.url}}{{site.baseurl}}/security-plugin/configuration/tls#configure-admin-certificates):
|
||||
|
||||
```bash
|
||||
curl -k --cert ./kirk.pem --key ./kirk-key.pem -XGET 'https://localhost:9200/.opendistro_security/_search'
|
||||
```
|
||||
|
||||
The alternative is to remove indices from the `plugins.security.system_indices.indices` list on each node and restart OpenSearch.
|
||||
@@ -1,348 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: YAML files
|
||||
parent: Configuration
|
||||
nav_order: 3
|
||||
---
|
||||
|
||||
# YAML files
|
||||
|
||||
Before running `securityadmin.sh` to load the settings into the `.opendistro_security` index, configure the YAML files in `plugins/opensearch-security/securityconfig`. You might want to back up these files so that you can reuse them on other clusters.
|
||||
|
||||
The best use of these YAML files is to configure [reserved and hidden resources]({{site.url}}{{site.baseurl}}/security-plugin/access-control/api#reserved-and-hidden-resources), such as the `admin` and `kibanaserver` users. You might find it easier to create other users, roles, mappings, action groups, and tenants using OpenSearch Dashboards or the REST API.
|
||||
|
||||
|
||||
## internal_users.yml
|
||||
|
||||
This file contains any initial users that you want to add to the security plugin's internal user database.
|
||||
|
||||
The file format requires a hashed password. To generate one, run `plugins/opensearch-security/tools/hash.sh -p <new-password>`. If you decide to keep any of the demo users, *change their passwords* and re-run [securityadmin.sh]({{site.url}}{{site.baseurl}}/security-plugin/configuration/security-admin/) to apply the new passwords.
|
||||
|
||||
```yml
|
||||
---
|
||||
# This is the internal user database
|
||||
# The hash value is a bcrypt hash and can be generated with plugin/tools/hash.sh
|
||||
|
||||
_meta:
|
||||
type: "internalusers"
|
||||
config_version: 2
|
||||
|
||||
# Define your internal users here
|
||||
new-user:
|
||||
hash: "$2y$12$88IFVl6IfIwCFh5aQYfOmuXVL9j2hz/GusQb35o.4sdTDAEMTOD.K"
|
||||
reserved: false
|
||||
hidden: false
|
||||
opensearch_security_roles:
|
||||
- "specify-some-security-role-here"
|
||||
backend_roles:
|
||||
- "specify-some-backend-role-here"
|
||||
attributes:
|
||||
attribute1: "value1"
|
||||
static: false
|
||||
|
||||
## Demo users
|
||||
|
||||
admin:
|
||||
hash: "$2a$12$VcCDgh2NDk07JGN0rjGbM.Ad41qVR/YFJcgHp0UGns5JDymv..TOG"
|
||||
reserved: true
|
||||
backend_roles:
|
||||
- "admin"
|
||||
description: "Demo admin user"
|
||||
|
||||
kibanaserver:
|
||||
hash: "$2a$12$4AcgAt3xwOWadA5s5blL6ev39OXDNhmOesEoo33eZtrq2N0YrU3H."
|
||||
reserved: true
|
||||
description: "Demo user for the OpenSearch Dashboards server"
|
||||
|
||||
kibanaro:
|
||||
hash: "$2a$12$JJSXNfTowz7Uu5ttXfeYpeYE0arACvcwlPBStB1F.MI7f0U9Z4DGC"
|
||||
reserved: false
|
||||
backend_roles:
|
||||
- "kibanauser"
|
||||
- "readall"
|
||||
attributes:
|
||||
attribute1: "value1"
|
||||
attribute2: "value2"
|
||||
attribute3: "value3"
|
||||
description: "Demo read-only user for OpenSearch dashboards"
|
||||
|
||||
logstash:
|
||||
hash: "$2a$12$u1ShR4l4uBS3Uv59Pa2y5.1uQuZBrZtmNfqB3iM/.jL0XoV9sghS2"
|
||||
reserved: false
|
||||
backend_roles:
|
||||
- "logstash"
|
||||
description: "Demo logstash user"
|
||||
|
||||
readall:
|
||||
hash: "$2a$12$ae4ycwzwvLtZxwZ82RmiEunBbIPiAmGZduBAjKN0TXdwQFtCwARz2"
|
||||
reserved: false
|
||||
backend_roles:
|
||||
- "readall"
|
||||
description: "Demo readall user"
|
||||
|
||||
snapshotrestore:
|
||||
hash: "$2y$12$DpwmetHKwgYnorbgdvORCenv4NAK8cPUg8AI6pxLCuWf/ALc0.v7W"
|
||||
reserved: false
|
||||
backend_roles:
|
||||
- "snapshotrestore"
|
||||
description: "Demo snapshotrestore user"
|
||||
```
|
||||
|
||||
## opensearch.yml
|
||||
|
||||
In addition to many OpenSearch settings, this file contains paths to TLS certificates and their attributes, such as distinguished names and trusted certificate authorities.
|
||||
|
||||
```yml
|
||||
plugins.security.ssl.transport.pemcert_filepath: esnode.pem
|
||||
plugins.security.ssl.transport.pemkey_filepath: esnode-key.pem
|
||||
plugins.security.ssl.transport.pemtrustedcas_filepath: root-ca.pem
|
||||
plugins.security.ssl.transport.enforce_hostname_verification: false
|
||||
plugins.security.ssl.http.enabled: true
|
||||
plugins.security.ssl.http.pemcert_filepath: esnode.pem
|
||||
plugins.security.ssl.http.pemkey_filepath: esnode-key.pem
|
||||
plugins.security.ssl.http.pemtrustedcas_filepath: root-ca.pem
|
||||
plugins.security.allow_unsafe_democertificates: true
|
||||
plugins.security.allow_default_init_securityindex: true
|
||||
plugins.security.authcz.admin_dn:
|
||||
- CN=kirk,OU=client,O=client,L=test, C=de
|
||||
|
||||
plugins.security.audit.type: internal_opensearch
|
||||
plugins.security.enable_snapshot_restore_privilege: true
|
||||
plugins.security.check_snapshot_restore_write_privileges: true
|
||||
plugins.security.restapi.roles_enabled: ["all_access", "security_rest_api_access"]
|
||||
plugins.security.system_indices.enabled: true
|
||||
plugins.security.system_indices.indices: [".opendistro-alerting-config", ".opendistro-alerting-alert*", ".opendistro-anomaly-results*", ".opendistro-anomaly-detector*", ".opendistro-anomaly-checkpoints", ".opendistro-anomaly-detection-state", ".opendistro-reports-*", ".opendistro-notifications-*", ".opendistro-notebooks", ".opendistro-asynchronous-search-response*"]
|
||||
node.max_local_storage_nodes: 3
|
||||
```
|
||||
|
||||
If you want to run your users' passwords against some validation, specify a regular expression (regex) in this file. You can also include an error message that loads when passwords don't pass validation. The following example demonstrates how to include a regex so OpenSearch requires new passwords to be a minimum of eight characters with at least one uppercase, one lowercase, one digit, and one special character.
|
||||
|
||||
Note that OpenSearch validates only users and passwords created through OpenSearch Dashboards or the REST API.
|
||||
|
||||
```yml
|
||||
plugins.security.restapi.password_validation_regex: '(?=.*[A-Z])(?=.*[^a-zA-Z\d])(?=.*[0-9])(?=.*[a-z]).{8,}'
|
||||
plugins.security.restapi.password_validation_error_message: "Password must be minimum 8 characters long and must contain at least one uppercase letter, one lowercase letter, one digit, and one special character."
|
||||
```
|
||||
|
||||
## whitelist.yml
|
||||
|
||||
You can use `whitelist.yml` to add any endpoints and HTTP requests to a list of allowed endpoints and requests. If enabled, all users except the super admin are allowed access to only the specified endpoints and HTTP requests, and all other HTTP requests associated with the endpoint are denied. For example, if GET `_cluster/settings` is added to the allow list, users cannot submit PUT requests to `_cluster/settings` to update cluster settings.
|
||||
|
||||
Note that while you can configure access to endpoints this way, for most cases, it is still best to configure permissions using the security plugin's users and roles, which have more granular settings.
|
||||
|
||||
```yml
|
||||
---
|
||||
_meta:
|
||||
type: "whitelist"
|
||||
config_version: 2
|
||||
|
||||
# Description:
|
||||
# enabled - feature flag.
|
||||
# if enabled is false, all endpoints are accessible.
|
||||
# if enabled is true, all users except the SuperAdmin can only submit the allowed requests to the specified endpoints.
|
||||
# SuperAdmin can access all APIs.
|
||||
# SuperAdmin is defined by the SuperAdmin certificate, which is configured with the opensearch.yml setting plugins.security.authcz.admin_dn:
|
||||
# Refer to the example setting in opensearch.yml to learn more about configuring SuperAdmin.
|
||||
#
|
||||
# requests - map of allow listed endpoints and HTTP requests
|
||||
|
||||
#this name must be config
|
||||
config:
|
||||
enabled: true
|
||||
requests:
|
||||
/_cluster/settings:
|
||||
- GET
|
||||
/_cat/nodes:
|
||||
- GET
|
||||
```
|
||||
|
||||
To enable PUT requests to cluster settings, add PUT to the list of allowed operations under `/_cluster/settings`.
|
||||
|
||||
```yml
|
||||
requests:
|
||||
/_cluster/settings:
|
||||
- GET
|
||||
- PUT
|
||||
```
|
||||
|
||||
You can also add custom indices to the allow list. `whitelist.yml` doesn't support wildcards, so you must manually specify all of the indices you want to add.
|
||||
|
||||
```yml
|
||||
requests: # Only allow GET requests to /sample-index1/_doc/1 and /sample-index2/_doc/1
|
||||
/sample-index1/_doc/1:
|
||||
- GET
|
||||
/sample-index2/_doc/1:
|
||||
- GET
|
||||
```
|
||||
|
||||
|
||||
## roles.yml
|
||||
|
||||
This file contains any initial roles that you want to add to the security plugin. Aside from some metadata, the default file is empty, because the security plugin has a number of static roles that it adds automatically.
|
||||
|
||||
```yml
|
||||
---
|
||||
complex-role:
|
||||
reserved: false
|
||||
hidden: false
|
||||
cluster_permissions:
|
||||
- "read"
|
||||
- "cluster:monitor/nodes/stats"
|
||||
- "cluster:monitor/task/get"
|
||||
index_permissions:
|
||||
- index_patterns:
|
||||
- "opensearch_dashboards_sample_data_*"
|
||||
dls: "{\"match\": {\"FlightDelay\": true}}"
|
||||
fls:
|
||||
- "~FlightNum"
|
||||
masked_fields:
|
||||
- "Carrier"
|
||||
allowed_actions:
|
||||
- "read"
|
||||
tenant_permissions:
|
||||
- tenant_patterns:
|
||||
- "analyst_*"
|
||||
allowed_actions:
|
||||
- "kibana_all_write"
|
||||
static: false
|
||||
_meta:
|
||||
type: "roles"
|
||||
config_version: 2
|
||||
```
|
||||
|
||||
|
||||
## roles_mapping.yml
|
||||
|
||||
```yml
|
||||
---
|
||||
manage_snapshots:
|
||||
reserved: true
|
||||
hidden: false
|
||||
backend_roles:
|
||||
- "snapshotrestore"
|
||||
hosts: []
|
||||
users: []
|
||||
and_backend_roles: []
|
||||
logstash:
|
||||
reserved: false
|
||||
hidden: false
|
||||
backend_roles:
|
||||
- "logstash"
|
||||
hosts: []
|
||||
users: []
|
||||
and_backend_roles: []
|
||||
own_index:
|
||||
reserved: false
|
||||
hidden: false
|
||||
backend_roles: []
|
||||
hosts: []
|
||||
users:
|
||||
- "*"
|
||||
and_backend_roles: []
|
||||
description: "Allow full access to an index named like the username"
|
||||
kibana_user:
|
||||
reserved: false
|
||||
hidden: false
|
||||
backend_roles:
|
||||
- "kibanauser"
|
||||
hosts: []
|
||||
users: []
|
||||
and_backend_roles: []
|
||||
description: "Maps kibanauser to kibana_user"
|
||||
complex-role:
|
||||
reserved: false
|
||||
hidden: false
|
||||
backend_roles:
|
||||
- "ldap-analyst"
|
||||
hosts: []
|
||||
users:
|
||||
- "new-user"
|
||||
and_backend_roles: []
|
||||
_meta:
|
||||
type: "rolesmapping"
|
||||
config_version: 2
|
||||
all_access:
|
||||
reserved: true
|
||||
hidden: false
|
||||
backend_roles:
|
||||
- "admin"
|
||||
hosts: []
|
||||
users: []
|
||||
and_backend_roles: []
|
||||
description: "Maps admin to all_access"
|
||||
readall:
|
||||
reserved: true
|
||||
hidden: false
|
||||
backend_roles:
|
||||
- "readall"
|
||||
hosts: []
|
||||
users: []
|
||||
and_backend_roles: []
|
||||
kibana_server:
|
||||
reserved: true
|
||||
hidden: false
|
||||
backend_roles: []
|
||||
hosts: []
|
||||
users:
|
||||
- "kibanaserver"
|
||||
and_backend_roles: []
|
||||
```
|
||||
|
||||
|
||||
## action_groups.yml
|
||||
|
||||
This file contains any initial action groups that you want to add to the security plugin.
|
||||
|
||||
Aside from some metadata, the default file is empty, because the security plugin has a number of static action groups that it adds automatically. These static action groups cover a wide variety of use cases and are a great way to get started with the plugin.
|
||||
|
||||
```yml
|
||||
---
|
||||
my-action-group:
|
||||
reserved: false
|
||||
hidden: false
|
||||
allowed_actions:
|
||||
- "indices:data/write/index*"
|
||||
- "indices:data/write/update*"
|
||||
- "indices:admin/mapping/put"
|
||||
- "indices:data/write/bulk*"
|
||||
- "read"
|
||||
- "write"
|
||||
static: false
|
||||
_meta:
|
||||
type: "actiongroups"
|
||||
config_version: 2
|
||||
```
|
||||
|
||||
## tenants.yml
|
||||
|
||||
You can use this file to specify and add any number of OpenSearch Dashboards tenants to your OpenSearch cluster. For more information about tenants, see [OpenSearch Dashboards multi-tenancy]({{site.url}}{{site.baseurl}}/security-plugin/access-control/multi-tenancy).
|
||||
|
||||
Like all of the other YAML files, we recommend you use `tenants.yml` to add any tenants you must have in your cluster, and then use OpenSearch Dashboards or the [REST API]({{site.url}}{{site.baseurl}}/security-plugin/access-control/api/#tenants) if you need to further configure or create any other tenants.
|
||||
|
||||
```yml
|
||||
---
|
||||
_meta:
|
||||
type: "tenants"
|
||||
config_version: 2
|
||||
admin_tenant:
|
||||
reserved: false
|
||||
description: "Demo tenant for admin user"
|
||||
```
|
||||
|
||||
## nodes_dn.yml
|
||||
|
||||
`nodes_dn.yml` lets you add certificates' [distinguished names (DNs)]({{site.url}}{{site.baseurl}}/security-plugin/configuration/generate-certificates/#add-distinguished-names-to-opensearchyml) an allow list to enable communication between any number of nodes and/or clusters. For example, a node that has the DN `CN=node1.example.com` in its allow list accepts communication from any other node or certificate that uses that DN.
|
||||
|
||||
The DNs get indexed into a [system index]({{site.url}}{{site.baseurl}}/security-plugin/configuration/system-indices) that only a super admin or an admin with a Transport Layer Security (TLS) certificate can access. If you want to programmatically add DNs to your allow lists, use the [REST API]({{site.url}}{{site.baseurl}}/security-plugin/access-control/api/#distinguished-names).
|
||||
|
||||
```yml
|
||||
---
|
||||
_meta:
|
||||
type: "nodesdn"
|
||||
config_version: 2
|
||||
|
||||
# Define nodesdn mapping name and corresponding values
|
||||
# cluster1:
|
||||
# nodes_dn:
|
||||
# - CN=*.example.com
|
||||
```
|
||||
@@ -1,36 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Upgrade from Kibana OSS to OpenSearch Dashboards
|
||||
nav_order: 50
|
||||
---
|
||||
|
||||
# Upgrade from Kibana OSS to OpenSearch Dashboards
|
||||
|
||||
Kibana OSS stores its visualizations and dashboards in one or more indices (`.kibana*`) on the Elasticsearch OSS cluster. As such, the most important step is to leave those indices intact as you upgrade from Elasticsearch OSS to OpenSearch.
|
||||
|
||||
Consider exporting all Kibana objects prior to starting the upgrade. In Kibana, choose **Stack Management**, **Saved Objects**, **Export objects**.
|
||||
{: .tip }
|
||||
|
||||
1. After you upgrade your Elasticsearch OSS cluster to OpenSearch, stop Kibana.
|
||||
|
||||
1. For safety, make a backup copy of `<kibana-dir>/config/kibana.yml`.
|
||||
|
||||
1. Extract the OpenSearch Dashboards tarball to a new directory.
|
||||
|
||||
1. Port your settings from `<kibana-dir>/config/kibana.yml` to `<dashboards-dir>/config/opensearch_dashboards.yml`.
|
||||
|
||||
In general, settings with `elasticsearch` in their names map to `opensearch` (e.g. `elasticsearch.shardTimeout` and `opensearch.shardTimeout`) and settings with `kibana` in their names map to `opensearchDashboards` (e.g. `kibana.defaultAppId` and `opensearchDashboards.defaultAppId`). Most other settings use the same names.
|
||||
|
||||
For a full list of OpenSearch Dashboards settings, see [here](https://github.com/opensearch-project/OpenSearch-Dashboards/blob/main/config/opensearch_dashboards.yml){:target='\_blank'}.
|
||||
|
||||
1. If your OpenSearch cluster uses the security plugin, preserve and modify the default settings in `opensearch_dashboards.yml`, particularly `opensearch.username` and `opensearch.password`.
|
||||
|
||||
If you disabled the security plugin on your OpenSearch cluster, remove or comment out all `opensearch_security` settings. Then run `rm -rf plugins/security-dashboards/` to remove the security plugin.
|
||||
|
||||
1. Start OpenSearch Dashboards:
|
||||
|
||||
```
|
||||
./bin/opensearch-dashboards
|
||||
```
|
||||
|
||||
1. Log in, and verify that your saved searches, visualizations, and dashboards are present.
|
||||
@@ -1,13 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Upgrade Docker clusters to OpenSearch
|
||||
nav_order: 25
|
||||
---
|
||||
|
||||
# Upgrade Docker clusters to OpenSearch
|
||||
|
||||
If you use a container orchestration system like Kubernetes (or manage your containers manually) and want to avoid downtime, think of the process not as an upgrade of each node, but as a decommissioning and replacement of each node. One by one, add OpenSearch nodes to the cluster and remove Elasticsearch OSS nodes, pointing to existing data volumes as necessary and allowing time for all indices to return to a green status prior to proceeding.
|
||||
|
||||
If you use Docker Compose, we highly recommend that you perform what amounts to a [cluster restart upgrade]({{site.url}}{{site.baseurl}}/upgrade-to/upgrade-to/). Update your cluster configuration with new images, new settings, and new environment variables, and test it. Then stop and start the cluster. This process requires downtime, but takes very few steps and lets you continue to treat the cluster as a single entity that you can reliably deploy and redeploy.
|
||||
|
||||
The most important step is to leave your data volumes intact. **Don't** run `docker-compose down -v`.
|
||||
@@ -1,21 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: About the process
|
||||
nav_order: 1
|
||||
redirect_from:
|
||||
- /upgrade-to/
|
||||
---
|
||||
|
||||
# About the process
|
||||
|
||||
The process of upgrading from Elasticsearch OSS (including Open Distro for Elasticsearch) to OpenSearch varies depending on your current version of Elasticsearch OSS, install type, tolerance for downtime, and cost-sensitivity. Rather than concrete steps to cover every situation, we have general guidance for the process.
|
||||
|
||||
Three approaches exist:
|
||||
|
||||
- Use a snapshot to [migrate your Elasticsearch OSS data]({{site.url}}{{site.baseurl}}/upgrade-to/snapshot-migrate/) to a new OpenSearch cluster.
|
||||
- Perform a [rolling upgrade or cluster restart upgrade]({{site.url}}{{site.baseurl}}/upgrade-to/upgrade-to/) on your existing nodes.
|
||||
- Replace existing Elasticsearch OSS nodes with new OpenSearch nodes. Node replacement is most popular when upgrading [Docker clusters]({{site.url}}{{site.baseurl}}/upgrade-to/docker-upgrade-to/).
|
||||
|
||||
Regardless of your approach, to safeguard against data loss, we recommend that you take a [snapshot]({{site.url}}{{site.baseurl}}/opensearch/snapshot-restore/) of all indices prior to any migration.
|
||||
|
||||
If your existing clients include a version check, such as recent versions of Logstash OSS and Filebeat OSS, [check compatibility]({{site.url}}{{site.baseurl}}/clients/agents-and-ingestion-tools/index/) before upgrading.
|
||||
@@ -1,11 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Use snapshots to migrate data
|
||||
nav_order: 5
|
||||
---
|
||||
|
||||
# Use snapshots to migrate data
|
||||
|
||||
One popular approach is to take a [snapshot]({{site.url}}{{site.baseurl}}/opensearch/snapshot-restore/) of your Elasticsearch OSS 6.x or 7.x indices, [create an OpenSearch cluster]({{site.url}}{{site.baseurl}}/opensearch/install/), restore the snapshot on the new cluster, and point your clients to the new host.
|
||||
|
||||
The snapshot approach can mean running two clusters in parallel, but lets you validate that the OpenSearch cluster is working in a way that meets your needs prior to modifying the Elasticsearch OSS cluster.
|
||||
@@ -1,181 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Upgrade from Elasticsearch OSS to OpenSearch
|
||||
nav_order: 15
|
||||
---
|
||||
|
||||
# Upgrade from Elasticsearch OSS to OpenSearch
|
||||
|
||||
If you want to upgrade from an existing Elasticsearch OSS cluster to OpenSearch and find the [snapshot approach]({{site.url}}{{site.baseurl}}/upgrade-to/snapshot-migrate/) unappealing, you can upgrade your existing nodes from Elasticsearch OSS to OpenSearch.
|
||||
|
||||
If your existing cluster runs an older version of Elasticsearch OSS, the first step is to upgrade to version 6.x or 7.x. Elasticsearch OSS supports two types of upgrades: rolling and cluster restart.
|
||||
|
||||
- Rolling upgrades let you shut down one node at a time for minimal disruption of service.
|
||||
|
||||
Rolling upgrades work between minor versions (e.g. 6.5 to 6.8) and also support a single path to the next major version (e.g. 6.8 to 7.10.2). Performing these upgrades might require intermediate upgrades to arrive at your desired version and can affect cluster performance as nodes leave and rejoin, but the cluster remains available throughout the process.
|
||||
|
||||
- Cluster restart upgrades require you to shut down all nodes, perform the upgrade, and restart the cluster.
|
||||
|
||||
Cluster restart upgrades work between minor versions (e.g. 6.5 to 6.8) and the next major version (for example, 6.x to 7.10.2). Cluster restart upgrades are faster to perform and require fewer intermediate upgrades, but require downtime.
|
||||
|
||||
|
||||
## Upgrade paths
|
||||
|
||||
Elasticsearch OSS version | Rolling upgrade path | Cluster restart upgrade path
|
||||
:--- | :--- | :---
|
||||
5.x | Upgrade to 5.6, upgrade to 6.8, reindex all 5.x indices, upgrade to 7.10.2, and upgrade to OpenSearch. | Upgrade to 6.8, reindex all 5.x indices, and upgrade to OpenSearch.
|
||||
6.x | Upgrade to 6.8, upgrade to 7.10.2, and upgrade to OpenSearch. | Upgrade to OpenSearch.
|
||||
7.x | Upgrade to OpenSearch. | Upgrade to OpenSearch.
|
||||
|
||||
If you are upgrading an Open Distro for Elasticsearch cluster, we recommend first upgrading to ODFE 1.13 and then upgrading to OpenSearch.
|
||||
{: .note }
|
||||
|
||||
|
||||
## Upgrade Elasticsearch OSS
|
||||
|
||||
1. Disable shard allocation to prevent Elasticsearch OSS from replicating shards as you shut down nodes:
|
||||
|
||||
```json
|
||||
PUT _cluster/settings
|
||||
{
|
||||
"persistent": {
|
||||
"cluster.routing.allocation.enable": "primaries"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
1. Stop Elasticsearch OSS on one node (rolling upgrade) or all nodes (cluster restart upgrade).
|
||||
|
||||
On Linux distributions that use systemd, use this command:
|
||||
|
||||
```bash
|
||||
sudo systemctl stop elasticsearch.service
|
||||
```
|
||||
|
||||
For tarball installations, find the process ID (`ps aux`) and kill it (`kill <pid>`).
|
||||
|
||||
1. Upgrade the node (rolling) or all nodes (cluster restart).
|
||||
|
||||
The exact command varies by package manager, but likely looks something like this:
|
||||
|
||||
```bash
|
||||
sudo yum install elasticsearch-oss-7.10.2 --enablerepo=elasticsearch
|
||||
```
|
||||
|
||||
For tarball installations, extract to a new directory to ensure you **do not overwrite** your `config`, `data`, and `logs` directories. Ideally, these directories should have their own, independent paths and *not* be colocated with the Elasticsearch application directory. Then set the `ES_PATH_CONF` environment variable to the directory that contains `elasticsearch.yml` (e.g. `/etc/elasticesarch/`). In `elasticsearch.yml`, set `path.data` and `path.logs` to your `data` and `logs` directories (e.g. `/var/lib/elasticsearch` and `/var/log/opensearch`).
|
||||
|
||||
1. Restart Elasticsearch OSS on the node (rolling) or all nodes (cluster restart).
|
||||
|
||||
On Linux distributions that use systemd, use this command:
|
||||
|
||||
```bash
|
||||
sudo systemctl start elasticsearch.service
|
||||
```
|
||||
|
||||
For tarball installations, run `./bin/elasticsearch -d`.
|
||||
|
||||
1. Wait for the node to rejoin the cluster (rolling) or for the cluster to start (cluster restart). Check the `_nodes` summary to verify that all nodes are available and running the expected version:
|
||||
|
||||
```bash
|
||||
# Elasticsearch OSS
|
||||
curl -XGET 'localhost:9200/_nodes/_all?pretty=true'
|
||||
# Open Distro for Elasticsearch with security plugin enabled
|
||||
curl -XGET 'https://localhost:9200/_nodes/_all?pretty=true' -u 'admin:admin' -k
|
||||
```
|
||||
|
||||
Specifically, check the `nodes.<node-id>.version` portion of the response. Also check `_cat/indices?v` for a green status on all indices.
|
||||
|
||||
1. (Rolling) Repeat steps 2--5 until all nodes are using the new version.
|
||||
|
||||
1. After all nodes are using the new version, re-enable shard allocation:
|
||||
|
||||
```json
|
||||
PUT _cluster/settings
|
||||
{
|
||||
"persistent": {
|
||||
"cluster.routing.allocation.enable": "all"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
1. If you upgraded from 5.x to 6.x, [reindex]({{site.url}}{{site.baseurl}}/opensearch/reindex-data/) all indices.
|
||||
|
||||
1. Repeat all steps as necessary until you arrive at your desired Elasticsearch OSS version.
|
||||
|
||||
|
||||
## Upgrade to OpenSearch
|
||||
|
||||
1. Disable shard allocation to prevent Elasticsearch OSS from replicating shards as you shut down nodes:
|
||||
|
||||
```json
|
||||
PUT _cluster/settings
|
||||
{
|
||||
"persistent": {
|
||||
"cluster.routing.allocation.enable": "primaries"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
1. Stop Elasticsearch OSS on one node (rolling upgrade) or all nodes (cluster restart upgrade).
|
||||
|
||||
On Linux distributions that use systemd, use this command:
|
||||
|
||||
```bash
|
||||
sudo systemctl stop elasticsearch.service
|
||||
```
|
||||
|
||||
For tarball installations, find the process ID (`ps aux`) and kill it (`kill <pid>`).
|
||||
|
||||
1. Upgrade the node (rolling) or all nodes (cluster restart).
|
||||
|
||||
1. Extract the OpenSearch tarball to a new directory to ensure you **do not overwrite** your Elasticsearch OSS `config`, `data`, and `logs` directories.
|
||||
|
||||
1. (Optional) Copy or move your Elasticsearch OSS `data` and `logs` directories to new paths. For example, you might move `/var/lib/elasticsearch` to `/var/lib/opensearch`.
|
||||
|
||||
1. Set the `OPENSEARCH_PATH_CONF` environment variable to the directory that contains `opensearch.yml` (e.g. `/etc/opensearch`).
|
||||
|
||||
1. In `opensearch.yml`, set `path.data` and `path.logs`. You might also want to disable the security plugin for now. `opensearch.yml` might look something like this:
|
||||
|
||||
```yml
|
||||
path.data: /var/lib/opensearch
|
||||
path.logs: /var/log/opensearch
|
||||
plugins.security.disabled: true
|
||||
```
|
||||
|
||||
1. Port your settings from `elasticsearch.yml` to `opensearch.yml`. Most settings use the same names. At a minimum, specify `cluster.name`, `node.name`, `discovery.seed_hosts`, and `cluster.initial_master_nodes`.
|
||||
|
||||
1. (Optional) If you're actively connecting to the cluster with legacy clients that check for a particular version number, such as Logstash OSS, add a [compatibility setting]({{site.url}}{{site.baseurl}}/clients/agents-and-ingestion-tools/) to `opensearch.yml`:
|
||||
|
||||
```yml
|
||||
compatibility.override_main_response_version: true
|
||||
```
|
||||
|
||||
1. (Optional) Add your certificates to your `config` directory, add them to `opensearch.yml`, and initialize the security plugin.
|
||||
|
||||
1. Start OpenSearch on the node (rolling) or all nodes (cluster restart).
|
||||
|
||||
For the tarball, run `./bin/opensearch -d`.
|
||||
|
||||
1. Wait for the OpenSearch node to rejoin the cluster (rolling) or for the cluster to start (cluster restart). Check the `_nodes` summary to verify that all nodes are available and running the expected version:
|
||||
|
||||
```bash
|
||||
# Security plugin disabled
|
||||
curl -XGET 'localhost:9200/_nodes/_all?pretty=true'
|
||||
# Security plugin enabled
|
||||
curl -XGET -k -u 'admin:admin' 'https://localhost:9200/_nodes/_all?pretty=true'
|
||||
```
|
||||
|
||||
Specifically, check the `nodes.<node-id>.version` portion of the response. Also check `_cat/indices?v` for a green status on all indices.
|
||||
|
||||
1. (Rolling) Repeat steps 2--5 until all nodes are using OpenSearch.
|
||||
|
||||
1. After all nodes are using the new version, re-enable shard allocation:
|
||||
|
||||
```json
|
||||
PUT _cluster/settings
|
||||
{
|
||||
"persistent": {
|
||||
"cluster.routing.allocation.enable": "all"
|
||||
}
|
||||
}
|
||||
```
|
||||
Binary file not shown.
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user