Using Dashboards Query Language

Dashboards Query Language (DQL) is a simple text-based query language for filtering data in OpenSearch Dashboards. Similar to Query DSL, DQL uses an HTTP request body. For example, to display your site visitor data for a host in the United States, you would enter geo.dest:US in the search field, as shown in the following image.

Search term using DQL toolbar in Dashboard

Before you can search data in Dashboards, you must index it. In OpenSearch, the basic unit of data is a JSON document. Within an index, OpenSearch identifies each document using a unique ID. To learn more about indexing in OpenSearch, see Index data.

Searching with terms queries

The most basic query specifies the search term, for example:

  1. host:www.example.com

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

  1. coordinates.lat:43.7102

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

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

To check whether a field exists or has any data, use a wildcard to see whether Dashboards returns any results,for example:

  1. host.keyword:*

Searching with Boolean queries

To mix and match or 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, for example:

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

You also can use multiple Boolean operators in one query, for example:

  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 one in the preceding example, response.keyword:200 and host.keyword:www.example.com is evaluated first.

To avoid confusion, use parentheses to dictate the order in which you want to evaluate operands. If you want to evaluate geo.dest:US or response.keyword:200 first, you can use an expression like the following:

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

Querying dates and ranges

DQL supports numeric inequalities, for example, bytes >= 15 and memory < 15.

You can use the same method to find a date before or after the date specified in the query. > indicates a search for a date after the specified date, and < returns dates before the specified date, for example, @timestamp > "2020-12-14T09:35:33.

Querying nested fields

Searching a document with nested fields requires you to specify the full path of the field to be retrieved. In the following example document, the superheroes field has nested objects:

  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. }

copy

To retrieve documents that match a specific field using DQL, specify the field, for example:

  1. superheroes: {hero-name: Superman}

copy

To retrieve documents that match multiple fields, specify all the fields, for example:

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

copy

You can combine multiple Boolean and range queries to create a more refined query, for example:

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

copy

Querying doubly nested objects

If a document has doubly nested objects (objects nested inside other objects), retrieve a field value by specifying the full path to the field. In the following example document, the superheroes object is nested inside the justice-league object:

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

copy

The following image shows the query result using the example notation justice-league.superheroes: {hero-name:Superman}.

DQL query result