Skip to content

Commit 80aba53

Browse files
authored
[DOC] Create Dashboards quickstart (opensearch-project#2409)
Create new documentation site pages and content for foundational user documentation --------- Signed-off-by: vagimeli <[email protected]>
1 parent a6503a5 commit 80aba53

22 files changed

+314
-202
lines changed

_dashboards/discover/dql.md

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
---
2+
layout: default
3+
title: Using Dashboards Query Language
4+
parent: Exploring data with Discover
5+
nav_order: 40
6+
redirect_from:
7+
- /dashboards/dql/
8+
---
9+
10+
# Using Dashboards Query Language
11+
12+
Dashboards Query Language (DQL) is a simple text-based query language for filtering data in OpenSearch Dashboards. Similar to [Query DSL]({{site.url}}{{site.baseurl}}/opensearch/query-dsl/index), 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.
13+
14+
<img src="{{site.url}}{{site.baseurl}}/images/dashboards/dql-interface.png" alt="Search term using DQL toolbar in Dashboard" width="500">
15+
16+
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]({{site.url}}{{site.baseurl}}/opensearch/index-data).
17+
{: .note purple}
18+
19+
## Searching with terms queries
20+
21+
The most basic query specifies the search term, for example:
22+
23+
```
24+
host:www.example.com
25+
```
26+
27+
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:
28+
29+
```
30+
coordinates.lat:43.7102
31+
```
32+
33+
DQL supports leading and trailing wildcards, so you can search for any terms that match your pattern, for example:
34+
35+
```
36+
host.keyword:*.example.com/*
37+
```
38+
39+
To check whether a field exists or has any data, use a wildcard to see whether Dashboards returns any results,for example:
40+
41+
```
42+
host.keyword:*
43+
```
44+
45+
## Searching with Boolean queries
46+
47+
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:
48+
49+
```
50+
host.keyword:www.example.com and response.keyword:200
51+
```
52+
53+
You also can use multiple Boolean operators in one query, for example:
54+
55+
```
56+
geo.dest:US or response.keyword:200 and host.keyword:www.example.com
57+
```
58+
59+
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.
60+
61+
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:
62+
63+
```
64+
(geo.dest:US or response.keyword:200) and host.keyword:www.example.com
65+
```
66+
67+
## Querying dates and ranges
68+
69+
DQL supports numeric inequalities, for example, `bytes >= 15 and memory < 15`.
70+
71+
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`.
72+
73+
## Querying nested fields
74+
75+
Searching a document with [nested fields]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/nested/) requires you to specify the full path of the field to be retrieved. In the following example document, the `superheroes` field has nested objects:
76+
77+
```json
78+
{
79+
"superheroes":[
80+
{
81+
"hero-name": "Superman",
82+
"real-identity": "Clark Kent",
83+
"age": 28
84+
},
85+
{
86+
"hero-name": "Batman",
87+
"real-identity": "Bruce Wayne",
88+
"age": 26
89+
},
90+
{
91+
"hero-name": "Flash",
92+
"real-identity": "Barry Allen",
93+
"age": 28
94+
},
95+
{
96+
"hero-name": "Robin",
97+
"real-identity": "Dick Grayson",
98+
"age": 15
99+
}
100+
]
101+
}
102+
```
103+
{% include copy.html %}
104+
105+
To retrieve documents that match a specific field using DQL, specify the field, for example:
106+
107+
```
108+
superheroes: {hero-name: Superman}
109+
```
110+
{% include copy.html %}
111+
112+
To retrieve documents that match multiple fields, specify all the fields, for example:
113+
114+
```
115+
superheroes: {hero-name: Superman} and superheroes: {hero-name: Batman}
116+
```
117+
{% include copy.html %}
118+
119+
You can combine multiple Boolean and range queries to create a more refined query, for example:
120+
121+
```
122+
superheroes: {hero-name: Superman and age < 50}
123+
```
124+
{% include copy.html %}
125+
126+
## Querying doubly nested objects
127+
128+
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:
129+
130+
```json
131+
{
132+
"justice-league": [
133+
{
134+
"superheroes":[
135+
{
136+
"hero-name": "Superman",
137+
"real-identity": "Clark Kent",
138+
"age": 28
139+
},
140+
{
141+
"hero-name": "Batman",
142+
"real-identity": "Bruce Wayne",
143+
"age": 26
144+
},
145+
{
146+
"hero-name": "Flash",
147+
"real-identity": "Barry Allen",
148+
"age": 28
149+
},
150+
{
151+
"hero-name": "Robin",
152+
"real-identity": "Dick Grayson",
153+
"age": 15
154+
}
155+
]
156+
}
157+
]
158+
}
159+
```
160+
{% include copy.html %}
161+
162+
The following image shows the query result using the example notation `justice-league.superheroes: {hero-name:Superman}`.
163+
164+
<img src="{{site.url}}{{site.baseurl}}/images/dashboards/dql-query-result.png" alt="DQL query result" width="1000">

_dashboards/discover/time-filter.md

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
---
2+
layout: default
3+
title: Setting the time filter
4+
parent: Exploring data with Discover
5+
nav_order: 10
6+
---
7+
8+
# Setting the time filter
9+
10+
You can change the time range to display dashboard data over minutes, hours, days, weeks, months, or years.
11+
12+
The default time range is **Last 15 minutes**. You can change the time range at the dashboard level or under **Stack Management > Advanced Settings > Time filter defaults**.
13+
{: .note}
14+
15+
To change the time range at the dashboard level, perform the following steps:
16+
17+
1. Select the calendar icon.
18+
2. Select one of the time filter options, as shown in the following image:
19+
- **Quick select:** Choose a time based on the last or next number of seconds, minutes, hours, days, or another time unit.
20+
- **Commonly used:** Choose a common time range like **Today**, **Last 7 days**, or **Last 30 days**.
21+
- **Recently used date ranges:** Select a previously used time range.
22+
- **Refresh every:** Set an automatic refresh period.
23+
24+
<img src="{{site.url}}{{site.baseurl}}/images/dashboards/time-range.png" alt="Time range interface" width="400"/>
25+
26+
3. Choose **Show dates** to set start and end times, and then select anywhere inside the toolbar to access the time filter pop-up window, as shown in the following image.
27+
28+
<img src="{{site.url}}{{site.baseurl}}/images/dashboards/time-filter-popup.png" alt="Time filter pop-up window" width="400"/>
29+
30+
4. Select **Absolute**, **Relative**, or **Now** and specify ranges.
31+
5. Choose **Update** to apply changes, as shown in the following image.
32+
33+
<img src="{{site.url}}{{site.baseurl}}/images/dashboards/start-end-time.png" alt="Start and end times interface" width="400"/>

_dashboards/dql.md

Lines changed: 0 additions & 142 deletions
This file was deleted.

0 commit comments

Comments
 (0)