From 6a198313819cc12c5784498b3e18201819be4d81 Mon Sep 17 00:00:00 2001 From: Ruirui Zhang Date: Mon, 28 Oct 2024 15:21:38 -0700 Subject: [PATCH 1/6] add querygroup api documentation Signed-off-by: Ruirui Zhang --- .../query-group-lifecycle-api.md | 169 ++++++++++++++++++ 1 file changed, 169 insertions(+) create mode 100644 _tuning-your-cluster/availability-and-recovery/workload-management/query-group-lifecycle-api.md diff --git a/_tuning-your-cluster/availability-and-recovery/workload-management/query-group-lifecycle-api.md b/_tuning-your-cluster/availability-and-recovery/workload-management/query-group-lifecycle-api.md new file mode 100644 index 00000000000..e36e2bbc6f8 --- /dev/null +++ b/_tuning-your-cluster/availability-and-recovery/workload-management/query-group-lifecycle-api.md @@ -0,0 +1,169 @@ +--- +layout: default +title: Query Group Lifecycle API +nav_order: 20 +parent: Workload management +grand_parent: Availability and recovery +--- +# Query Group Lifecycle API + +The Query Group Lifecycle API in OpenSearch provides functionality to create, update, get, and delete query groups, enabling users to organize and control sets of related queries under specific groups. + +## Create query group +Creates a new Query group with the specified properties. + +#### Path and HTTP method +```json +PUT _wlm/query_group +``` +#### Example request +```json +PUT _wlm/query_group +{ + "name": "analytics", + "resiliency_mode": "enforced", + "resource_limits": { + "cpu": 0.4, + "memory": 0.2 + } +} +``` +#### Example response +```json +{ + "_id":"preXpc67RbKKeCyka72_Gw", + "name":"analytics", + "resiliency_mode":"enforced", + "resource_limits":{ + "cpu":0.4, + "memory":0.2 + }, + "updated_at":1726270184642 +} +``` + +## Update query group +Updates the properties of an existing Query Group. + +#### Path and HTTP method +```json +PUT _wlm/query_group/ +``` +#### Example request +```json +PUT _wlm/query_group/analytics +{ + "resiliency_mode": "monitor", + "resource_limits": { + "cpu": 0.41, + "memory": 0.21 + } +} +``` +#### Example response +```json +{ + "_id":"preXpc67RbKKeCyka72_Gw", + "name":"analytics", + "resiliency_mode":"monitor", + "resource_limits":{ + "cpu":0.41, + "memory":0.21 + }, + "updated_at":1726270333804 +} +``` +## Get query group +Retrieves the properties of the provided Query Group. + +#### Path and HTTP method +```json +GET _wlm/query_group/ +``` +#### Example request +```json +GET _wlm/query_group/analytics +``` +#### Example response +```json +{ + "query_groups": [ + { + "_id": "preXpc67RbKKeCyka72_Gw", + "name": "analytics", + "resiliency_mode": "monitor", + "resource_limits": { + "cpu": 0.41, + "memory": 0.21 + }, + "updated_at": 1726270333804 + } + ] +} +``` +## Get all query groups +Retrieves the properties of all Query groups in the cluster. + +#### Path and HTTP method +```json +GET _wlm/query_group +``` +#### Example request +```json +GET _wlm/query_group +``` +#### Example response +```json +{ + "query_groups": [ + { + "_id": "preXpc67RbKKeCyka72_Gw", + "name": "analytics", + "resiliency_mode": "monitor", + "resource_limits": { + "cpu": 0.41, + "memory": 0.21 + }, + "updated_at": 1726270333804 + }, + { + "_id": "pviC2vuep2Kc84yka43_Np", + "name": "analytics_2", + "resiliency_mode": "monitor", + "resource_limits": { + "cpu": 0.15, + "memory": 0.3 + }, + "updated_at": 1726270840583 + } + ] +} +``` +## Delete query group +Delete the provided Query group. + +#### Path and HTTP method +```json +DELETE _wlm/query_group/ +``` +#### Example request +```json +DELETE _wlm/query_group/analytics +``` +#### Example response +```json +{ + "acknowledged":true +} +``` + +## Fields +The query group lifecycle API contains the following fields. + +| Field | Description | +|:-----------------------|:-------------------------------------------------------------------------------------------| +| `_id` | The id of the query group. | +| `name` | The name of the query group. | +| `resiliency_mode` | The resiliency mode of the query group. Valid modes are `enforced`, `soft`, and `monitor`. | +| `resource_limits` | The resource limits of the query group. Valid resources are `cpu` and `memory`. | +| `updated_at` | The last updated time of the query group. | From 6b12cc7c4e44eabfa257e3b84b443723a872f8fb Mon Sep 17 00:00:00 2001 From: Ruirui Zhang Date: Mon, 28 Oct 2024 15:30:50 -0700 Subject: [PATCH 2/6] fix wording Signed-off-by: Ruirui Zhang --- .../workload-management/query-group-lifecycle-api.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/_tuning-your-cluster/availability-and-recovery/workload-management/query-group-lifecycle-api.md b/_tuning-your-cluster/availability-and-recovery/workload-management/query-group-lifecycle-api.md index e36e2bbc6f8..8b599532955 100644 --- a/_tuning-your-cluster/availability-and-recovery/workload-management/query-group-lifecycle-api.md +++ b/_tuning-your-cluster/availability-and-recovery/workload-management/query-group-lifecycle-api.md @@ -1,11 +1,11 @@ --- layout: default -title: Query Group Lifecycle API +title: Query group lifecycle API nav_order: 20 parent: Workload management grand_parent: Availability and recovery --- -# Query Group Lifecycle API +# Query group lifecycle API The Query Group Lifecycle API in OpenSearch provides functionality to create, update, get, and delete query groups, enabling users to organize and control sets of related queries under specific groups. From 9224e38d2cbbbecc03aa0f290fbcb9459c3ec94b Mon Sep 17 00:00:00 2001 From: Ruirui Zhang Date: Tue, 29 Oct 2024 16:52:45 -0700 Subject: [PATCH 3/6] fix wording Signed-off-by: Ruirui Zhang --- .../workload-management/query-group-lifecycle-api.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/_tuning-your-cluster/availability-and-recovery/workload-management/query-group-lifecycle-api.md b/_tuning-your-cluster/availability-and-recovery/workload-management/query-group-lifecycle-api.md index 8b599532955..6549fb65f73 100644 --- a/_tuning-your-cluster/availability-and-recovery/workload-management/query-group-lifecycle-api.md +++ b/_tuning-your-cluster/availability-and-recovery/workload-management/query-group-lifecycle-api.md @@ -7,7 +7,7 @@ grand_parent: Availability and recovery --- # Query group lifecycle API -The Query Group Lifecycle API in OpenSearch provides functionality to create, update, get, and delete query groups, enabling users to organize and control sets of related queries under specific groups. +The Query Group Lifecycle API in OpenSearch provides functionality to create, update, retrieve, and delete query groups, allowing users to categorize queries into specific groups based on defined criteria. This feature provides a more organized and efficient OpenSearch environment, enhancing user experiences and resource management overall. ## Create query group Creates a new Query group with the specified properties. @@ -158,7 +158,7 @@ DELETE _wlm/query_group/analytics ``` ## Fields -The query group lifecycle API contains the following fields. +The query group schema contains the following fields. | Field | Description | |:-----------------------|:-------------------------------------------------------------------------------------------| From c34f597bf1aa29b2d2ce76e66eaba01c345cf922 Mon Sep 17 00:00:00 2001 From: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> Date: Thu, 14 Nov 2024 13:46:08 -0600 Subject: [PATCH 4/6] Make page fit API template. Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> --- .../query-group-lifecycle-api.md | 169 ++++++------------ 1 file changed, 54 insertions(+), 115 deletions(-) diff --git a/_tuning-your-cluster/availability-and-recovery/workload-management/query-group-lifecycle-api.md b/_tuning-your-cluster/availability-and-recovery/workload-management/query-group-lifecycle-api.md index 6549fb65f73..9b96a9fb83e 100644 --- a/_tuning-your-cluster/availability-and-recovery/workload-management/query-group-lifecycle-api.md +++ b/_tuning-your-cluster/availability-and-recovery/workload-management/query-group-lifecycle-api.md @@ -5,18 +5,35 @@ nav_order: 20 parent: Workload management grand_parent: Availability and recovery --- -# Query group lifecycle API +# Query Group Lifecycle API -The Query Group Lifecycle API in OpenSearch provides functionality to create, update, retrieve, and delete query groups, allowing users to categorize queries into specific groups based on defined criteria. This feature provides a more organized and efficient OpenSearch environment, enhancing user experiences and resource management overall. +The Query Group Lifecycle API in creates, updates, retrieves, and deletes query groups. The API categorizes queries into specific groups, called _query groups_ based on desired resource limits. -## Create query group -Creates a new Query group with the specified properties. +## Paths and HTTP method -#### Path and HTTP method ```json PUT _wlm/query_group +PUT _wlm/query_group/ +DELETE _wlm/query_group/ ``` -#### Example request + +## Request body fields + +| Field | Description | +| :--- | :--- | +| `_id` | The id of the query group. Optional. | +| `name` | The name of the query group. Required when creating a new query group. | +| `resiliency_mode` | The resiliency mode of the query group. Valid modes are `enforced`, `soft`, and `monitor`. For more information about resiliency modes, see [Operating modes](https://opensearch.org/docs/latest/tuning-your-cluster/availability-and-recovery/workload-management/wlm-feature-overview/#operating-modes). | +| `resource_limits` | The resource limits of the query group. Valid resources are `cpu` and `memory`. | + +When creating a query group, make sure that the sum of the resource limits for a single resource, either `cpu` or `memory`, does not exceed 1. + +## Example requests + +The following requests show how to use the Query Group Lifecycle API. + +### Creating a query group + ```json PUT _wlm/query_group { @@ -28,28 +45,9 @@ PUT _wlm/query_group } } ``` -#### Example response -```json -{ - "_id":"preXpc67RbKKeCyka72_Gw", - "name":"analytics", - "resiliency_mode":"enforced", - "resource_limits":{ - "cpu":0.4, - "memory":0.2 - }, - "updated_at":1726270184642 -} -``` -## Update query group -Updates the properties of an existing Query Group. +### Updating a query group -#### Path and HTTP method -```json -PUT _wlm/query_group/ -``` -#### Example request ```json PUT _wlm/query_group/analytics { @@ -60,110 +58,51 @@ PUT _wlm/query_group/analytics } } ``` -#### Example response -```json -{ - "_id":"preXpc67RbKKeCyka72_Gw", - "name":"analytics", - "resiliency_mode":"monitor", - "resource_limits":{ - "cpu":0.41, - "memory":0.21 - }, - "updated_at":1726270333804 -} -``` -## Get query group -Retrieves the properties of the provided Query Group. -#### Path and HTTP method -```json -GET _wlm/query_group/ -``` -#### Example request +### Getting a query group + ```json GET _wlm/query_group/analytics ``` -#### Example response -```json -{ - "query_groups": [ - { - "_id": "preXpc67RbKKeCyka72_Gw", - "name": "analytics", - "resiliency_mode": "monitor", - "resource_limits": { - "cpu": 0.41, - "memory": 0.21 - }, - "updated_at": 1726270333804 - } - ] -} -``` -## Get all query groups -Retrieves the properties of all Query groups in the cluster. -#### Path and HTTP method -```json -GET _wlm/query_group -``` -#### Example request +### Deleting a query group + ```json -GET _wlm/query_group +DELETE _wlm/query_group/analytics ``` -#### Example response + +## Example responses + +OpenSearch returns responses similar to the following. + +### Creating a query group + ```json { - "query_groups": [ - { - "_id": "preXpc67RbKKeCyka72_Gw", - "name": "analytics", - "resiliency_mode": "monitor", - "resource_limits": { - "cpu": 0.41, - "memory": 0.21 - }, - "updated_at": 1726270333804 - }, - { - "_id": "pviC2vuep2Kc84yka43_Np", - "name": "analytics_2", - "resiliency_mode": "monitor", - "resource_limits": { - "cpu": 0.15, - "memory": 0.3 - }, - "updated_at": 1726270840583 - } - ] + "_id":"preXpc67RbKKeCyka72_Gw", + "name":"analytics", + "resiliency_mode":"enforced", + "resource_limits":{ + "cpu":0.4, + "memory":0.2 + }, + "updated_at":1726270184642 } ``` -## Delete query group -Delete the provided Query group. -#### Path and HTTP method -```json -DELETE _wlm/query_group/ -``` -#### Example request -```json -DELETE _wlm/query_group/analytics -``` -#### Example response +### Updating query group + ```json { - "acknowledged":true + "_id":"preXpc67RbKKeCyka72_Gw", + "name":"analytics", + "resiliency_mode":"monitor", + "resource_limits":{ + "cpu":0.41, + "memory":0.21 + }, + "updated_at":1726270333804 } ``` -## Fields -The query group schema contains the following fields. -| Field | Description | -|:-----------------------|:-------------------------------------------------------------------------------------------| -| `_id` | The id of the query group. | -| `name` | The name of the query group. | -| `resiliency_mode` | The resiliency mode of the query group. Valid modes are `enforced`, `soft`, and `monitor`. | -| `resource_limits` | The resource limits of the query group. Valid resources are `cpu` and `memory`. | -| `updated_at` | The last updated time of the query group. | From a9dad842d139060e25096fef9687462b34b19872 Mon Sep 17 00:00:00 2001 From: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> Date: Fri, 15 Nov 2024 07:38:55 -0600 Subject: [PATCH 5/6] Test automation Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> --- .../query-group-lifecycle-api.md | 18 +++++++++++++----- 1 file changed, 13 insertions(+), 5 deletions(-) diff --git a/_tuning-your-cluster/availability-and-recovery/workload-management/query-group-lifecycle-api.md b/_tuning-your-cluster/availability-and-recovery/workload-management/query-group-lifecycle-api.md index 9b96a9fb83e..db24fcbb192 100644 --- a/_tuning-your-cluster/availability-and-recovery/workload-management/query-group-lifecycle-api.md +++ b/_tuning-your-cluster/availability-and-recovery/workload-management/query-group-lifecycle-api.md @@ -11,14 +11,22 @@ The Query Group Lifecycle API in creates, updates, retrieves, and deletes query ## Paths and HTTP method -```json -PUT _wlm/query_group -PUT _wlm/query_group/ -DELETE _wlm/query_group/ -``` + + + + ## Request body fields + + + | Field | Description | | :--- | :--- | | `_id` | The id of the query group. Optional. | From e58ea9a960eeaae0abfbe31708ceddc5ada1e491 Mon Sep 17 00:00:00 2001 From: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> Date: Fri, 15 Nov 2024 09:11:36 -0600 Subject: [PATCH 6/6] Update query-group-lifecycle-api.md Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> --- .../query-group-lifecycle-api.md | 37 +++++++++++-------- 1 file changed, 21 insertions(+), 16 deletions(-) diff --git a/_tuning-your-cluster/availability-and-recovery/workload-management/query-group-lifecycle-api.md b/_tuning-your-cluster/availability-and-recovery/workload-management/query-group-lifecycle-api.md index db24fcbb192..83d66c9eb8f 100644 --- a/_tuning-your-cluster/availability-and-recovery/workload-management/query-group-lifecycle-api.md +++ b/_tuning-your-cluster/availability-and-recovery/workload-management/query-group-lifecycle-api.md @@ -5,34 +5,29 @@ nav_order: 20 parent: Workload management grand_parent: Availability and recovery --- + # Query Group Lifecycle API The Query Group Lifecycle API in creates, updates, retrieves, and deletes query groups. The API categorizes queries into specific groups, called _query groups_ based on desired resource limits. ## Paths and HTTP method - - - - +```json +PUT _wlm/query_group +PUT _wlm/query_group/ +GET _wlm/query_group +GET _wlm/query_group/ +DELETE _wlm/query_group/ +``` ## Request body fields - - - | Field | Description | | :--- | :--- | -| `_id` | The id of the query group. Optional. | -| `name` | The name of the query group. Required when creating a new query group. | +| `_id` | The ID of the query group, which can be used to associate query requests with the group and enforce the group's resource limits. | +| `name` | The name of the query group. | | `resiliency_mode` | The resiliency mode of the query group. Valid modes are `enforced`, `soft`, and `monitor`. For more information about resiliency modes, see [Operating modes](https://opensearch.org/docs/latest/tuning-your-cluster/availability-and-recovery/workload-management/wlm-feature-overview/#operating-modes). | -| `resource_limits` | The resource limits of the query group. Valid resources are `cpu` and `memory`. | +| `resource_limits` | The resource limits for query requests in the query group. Valid resources are `cpu` and `memory`. | When creating a query group, make sure that the sum of the resource limits for a single resource, either `cpu` or `memory`, does not exceed 1. @@ -113,4 +108,14 @@ OpenSearch returns responses similar to the following. } ``` +## Response body fields + +| Field | Description | +| :--- | :--- | +| `_id` | The ID of the query group. | +| `name` | The name of the query group. Required when creating a new query group. | +| `resiliency_mode` | The resiliency mode of the query group. | +| `resource_limits` | The resource limits of the query group. | +| `updated_at` | The time at which the query group was last updated. | +