Dashboards Query Language

Similar to the Query DSL that lets you use the HTTP request body to search for data, you can use the Dashboards Query Language (DQL) in OpenSearch Dashboards to search for data and visualizations.

For example, if you want to see all visualizations of visits to a host based in the US, enter geo.dest:US into the search field, and Dashboards refreshes to display all related data.

Just like the query DSL, DQL has a handful of query types, so use whichever best fits your use case.

This section uses the OpenSearch Dashboards sample web log data. To add sample data in Dashboards, log in to OpenSearch Dashboards, choose Home, Add sample data, and then Add data.

Terms query

The most basic query is to just specify the term you’re searching for.

  1. host:www.example.com

To access an object’s nested field, list the complete path to the field separated by periods. For example, to retrieve the lat field in the coordinates object:

  1. coordinates.lat:43.7102

DQL also supports leading and trailing wildcards, so you can search for any terms that match your pattern.

  1. host.keyword:*.example.com/*

To check if a field exists or has any data, use a wildcard to see if Dashboards returns any results.

  1. host.keyword:*

Boolean query

To mix and match, or even combine, multiple queries for more refined results, you can use the boolean operators and, or, and not. DQL is not case sensitive, so AND and and are the same.

  1. host.keyword:www.example.com and response.keyword:200

The following example demonstrates how to use multiple operators in one query.

  1. geo.dest:US or response.keyword:200 and host.keyword:www.example.com

Remember that boolean operators follow the logical precedence order of not, and, and or, so if you have an expression like the previous example, response.keyword:200 and host.keyword:www.example.com gets evaluated first, and then Dashboards uses that result to compare with geo.dest:US.

To avoid confusion, we recommend using parentheses to dictate the order you want to evaluate in. If you want to evaluate geo.dest:US or response.keyword:200 first, your expression becomes:

  1. (geo.dest:US or response.keyword:200) and host.keyword:www.example.com

Date and range queries

DQL also supports inequalities if you’re using numeric inequalities.

  1. bytes >= 15 and memory < 15

Similarly, you can use the same method to find a date before or after your query. > indicates a search for a date after your specified date, and < returns dates before.

  1. @timestamp > "2020-12-14T09:35:33"

Nested field query

If you have a document with nested fields, you have to specify which parts of the document you want to retrieve.

Suppose that you have the following document:

  1. {
  2.   "superheroes":[
  3.     {
  4.       "hero-name": "Superman",
  5.       "real-identity": "Clark Kent",
  6.       "age": 28
  7.     },
  8.     {
  9.       "hero-name": "Batman",
  10.       "real-identity": "Bruce Wayne",
  11.       "age": 26
  12.     },
  13.     {
  14.       "hero-name": "Flash",
  15.       "real-identity": "Barry Allen",
  16.       "age": 28
  17.     },
  18.     {
  19.       "hero-name": "Robin",
  20.       "real-identity": "Dick Grayson",
  21.       "age": 15
  22.     }
  23.   ]
  24. }

The following example demonstrates how to use DQL to retrieve a specific field.

  1. superheroes: {hero-name: Superman}

If you want to retrieve multiple objects from your document, just specify all of the fields you want to retrieve.

  1. superheroes: {hero-name: Superman} and superheroes: {hero-name: Batman}

The previous boolean and range queries still work, so you can submit a more refined query.

  1. superheroes: {hero-name: Superman and age < 50}

If your document has an object nested within another object, you can still retrieve data by specifying all of the levels.

  1. justice-league.superheroes: {hero-name:Superman}