diff --git a/_dashboards/discover/dql.md b/_dashboards/discover/dql.md new file mode 100644 index 00000000..7185de16 --- /dev/null +++ b/_dashboards/discover/dql.md @@ -0,0 +1,164 @@ +--- +layout: default +title: Using Dashboards Query Language +parent: Exploring data with Discover +nav_order: 40 +redirect_from: + - /dashboards/dql/ +--- + +# 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]({{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. + + + +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). +{: .note purple} + +## Searching with terms queries + +The most basic query specifies the search term, for example: + +``` +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: + +``` +coordinates.lat:43.7102 +``` + +DQL supports leading and trailing wildcards, so you can search for any terms that match your pattern, for example: + +``` +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: + +``` +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: + +``` +host.keyword:www.example.com and response.keyword:200 +``` + +You also can use multiple Boolean operators in one query, for example: + +``` +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: + +``` +(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]({{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: + +```json +{ + "superheroes":[ + { + "hero-name": "Superman", + "real-identity": "Clark Kent", + "age": 28 + }, + { + "hero-name": "Batman", + "real-identity": "Bruce Wayne", + "age": 26 + }, + { + "hero-name": "Flash", + "real-identity": "Barry Allen", + "age": 28 + }, + { + "hero-name": "Robin", + "real-identity": "Dick Grayson", + "age": 15 + } + ] +} +``` +{% include copy.html %} + +To retrieve documents that match a specific field using DQL, specify the field, for example: + +``` +superheroes: {hero-name: Superman} +``` +{% include copy.html %} + +To retrieve documents that match multiple fields, specify all the fields, for example: + +``` +superheroes: {hero-name: Superman} and superheroes: {hero-name: Batman} +``` +{% include copy.html %} + +You can combine multiple Boolean and range queries to create a more refined query, for example: + +``` +superheroes: {hero-name: Superman and age < 50} +``` +{% include copy.html %} + +## 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: + +```json +{ +"justice-league": [ +{ +"superheroes":[ +{ +"hero-name": "Superman", +"real-identity": "Clark Kent", +"age": 28 +}, +{ +"hero-name": "Batman", +"real-identity": "Bruce Wayne", +"age": 26 +}, +{ +"hero-name": "Flash", +"real-identity": "Barry Allen", +"age": 28 +}, +{ +"hero-name": "Robin", +"real-identity": "Dick Grayson", +"age": 15 +} +] +} +] +} +``` +{% include copy.html %} + +The following image shows the query result using the example notation `justice-league.superheroes: {hero-name:Superman}`. + + diff --git a/_dashboards/discover/time-filter.md b/_dashboards/discover/time-filter.md new file mode 100644 index 00000000..fe910aba --- /dev/null +++ b/_dashboards/discover/time-filter.md @@ -0,0 +1,33 @@ +--- +layout: default +title: Setting the time filter +parent: Exploring data with Discover +nav_order: 10 +--- + +# Setting the time filter + +You can change the time range to display dashboard data over minutes, hours, days, weeks, months, or years. + +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**. +{: .note} + +To change the time range at the dashboard level, perform the following steps: + +1. Select the calendar icon. +2. Select one of the time filter options, as shown in the following image: + - **Quick select:** Choose a time based on the last or next number of seconds, minutes, hours, days, or another time unit. + - **Commonly used:** Choose a common time range like **Today**, **Last 7 days**, or **Last 30 days**. + - **Recently used date ranges:** Select a previously used time range. + - **Refresh every:** Set an automatic refresh period. + + + +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. + + + +4. Select **Absolute**, **Relative**, or **Now** and specify ranges. +5. Choose **Update** to apply changes, as shown in the following image. + + diff --git a/_dashboards/dql.md b/_dashboards/dql.md deleted file mode 100644 index c0b4fcf5..00000000 --- a/_dashboards/dql.md +++ /dev/null @@ -1,142 +0,0 @@ ---- -layout: default -title: Dashboards query language -nav_order: 90 ---- - -# Dashboards Query Language - -Similar to the [Query DSL]({{site.url}}{{site.baseurl}}/opensearch/query-dsl/index) 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**. - ---- - -#### Table of contents -1. TOC -{:toc} - ---- - -## Terms query - -The most basic query is to just specify the term you're searching for. - -``` -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: - -``` -coordinates.lat:43.7102 -``` - -DQL also supports leading and trailing wildcards, so you can search for any terms that match your pattern. - -``` -host.keyword:*.example.com/* -``` - -To check if a field exists or has any data, use a wildcard to see if Dashboards returns any results. - -``` -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. - -``` -host.keyword:www.example.com and response.keyword:200 -``` - -The following example demonstrates how to use multiple operators in one query. - -``` -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: - -``` -(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. - -``` -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. - -``` -@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: - -```json -{ - "superheroes":[ - { - "hero-name": "Superman", - "real-identity": "Clark Kent", - "age": 28 - }, - { - "hero-name": "Batman", - "real-identity": "Bruce Wayne", - "age": 26 - }, - { - "hero-name": "Flash", - "real-identity": "Barry Allen", - "age": 28 - }, - { - "hero-name": "Robin", - "real-identity": "Dick Grayson", - "age": 15 - } - ] -} -``` - -The following example demonstrates how to use DQL to retrieve a specific field. - -``` -superheroes: {hero-name: Superman} -``` - -If you want to retrieve multiple objects from your document, just specify all of the fields you want to retrieve. - -``` -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. - -``` -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. - -``` -justice-league.superheroes: {hero-name:Superman} -``` diff --git a/_dashboards/get-started/quickstart-dashboards.md b/_dashboards/get-started/quickstart-dashboards.md new file mode 100644 index 00000000..5cae8b05 --- /dev/null +++ b/_dashboards/get-started/quickstart-dashboards.md @@ -0,0 +1,117 @@ +--- +layout: default +title: Quickstart guide for OpenSearch Dashboards +nav_order: 20 +has_children: false +--- + +# Quickstart guide for OpenSearch Dashboards + +This quickstart guide covers the core concepts that you need to understand to get started with OpenSearch Dashboards. You'll learn how to: + +- Add sample data. +- Explore and inspect data with **Discover**. +- Visualize data with **Dashboard**. +- Add sample data. +- Explore and inspect data with **Discover**. +- Visualize data with **Dashboard**. + +Before you get started, make sure you've installed OpenSearch and OpenSearch Dashboards. For information on installation and configuration, see [Install and configure OpenSearch]({{site.url}}{{site.baseurl}}/install-and-configure/install-opensearch/index/) and [Install and configure OpenSearch Dashboards]({{site.url}}{{site.baseurl}}/install-and-configure/install-dashboards/index/). +{: .note} + +# Adding sample data + +Sample datasets come with visualizations, dashboards, and other tools to help you explore Dashboards before you add your own data. To add sample data, perform the following steps: + +1. Verify access to OpenSearch Dashboards by connecting to [http://localhost:5601](http://localhost:5601) from a browser. The default username and password are `admin`. +1. On the OpenSearch Dashboards **Home** page, choose **Add sample data**. +2. Choose **Add data** to add the datasets, as shown in the following image. + + + +# Exploring and inspecting data + +In [**Discover**](discover/index.md), you can: + +- Choose data to explore, set a time range for that data, search it using [Dashboards Query Language (DQL)]({{site.url}}{{site.baseurl}}/dashboards/dql/), and filter the results. +- Explore the data, view individual documents, and create tables summarizing the data's contents. +- Visualize your findings. + +## Try it: Getting familiar with Discover + +1. On the OpenSearch Dashboards **Home** page, choose **Discover**. +1. Change the [time filter](time-filter.md) to **Last 7 days**, as shown in the following image. + + + +2. Search using the DQL query `FlightDelay:true AND DestCountry: US AND FlightDelayMin >= 60` and then choose **Update**. You should see results for US-bound flights delayed by 60 minutes or more, as shown in the following image. + + + +3. To filter data, choose **Add filter** and then select an **Available field**. For example, select `FlightDelayType`, **is**, and **Weather delay** from the **Field**, **Operator**, and **Value** dropdown lists, as shown in the following image. + + + +# Visualizing data + +Raw data can be difficult to comprehend and use. Data visualizations help you prepare and present data in a visual form. In **Dashboard** you can: + +- Display data in a single view. +- Build dynamic dashboards. +- Create and share reports. +- Embed analytics to differentiate your applications. + +## Try it: Getting familiar with Dashboard + +1. On the OpenSearch Dashboards **Home** page, choose **Dashboard**. +1. Choose **[Flights] Global Flight Data** in the **Dashboards** window, as shown in the following image. + + + +1. To add panels to the dashboard, choose **Edit** and then **Add** from the toolbar. +1. In the **Add panels** window, choose the existing panel **[Flights] Delay Buckets**. You'll see a pop-up window on the lower right confirming that you've added the panel. +1. Select `x` to close the **Add panels** window. +1. View the added panel **[Flights] Delay Buckets**, which is added as the last panel on the dashboard, as shown in the following image. + + + +## Try it: Creating a visualization panel + +Continuing with the preceding dashboard, you'll create a bar chart comparing the number of canceled flights and delayed flights to delay type and then add the panel to the dashboard: + +1. Change the default [time range]({{site.url}}{{site.baseurl}}/dashboards/get-started/time-filter/) from **24 hours** to **Last 7 days**. +1. In the toolbar, choose **Edit**, then **Create new**. +1. Select **VisBuilder** in the **New Visualizations** window. +1. In the **Data Source** dropdown list, choose `opensearch_dashboards_sample_data_flights`. +1. Drag the fields **Cancelled** and **FlightDelay** to the y-axis column. +1. Drag the field **FlightDelayType** to the x-axis column. +1. Choose **Save** and name the visualization in the **Title** field. +2. Choose **Save and return**. The following bar chart is added as the last panel on the dashboard, as shown in the following image. + + + +# Interacting with data + +Interactive dashboards allow you analyze data in more depth and filter it in several ways. In Dashboards, you can interact directly with data on a dashboard by using dashboard-level filters. For example, continuing with the preceding dashboard, you can filter to show delays and cancellations for a specific airline. + +## Try it: Interacting with the sample flight data + +1. On the **[Flights] Airline Carrier** panel, choose **OpenSearch-Air**. The dashboard updates automatically. +1. Choose **Save** to save the customized dashboard. + +Alternatively, you can apply filters using the dashboard toolbar: + +1. In the dashboard toolbar, choose **Add filter**. +1. From the **Field**, **Operator**, and **Value** dropdown lists, choose **Carrier**, **is**, and **OpenSearch-Air**, respectively, as shown in the following image. + + + +1. Choose **Save**. The dashboard updates automatically, and the result is the dashboard shown in the following image. + + + +# Next steps + +- **Visualize data**. To learn more about data visualizations in OpenSearch Dashboards, see [**Building data visualizations with Visualize**]({{site.url}}{{site.baseurl}}/dashboards/visualize/viz-index/). +- **Create dashboards**. To learn more about creating dashboards in OpenSearch Dashboards, see [**Creating dashboards with Dashboard**]({{site.url}}{{site.baseurl}}/dashboards/dashboard/). +- **Explore data**. To learn more about exploring data in OpenSearch Dashboards, see [**Exploring data with Discover**]({{site.url}}{{site.baseurl}}/dashboards/discover/). \ No newline at end of file diff --git a/_dashboards/index.md b/_dashboards/index.md deleted file mode 100644 index 1c0d5a43..00000000 --- a/_dashboards/index.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -layout: default -title: Getting started with OpenSearch Dashboards -nav_order: 1 -has_children: false -has_toc: false -redirect_from: - - /docs/opensearch-dashboards/ - - /dashboards/ ---- - -{%- comment -%}The `/docs/opensearch-dashboards/` redirect is specifically to support the UI links in OpenSearch Dashboards 1.0.0.{%- endcomment -%} - -# Getting started with OpenSearch Dashboards - -OpenSearch Dashboards is an open-source, integrated visualization tool that makes it easy for users to explore their data in OpenSearch. From real-time application monitoring, threat detection, and incident management to personalized search, OpenSearch Dashboards gives you the data visualizations needed to graphically represent trends, outliers, and patterns in your data. The image below shows a sample of data visualizations in OpenSearch Dashboards. - - - -## Use cases for OpenSearch Dashboards - -In OpenSearch Dashboards, a data dashboard is a collection of charts, graphs, gauges, and other visualizations that gives you a snapshot of the data that you're interested in and that you interact with. You can track, analyze, and display real-time search, monitoring, and analysis of business and operational data for use cases like application monitoring, log analytics, observability, and website search. The image below shows data visualization use cases for OpenSearch Dashboards. - -
Visualize log and trace data with interactive log analytics. | -Detect and mitigate issues faster with anomaly detection. | -
Diagnose performance issues and reduce application downtime. | -Unlock real-time search, monitoring, and analysis of business and operational data. | -