SubList function documentation (#9718)

* SubList function documentation

*  Sublist function documentation

Signed-off-by: Sai charan raj Gudala <s.charancherry22@gmail.com>

* Add writer edits. Break up examples. Use function in pipeline.

Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com>

* Apply suggestions from code review

Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com>

* Update _data-prepper/pipelines/sublist.md

Signed-off-by: Nathan Bower <nbower@amazon.com>

---------

Signed-off-by: Sai charan raj Gudala <s.charancherry22@gmail.com>
Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com>
Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com>
Signed-off-by: Nathan Bower <nbower@amazon.com>
Co-authored-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com>
Co-authored-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com>
Co-authored-by: Nathan Bower <nbower@amazon.com>
(cherry picked from commit a2dd9ba)
Signed-off-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

Author: 4 people

_data-prepper/pipelines/functions.md

@@ -17,4 +17,6 @@ OpenSearch Data Prepper offers a range of built-in functions that can be used wi
 - [`hasTags()`]({{site.url}}{{site.baseurl}}/data-prepper/pipelines/has-tags/)
 - [`join()`]({{site.url}}{{site.baseurl}}/data-prepper/pipelines/join/)
 - [`length()`]({{site.url}}{{site.baseurl}}/data-prepper/pipelines/length/)
+- [`subList()`]({{site.url}}{{site.baseurl}}/data-prepper/pipelines/sublist/)
 - [`startsWith()`]({{site.url}}{{site.baseurl}}/data-prepper/pipelines/startswith/)
+

_data-prepper/pipelines/sublist.md

@@ -0,0 +1,79 @@
+---
+layout: default
+title: subList()
+parent: Functions
+grand_parent: Pipelines
+nav_order: 35
+---
+
+# subList(<key>, <start_index, inclusive>, <end_index, exclusive>)
+
+The `subList()` function extracts a sublist from a list field in an event. It takes the following arguments:
+
+- A JSON pointer to an event field containing a list
+- A start index (inclusive)
+- An end index (exclusive)
+
+The function returns the portion of the list between the specified start and end indexes. If the end index is `-1`, the function extracts elements from the start index to the end of the list.
+
+
+## Examples
+
+The following examples show how the `sublist()` function works.
+
+### add_entries processor
+
+You can use `subList()` in the `add_entries` processor, as shown in the following example.
+
+The function uses the following input to extract a sublist:
+
+```
+input: {"my_list": [ 0, 1, 2, 3, 4, 5, 6]}
+```
+
+Then, the following configuration uses the `add_entries` processor to extract a sublist from `my_list`, starting at index `1` and ending before index `4`: 
+
+```yaml
+add_entries:
+  entries:
+    - key: "my_list"
+      value_expression: '/subList(/my_list, 1, 4)'
+      overwrite_if_key_exists: true
+```
+{% include copy.html %}
+
+The following output shows the resulting list after extracting elements from index `1` to `3` and overwriting the original list:
+
+```
+output: my_list: [1, 2, 3]
+```
+
+### Specific ranges
+
+Each of the following examples demonstrates how the `subList()` function extracts a specific range of elements from a list.
+
+The following example extracts elements from index `0` to `2` (excluding index `3`), resulting in the first three elements of the list:
+
+```json
+{
+  "event": {
+    "/my_list": [0, 1, 2, 3, 4, 5, 6]
+  },
+  "expression": "subList(/my_list, 4, -1)",
+  "expected_output": [4, 5, 6]
+}
+```
+{% include copy.html %}
+
+The following example uses `-1` as the end index, which specifies to include all elements from index `4` to the end of the list:
+
+```json
+{
+  "event": {
+    "/my_list": [0, 1, 2, 3, 4, 5, 6]
+  },
+  "expression": "subList(/my_list, 4, -1)",
+  "expected_output": [4, 5, 6]
+}
+```
+{% include copy.html %}