Merge branch 'main' into metrics-logs

_api-reference/cat/index.md

@@ -24,17 +24,54 @@ GET _cat
 ```
 {% include copy-curl.html %}
 
+The response is an ASCII cat (`=^.^=`) and a list of operations:
+
+```
+=^.^=
+/_cat/allocation
+/_cat/segment_replication
+/_cat/segment_replication/{index}
+/_cat/shards
+/_cat/shards/{index}
+/_cat/cluster_manager
+/_cat/nodes
+/_cat/tasks
+/_cat/indices
+/_cat/indices/{index}
+/_cat/segments
+/_cat/segments/{index}
+/_cat/count
+/_cat/count/{index}
+/_cat/recovery
+/_cat/recovery/{index}
+/_cat/health
+/_cat/pending_tasks
+/_cat/aliases
+/_cat/aliases/{alias}
+/_cat/thread_pool
+/_cat/thread_pool/{thread_pools}
+/_cat/plugins
+/_cat/fielddata
+/_cat/fielddata/{fields}
+/_cat/nodeattrs
+/_cat/repositories
+/_cat/snapshots/{repository}
+/_cat/templates
+/_cat/pit_segments
+/_cat/pit_segments/{pit_id}
+```
+
 ## Optional query parameters
 
-You can use the following query parameters with any CAT API to filter your results.
+The root `_cat` API does not take any parameters, but individual APIs, such as `/_cat/nodes` accept the following query parameters.
 
 Parameter | Description
 :--- | :--- |
 `v` |  Provides verbose output 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` |  Returns the result in JSON, YAML, or CBOR formats.
-`sort` | Sorts the output by the specified columns.
+`format` |  The format in which to return the result. Valid values are `json`, `yaml`, `cbor`, and `smile`.
+`s` | Sorts the output by the specified columns.
 
 ### Query parameter usage examples
 
@@ -59,7 +96,6 @@ sample-alias1 sample-index-1 - - - -
 Without the verbose parameter, `v`, the response simply returns the alias names:
 
 ```
-
 .kibana .kibana_1 - - - -
 sample-alias1 sample-index-1 - - - -
 ```
@@ -72,6 +108,24 @@ To see all the available headers, use the `help` parameter:
 GET _cat/<operation_name>?help
 ```
 
+For example, to see the available headers for the CAT aliases operation, send the following request:
+
+```json
+GET _cat/aliases?help
+```
+{% include copy-curl.html %}
+
+The response contains the available headers:
+
+```
+alias          | a                | alias name
+index          | i,idx            | index alias points to
+filter         | f,fi             | filter
+routing.index  | ri,routingIndex  | index routing
+routing.search | rs,routingSearch | search routing
+is_write_index | w,isWriteIndex   | write index
+```
+
 ### Get a subset of headers
 
 To limit the output to a subset of headers, use the `h` parameter:
@@ -80,7 +134,71 @@ 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
 ```
 
+For example, to limit aliases to only the alias name and index, send the following request:
+
+```json
+GET _cat/aliases?h=alias,index
+```
+{% include copy-curl.html %}
+
+The response contains the requested information:
+
+```
+.kibana .kibana_1
+sample-alias1 sample-index-1
+```
+
 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.
 
+### Sort by a header
+
+To sort the output by a header, use the `s` parameter:
+
+```json
+GET _cat/<operation_name>?s=<header_name_1>,<header_name_2>
+```
+
+For example, to sort aliases by alias and then index, send the following request:
+
+```json
+GET _cat/aliases?s=i,a
+```
+{% include copy-curl.html %}
+
+The response contains the requested information:
+
+```
+sample-alias2 sample-index-1
+sample-alias1 sample-index-2
+```
+
+### Retrieve data in JSON format
+
+By default, CAT APIs return data in `text/plain` format.
+
+To retrieve data in JSON format, use the `format=json` parameter:
+
+```json
+GET _cat/<operation_name>?format=json
+```
+
+For example, to retrieve aliases in JSON format, send the following request:
+
+```json
+GET _cat/aliases?format=json
+```
+{% include copy-curl.html %}
+
+The response contains data in JSON format:
+
+```json
+[
+  {"alias":".kibana","index":".kibana_1","filter":"-","routing.index":"-","routing.search":"-","is_write_index":"-"},
+  {"alias":"sample-alias-1","index":"sample-index-1","filter":"-","routing.index":"-","routing.search":"-","is_write_index":"-"}
+]
+```
+
+Other supported formats are [YAML](https://yaml.org/), [CBOR](https://cbor.io/), and [Smile](https://github.com/FasterXML/smile-format-specification).
+
 If you use the Security plugin, make sure you have the appropriate permissions.
 {: .note }

_api-reference/common-parameters.md

@@ -90,3 +90,37 @@ The following request specifies filters to limit the fields returned in the resp
 
 GET _search?filter_path=<field_name>.*,-<field_name>
 ```
+
+## Units
+
+OpenSearch APIs support the following units.
+
+### Time units
+
+The following table lists all supported time units.
+
+Units | Specify as
+:--- | :---
+Days | `d`
+Hours | `h`
+Minutes | `m`
+Seconds | `s`
+Milliseconds | `ms`
+Microseconds | `micros`
+Nanoseconds | `nanos`
+
+### Distance units
+
+The following table lists all supported distance units.
+
+Units | Specify as
+:--- | :---
+Miles | `mi` or `miles`
+Yards | `yd` or `yards`
+Feet | `ft` or `feet`
+Inches | `in` or `inch`
+Kilometers | `km` or `kilometers`
+Meters | `m` or `meters`
+Centimeters | `cm` or `centimeters`
+Millimeters | `mm` or `millimeters`
+Nautical miles | `NM`, `nmi`, or `nauticalmiles` 

_api-reference/index-apis/refresh.md

@@ -45,7 +45,7 @@ The following table lists the available query parameters. All query parameters a
 | :--- | :--- | :--- |
 | `ignore_unavailable` | Boolean | When `false`, the request returns an error when it targets a missing or closed index. Default is `false`.
 | `allow_no_indices` | Boolean | When `false`, the Refresh Index API returns an error when a wildcard expression, index alias, or `_all` targets only closed or missing indexes, even when the request is made against open indexes. Default is `true`. |
-| `expand_wildcard` | String | The type of index that the wildcard patterns can match. If the request targets data streams, this argument determines whether the wildcard expressions match any hidden data streams. Supports comma-separated values, such as `open,hidden`. Valid values are `all`, `open`, `closed`, `hidden`, and `none`.
+| `expand_wildcards` | String | The type of index that the wildcard patterns can match. If the request targets data streams, this argument determines whether the wildcard expressions match any hidden data streams. Supports comma-separated values, such as `open,hidden`. Valid values are `all`, `open`, `closed`, `hidden`, and `none`.
 
 
 

_dashboards/visualize/area.md

@@ -1,6 +1,6 @@
 ---
 layout: default
-title: Using area charts
+title: Area charts
 parent: Building data visualizations
 nav_order: 5
 ---

_dashboards/visualize/gantt.md

@@ -1,6 +1,6 @@
 ---
 layout: default
-title: Using Gantt charts
+title: Gantt charts
 parent: Building data visualizations
 nav_order: 30
 redirect_from:
@@ -18,7 +18,7 @@ To create a Gantt chart, perform the following steps:
 1. In the visualizations menu, choose **Create visualization** and **Gantt Chart**.
 1. Choose a source for the chart (e.g. some log data).
 1. Under **Metrics**, choose **Event**. For log data, each log is an event.
-1. Select the **Start Time** and **Duration** fields from your data set. The start time is the timestamp for the beginning of an event. The duration is the amount of time to add to the start time.
+1. Select the **Start Time** and **Duration** fields from your dataset. The start time is the timestamp for the beginning of an event. The duration is the amount of time to add to the start time.
 1. Under **Results**, choose the number of events to display on the chart. Gantt charts sequence events from earliest to latest based on start time.
 1. Choose **Panel settings** to adjust axis labels, time format, and colors.
 1. Choose **Update**.

_dashboards/visualize/geojson-regionmaps.md

@@ -1,6 +1,6 @@
 ---
 layout: default
-title: Using coordinate and region maps
+title: Coordinate and region maps
 parent: Building data visualizations
 has_children: true
 nav_order: 15
@@ -12,7 +12,7 @@ redirect_from:
 
 OpenSearch has a standard set of GeoJSON files that provide a vector map with each region map. OpenSearch Dashboards also provides basic map tiles with a standard vector map to create region maps. You can configure the base map tiles using [Web Map Service (WMS)](https://www.ogc.org/standards/wms). For more information, see [Configuring WMS in OpenSearch Dashboards]({{site.url}}{{site.baseurl}}/dashboards/maptiles/). 
 
-For air gapped environments, OpenSearch Dashboards provides a self-host maps server. For more information, see [Using the self-host maps server]({{site.url}}{{site.baseurl}}/dashboards/selfhost-maps-server/)
+For air-gapped environments, OpenSearch Dashboards provides a self-host maps server. For more information, see [Using the self-host maps server]({{site.url}}{{site.baseurl}}/dashboards/selfhost-maps-server/).
 
 While you can't configure a server to support user-defined vector map layers, you can configure your own GeoJSON file and upload it for this purpose. 
 {: .note}
@@ -35,7 +35,7 @@ You can use [geojson.io](https://geojson.io/#map=2/20.0/0.0) to extract GeoJSON
 
 To create your own custom vector map, upload a JSON file that contains GEO data for your customized regional maps. The JSON file contains vector layers for visualization.
 
-1. Prepare a JSON file to upload. Make sure the file has either a .geojson or .json extension.
+1. Prepare a JSON file to upload. Make sure the file has either a `.geojson` or `.json` extension.
 1. On the top menu bar, go to **OpenSearch Dashboards > Visualize**.
 1. Select the **Create Visualization** button.
 1. Select **Region Map**.

_dashboards/visualize/maps-stats-api.md

@@ -3,7 +3,7 @@ layout: default
 title: Maps Stats API
 nav_order: 20
 grand_parent: Building data visualizations
-parent: Using coordinate and region maps 
+parent: Coordinate and region maps 
 has_children: false
 ---
 

_dashboards/visualize/maps.md

@@ -2,7 +2,7 @@
 layout: default
 title: Using maps 
 grand_parent: Building data visualizations
-parent: Using coordinate and region maps
+parent: Coordinate and region maps
 nav_order: 10
 redirect_from:
   - /dashboards/maps-plugin/

_dashboards/visualize/maptiles.md

@@ -2,7 +2,7 @@
 layout: default
 title: Configuring a Web Map Service (WMS)
 grand_parent: Building data visualizations
-parent: Using coordinate and region maps
+parent: Coordinate and region maps
 nav_order: 30
 redirect_from:
   - /dashboards/maptiles/

_dashboards/visualize/selfhost-maps-server.md

@@ -1,14 +1,14 @@
 ---
 layout: default
-title: Using the self-host maps server
+title: Using self-hosted map servers
 grand_parent: Building data visualizations
-parent: Using coordinate and region maps
+parent: Coordinate and region maps
 nav_order: 40
 redirect_from:
   - /dashboards/selfhost-maps-server/
 ---
 
-# Using the self-host maps server
+# Using self-hosted map servers
 
 The self-host maps server for OpenSearch Dashboards allows users to access the default maps service in air-gapped environments. OpenSearch-compatible map URLs include a map manifest with map tiles and vectors, the map tiles, and the map vectors.
 

_dashboards/visualize/tsvb.md

@@ -0,0 +1,70 @@
+---
+layout: default
+title: TSVB
+parent: Building data visualizations
+nav_order: 45
+---
+
+# TSVB
+
+The Time-Series Visual Builder (TSVB) is a powerful data visualization tool in OpenSearch Dashboards that allows you to create detailed time-series visualizations. One of its key features is the ability to add annotations or markers at specific time points based on index data. This feature is particularly useful for making connections between multiple indexes and building visualizations that display data over time, such as flight status, delays by type, and more. TSVB currently supports the following visualization types: Area, Line, Metric, Gauge, Markdown, and Data Table.
+
+## Creating TSVB visualizations from multiple data sources
+Introduced 2.14
+{: .label .label-purple }
+
+Before proceeding, ensure that the following configuration settings are enabled in the `config/opensearch_dasboards.yaml` file:
+
+```yaml
+data_source.enabled: true
+vis_type_timeseries.enabled: true
+```
+{% include copy-curl.html %}
+
+Once you have configured [multiple data sources]({{site.url}}{{site.baseurl}}/dashboards/management/multi-data-sources/) in OpenSearch Dashboards, you can use Vega to query those data sources. The following GIF shows the process of creating TSVB visualizations in OpenSearch Dashboards.
+
+![Process of creating TSVB visualizations in OpenSearch Dashboards]({{site.url}}{{site.baseurl}}/images/dashboards/configure-tsvb.gif)
+
+**Step 1: Set up and connect data sources**
+
+Open OpenSearch Dashboards and follow these steps:
+
+1. Select **Dashboards Management** from the main menu on the left.
+2. Select **Data sources** and then select the **Create data source** button.
+3. On the **Create data source** page, enter the connection details and endpoint URL.
+4. On the **Home** page, select **Add sample data** and then select the **Add data** button for the **Sample web logs** dataset.
+
+The following GIF shows the steps required to set up and connect a data source.
+
+![Create data source]({{site.url}}{{site.baseurl}}/images/dashboards/create-datasource.gif)
+
+**Step 2: Create the visualization**
+
+Follow these steps to create the visualization:
+
+1. From the menu on the left, select **Visualize**.
+2. On the **Visualizations** page, select **Create Visualization** and then select **TSVB** in the pop-up window.
+
+**Step 3: Specify data sources**
+
+After creating a TSVB visualization, data may appear based on your default index pattern. To change the index pattern or configure additional settings, follow these steps:
+
+1. In the **Create** window, select **Panel options**.
+2. Under **Data source**, select the OpenSearch cluster from which to pull data. In this case, choose your newly created data source.
+3. Under **Index name**, enter `opensearch_dashboards_sample_data_logs`.
+4. Under **Time field**, select `@timestamp`. This setting specifies the time range for rendering the visualization.
+
+**(Optional) Step 4: Add annotations**
+
+Annotations are markers that can be added to time-series visualizations. Follow these steps to add annotations:
+
+1. On the upper-left corner of the page, select **Time Series**.
+2. Select the **Annotations** tab and then **Add data source**.
+3. In the **Index** name field, specify the appropriate index. In this case, continue using the same index from the previous steps, that is, `opensearch_dashboards_sample_data_logs`.
+4. From **Time** field, select `@timestamp`.
+5. In the **Fields** field, enter `timestamp`.
+6. In the **Row template** field, enter `timestamp`.
+
+The visualization automatically updates to display your annotations, as shown in the following image.
+
+  <img src="{{site.url}}{{site.baseurl}}/images/dashboards/tsvb-with-annotations.png" alt="TSVB visualization with annotations" width="700"/>