Add documentation page for Vega Visualizations

_dashboards/management/multi-data-sources.md

@@ -3,7 +3,7 @@ layout: default
 title: Configuring and using multiple data sources
 parent: Data sources
 nav_order: 10
-redirect_from: 
+redirect_from:
   - /dashboards/discover/multi-data-sources/
 ---
 
@@ -16,7 +16,7 @@ You can ingest, process, and analyze data from multiple data sources in OpenSear
 
 ## Getting started
 
-The following tutorial guides you through configuring and using multiple data sources. 
+The following tutorial guides you through configuring and using multiple data sources.
 
 ### Step 1: Modify the YAML file settings
 
@@ -36,16 +36,16 @@ A data source connection specifies the parameters needed to connect to a data so
 To create a new data source connection:
 
 1. From the OpenSearch Dashboards main menu, select **Dashboards Management** > **Data sources** > **Create data source connection**.
-2. Add the required information to each field to configure **Connection Details** and **Authentication Method**. 
-   
+2. Add the required information to each field to configure the **Connection Details** and **Authentication Method**.
+
     - Under **Connection Details**, enter a title and endpoint URL. For this tutorial, use the URL `http://localhost:5601/app/management/opensearch-dashboards/dataSources`. Entering a description is optional.
 
     - Under **Authentication Method**, select an authentication method from the dropdown list. Once an authentication method is selected, the applicable fields for that method appear. You can then enter the required details. The authentication method options are:
       - **No authentication**: No authentication is used to connect to the data source.
       - **Username & Password**: A basic username and password are used to connect to the data source.
       - **AWS SigV4**: An AWS Signature Version 4 authenticating request is used to connect to the data source. AWS Signature Version 4 requires an access key and a secret key.
-            - For AWS Signature Version 4 authentication, first specify the **Region**. Next, select the OpenSearch service in the **Service Name** list. The options are **Amazon OpenSearch Service** and **Amazon OpenSearch Serverless**. Last, enter the **Access Key** and **Secret Key** for authorization. 
-      
+            - For AWS Signature Version 4 authentication, first specify the **Region**. Next, select the OpenSearch service from the **Service Name** list. The options are **Amazon OpenSearch Service** and **Amazon OpenSearch Serverless**. Last, enter the **Access Key** and **Secret Key** for authorization.
+
       For information about available AWS Regions for AWS accounts, see [Available Regions](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html#concepts-available-regions). For more information about AWS Signature Version 4 authentication requests, see [Authenticating Requests (AWS Signature Version 4)](https://docs.aws.amazon.com/AmazonS3/latest/API/sig-v4-authenticating-requests.html).
       {: .note}
 
@@ -71,15 +71,15 @@ An example data source connection screen is shown in the following image.
 
 ### Selecting multiple data sources through the Dev Tools console
 
-Alternatively, you can select multiple data sources through the [Dev Tools]({{site.url}}{{site.baseurl}}/dashboards/dev-tools/index-dev/) console. This option provides for working with a broader range of data and gaining deeper insight into your code and applications. 
+Alternatively, you can select multiple data sources through the [Dev Tools]({{site.url}}{{site.baseurl}}/dashboards/dev-tools/index-dev/) console. This option allows you to work with a broader range of data and gaining a deeper understanding of your code and applications.
 
 Watch the following 10-second video to see it in action.
 
 <img src="{{site.url}}{{site.baseurl}}/images/dashboards/multidata-dev-tools.gif" alt="Multiple data sources in Dev Tools demo">{: .img-fluid}
 
 To select a data source through the Dev Tools console, follow these steps:
 
-1. Locate your copy of `opensearch_dashboards.yml` and open it in the editor of your choice. 
+1. Locate your copy of `opensearch_dashboards.yml` and open it in the editor of your choice.
 2. Set `data_source.enabled` to `true`.
 3. Connect to OpenSearch Dashboards and select **Dev Tools** in the menu.
 4. Enter the following query in the editor pane of the **Console** and then select the play button:
@@ -100,13 +100,13 @@ To upload saved objects from connected data sources to a dashboard with multiple
 
 Follow these steps to import saved objects from a connected data source:
 
-1. Locate your `opensearch_dashboards.yml` file and open it in your preferred text editor. 
+1. Locate your `opensearch_dashboards.yml` file and open it in your preferred text editor.
 2. Set `data_source.enabled` to `true`.
 3. Connect to OpenSearch Dashboards and go to **Dashboards Management** > **Saved objects**.
 4. Select **Import** > **Select file** and upload the file acquired from the connected data source.
 5. Choose the appropriate **Data source** from the dropdown menu, set your **Conflict management** option, and then select the **Import** button.
 
-## Next steps 
+## Next steps
 
 Once you've configured your multiple data sources, you can start exploring that data. See the following resources to learn more:
 
@@ -120,5 +120,5 @@ Once you've configured your multiple data sources, you can start exploring that
 This feature has some limitations:
 
 * The multiple data sources feature is supported for index-pattern-based visualizations only.
-* The visualization types Time Series Visual Builder (TSVB), Vega and Vega-Lite, and timeline are not supported.
+* The Time Series Visual Builder (TSVB) and timeline visualization types are not supported.
 * External plugins, such as Gantt chart, and non-visualization plugins, such as the developer console, are not supported.

_dashboards/visualize/vega.md

@@ -0,0 +1,192 @@
+---
+layout: default
+title: Using Vega
+parent: Building data visualizations
+nav_order: 45
+---
+
+# Using Vega
+
+[Vega](https://vega.github.io/vega/) and [Vega-Lite](https://vega.github.io/vega-lite/) are open-source, declarative language visualization tools that you can use to create custom data visualizations with your OpenSearch data and [Vega Data](https://vega.github.io/vega/docs/data/). These tools are ideal for advanced users comfortable with writing OpenSearch queries directly. Enable the `vis_type_vega` plugin in your `opensearch_dashboards.yml` file to write your [Vega specifications](https://vega.github.io/vega/docs/specification/) in either JSON or [HJSON](https://hjson.github.io/) format or to specify one or more OpenSearch queries within your Vega specification. By default, the plugin is set to `true`. The configuration is shown in the following example. For configuration details, refer to the `vis_type_vega` [README](https://github.com/opensearch-project/OpenSearch-Dashboards/blob/main/src/plugins/vis_type_vega/README.md).
+
+```
+vis_type_vega.enabled: true
+```
+
+The following image shows a custom Vega map created in OpenSearch.
+
+<img src="{{site.url}}{{site.baseurl}}/images/dashboards/vega-2.png" alt="Map created using Vega visualization in OpenSearch Dashboards">
+
+## Querying from multiple data sources
+
+If 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. Within your Vega specification, add the `data_source_name` field under the `url` property to target a specific data source by name. By default, queries use data from the local cluster. You can assign individual `data_source_name` values to each OpenSearch query within your Vega specification. This allows you to query multiple indexes across different data sources in a single visualization.
+
+The following is an example Vega specification with `Demo US Cluster` as the specified `data_source_name`:
+
+```
+{
+  $schema: https://vega.github.io/schema/vega/v5.json
+  config: {
+    kibana: {type: "map", latitude: 25, longitude: -70, zoom: 3}
+  }
+  data: [
+    {
+      name: table
+      url: {
+        index: opensearch_dashboards_sample_data_flights
+        // This OpenSearchQuery will query from the Demo US Cluster datasource
+        data_source_name: Demo US Cluster
+        %context%: true
+        // Uncomment to enable time filtering
+        // %timefield%: timestamp
+        body: {
+          size: 0
+          aggs: {
+            origins: {
+              terms: {field: "OriginAirportID", size: 10000}
+              aggs: {
+                originLocation: {
+                  top_hits: {
+                    size: 1
+                    _source: {
+                      includes: ["OriginLocation", "Origin"]
+                    }
+                  }
+                }
+                distinations: {
+                  terms: {field: "DestAirportID", size: 10000}
+                  aggs: {
+                    destLocation: {
+                      top_hits: {
+                        size: 1
+                        _source: {
+                          includes: ["DestLocation"]
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+      format: {property: "aggregations.origins.buckets"}
+      transform: [
+        {
+          type: geopoint
+          projection: projection
+          fields: [
+            originLocation.hits.hits[0]._source.OriginLocation.lon
+            originLocation.hits.hits[0]._source.OriginLocation.lat
+          ]
+        }
+      ]
+    }
+    {
+      name: selectedDatum
+      on: [
+        {trigger: "!selected", remove: true}
+        {trigger: "selected", insert: "selected"}
+      ]
+    }
+  ]
+  signals: [
+    {
+      name: selected
+      value: null
+      on: [
+        {events: "@airport:mouseover", update: "datum"}
+        {events: "@airport:mouseout", update: "null"}
+      ]
+    }
+  ]
+  scales: [
+    {
+      name: airportSize
+      type: linear
+      domain: {data: "table", field: "doc_count"}
+      range: [
+        {signal: "zoom*zoom*0.2+1"}
+        {signal: "zoom*zoom*10+1"}
+      ]
+    }
+  ]
+  marks: [
+    {
+      type: group
+      from: {
+        facet: {
+          name: facetedDatum
+          data: selectedDatum
+          field: distinations.buckets
+        }
+      }
+      data: [
+        {
+          name: facetDatumElems
+          source: facetedDatum
+          transform: [
+            {
+              type: geopoint
+              projection: projection
+              fields: [
+                destLocation.hits.hits[0]._source.DestLocation.lon
+                destLocation.hits.hits[0]._source.DestLocation.lat
+              ]
+            }
+            {type: "formula", expr: "{x:parent.x, y:parent.y}", as: "source"}
+            {type: "formula", expr: "{x:datum.x, y:datum.y}", as: "target"}
+            {type: "linkpath", shape: "diagonal"}
+          ]
+        }
+      ]
+      scales: [
+        {
+          name: lineThickness
+          type: log
+          clamp: true
+          range: [1, 8]
+        }
+        {
+          name: lineOpacity
+          type: log
+          clamp: true
+          range: [0.2, 0.8]
+        }
+      ]
+      marks: [
+        {
+          from: {data: "facetDatumElems"}
+          type: path
+          interactive: false
+          encode: {
+            update: {
+              path: {field: "path"}
+              stroke: {value: "black"}
+              strokeWidth: {scale: "lineThickness", field: "doc_count"}
+              strokeOpacity: {scale: "lineOpacity", field: "doc_count"}
+            }
+          }
+        }
+      ]
+    }
+    {
+      name: airport
+      type: symbol
+      from: {data: "table"}
+      encode: {
+        update: {
+          size: {scale: "airportSize", field: "doc_count"}
+          xc: {signal: "datum.x"}
+          yc: {signal: "datum.y"}
+          tooltip: {
+            signal: "{title: datum.originLocation.hits.hits[0]._source.Origin + ' (' + datum.key + ')', connnections: length(datum.distinations.buckets), flights: datum.doc_count}"
+          }
+        }
+      }
+    }
+  ]
+}
+```
+{% include copy-curl.html %}