Creating visualizations using queries

The visualization editor lets you create visualizations by writing Piped Processing Language (PPL) or Prometheus Query Language (PromQL) queries. The editor automatically maps query result fields to chart axes and suggests a chart type based on the shape of your data. To open the visualization editor from a dashboard, select Create new > Add visualization.

Prerequisites

Before using the visualization editor, complete the following setup steps.

Step 1: Enable required settings

Add the following settings to your opensearch_dashboards.yml file:

workspace.enabled: true
explore.enabled: true

After updating the configuration file, restart OpenSearch Dashboards for the changes to take effect.

Step 2: Create a workspace

The visualization editor requires a workspace. To create a workspace, follow these steps:

1. Navigate to the OpenSearch Dashboards home page.
2. Select Create workspace.
3. Enter a workspace name.
4. Select the Analytics (all features) use case.
5. Select Create workspace.

For more information, see Workspaces.

Step 3: Configure a data source

The visualization editor requires a dataset associated with your workspace:

• For PPL, configure an index pattern:

  1. Inside your workspace, go to Index patterns (under Management).
  2. Select Create index pattern.
  3. Enter the index name (for example, opensearch_dashboards_sample_data_logs).
  4. Select Next step.
  5. Select a time field (for example, @timestamp).
  6. Select Create index pattern.

For more information, see Index patterns.

• For PromQL (Prometheus data source), configure a Prometheus data source connection for your workspace. For more information, see Connecting Prometheus to OpenSearch.

Step 4 (Optional): Install sample data

The examples in this documentation use the OpenSearch Dashboards sample datasets. To install the sample datasets, follow these steps:

1. On the OpenSearch Dashboards home page, select Add sample data.
2. Select Add data for the datasets you want to use (for example, Sample web logs or Sample flight data).

For more information, see Adding sample data.

Navigating the visualization editor UI

The following image shows the visualization editor interface.

• The time filter (A) selects the time range for query results.
• The Update button (B) runs or refreshes the query.
• The query editor (C) is where you write PPL queries.
• The Saved queries dropdown (D) saves and loads reusable queries.
• The configuration panel (E) contains the chart type selector, field mappings, and style settings.

Creating a visualization

To open the visualization editor, use one of the following methods:

• From the left navigation menu, select Explorer > Logs, then select the Visualization tab.
• From a dashboard, select the add panel icon, then select Add visualization.

To create a visualization, follow these steps:

1. Select a dataset from the dataset selector in the query bar (for example, opensearch_dashboards_sample_data_logs).

2. Write a PPL query in the query editor. If you selected a dataset, start the query with a pipe character (|). Otherwise, specify the source explicitly using source =. For example, the following query counts log events per hour:

   source = opensearch_dashboards_sample_data_logs | stats count() by SPAN(@timestamp, 1h)
   

   If opensearch_dashboards_sample_data_logs is already selected as the dataset, you can omit the source:

   | stats count() by SPAN(@timestamp, 1h)
   

3. Select Update or press Enter to run the query.
4. The editor automatically selects a chart type and maps fields to axes based on your query results. To change the chart type, use the Visualization type dropdown.
5. To customize the field mapping, use the Fields panel.

Using dashboard variables

You can use dashboard variables to create dynamic, interactive visualizations. Variables let you switch between filter values, metrics, time intervals, and aggregation functions without editing the query. Reference variables in your PPL or PromQL queries using $variableName or ${variableName} syntax.

For more information, see Dashboard variables.

Saving a visualization

To save a visualization, select Save (or Save and back if you opened the editor from a dashboard). Enter a name for the visualization and select Save.

If you opened the visualization editor from a dashboard, the visualization is automatically added to that dashboard after saving. If you created the visualization from Explorer > Logs, save it first, then add it to a dashboard manually.

Saving and reusing queries

To save a PPL query for reuse, select Saved queries > Save query. In the dialog, configure the following options.

Select Save changes to save the query.

To load a previously saved query, select Saved queries > Open query, then select a query from the list and select the Open query button. The saved query is loaded into the query editor.

Visualization types

The following table lists the supported visualization types and their expected data shapes.

Configuring visualizations

Shared configuration options (fields, split, axes, tooltip, legend, thresholds, and more) apply across multiple visualization types. For details, see Configuring visualizations in the visualization editor.

Related documentation

• PPL
• Dashboard variables
• Creating dashboards
• Index patterns
• Connecting Prometheus to OpenSearch