Skip to content

Add new _scale API as part of OpenSearch Reader/Writer Separation #9762

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
May 2, 2025
Merged

Add new _scale API as part of OpenSearch Reader/Writer Separation #9762

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
91b469c
Add new scale API
prudhvigodithi Apr 29, 2025
2c14b6e
Merge branch 'main' into scale
Naarcha-AWS Apr 29, 2025
4292543
Update scale.md
Naarcha-AWS May 1, 2025
703d949
Apply suggestions from code review
Naarcha-AWS May 2, 2025
82f9de1
Merge branch 'main' into scale
Naarcha-AWS May 2, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
75 changes: 75 additions & 0 deletions _api-reference/index-apis/scale.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,75 @@
---
layout: default
title: Scale
parent: Index APIs
nav_order: 50
---

# Scale
**Introduced 3.0**
{: .label .label-purple }

The Scale API allows you to enable or disable the `search_only` mode on an index. When an index is in `search_only` mode, it retains only its search replicas and scales down primary and regular replica shards. This optimization helps reduce resource consumption during periods of low write activity while maintaining search capabilities.

This feature supports scenarios such as scale-to-zero deployments and reader/writer separation patterns, which can significantly improve resource utilization and reduce costs in production environments.

If you are using the Security plugin, you must have the `manage index` privileges.
{: .note}

## Endpoints

```json
POST /<index>/_scale
```

## Path parameters

The following table lists the available path parameters.

| Parameter | Required | Data type | Description |
| :--- | :--- | :--- | :--- |
| `index` | **Required** | String | The name of the index to scale. Wildcards are not supported. |

## Request body fields

The following table lists the available request body fields.

| Field | Required | Data type | Description |
| :--- | :--- | :--- | :--- |
| `search_only` | **Required** | Boolean | When `true`, enables search-only mode on the index. When `false`, disables search-only mode and restores the index to normal operations. |

## Example requests

### Enable search-only mode

Check failure on line 43 in _api-reference/index-apis/scale.md

View workflow job for this annotation

GitHub Actions / style-job 

[vale] reported by reviewdog 🐶
[OpenSearch.StackedHeadings] Do not stack headings. Insert an introductory sentence between headings.

Raw Output:
{"message": "[OpenSearch.StackedHeadings] Do not stack headings. Insert an introductory sentence between headings.", "location": {"path": "_api-reference/index-apis/scale.md", "range": {"start": {"line": 43, "column": 1}}}, "severity": "ERROR"}

The following request enables search-only mode for an index named `my-index`:

```json
POST /my-index/_scale
{
"search_only": true
}
```
{% include copy-curl.html %}

### Disable search-only mode

The following request disables search-only mode and returns the index to normal operations:

```json
POST /my-index/_scale
{
"search_only": false
}
```
{% include copy-curl.html %}

## Example response

The API returns the following response:

```json
{
"acknowledged": true
}
```
Loading