diff --git a/docs/discover/document-explorer.asciidoc b/docs/discover/document-explorer.asciidoc index 071c9f9875028..921e0504f4596 100644 --- a/docs/discover/document-explorer.asciidoc +++ b/docs/discover/document-explorer.asciidoc @@ -1,8 +1,7 @@ [[document-explorer]] -== Explore your documents +== Customize the Discover view Fine tune your explorations by customizing *Discover* to bring out the the best view of your documents. -Adjust the chart height, modify the document table, and look inside a document. [role="screenshot"] image::images/hello-field.png[A view of the Discover app] @@ -10,34 +9,27 @@ image::images/hello-field.png[A view of the Discover app] [float] [[document-explorer-c]] -=== Hide or resize the chart +=== Hide or resize areas -Hide or resize the chart for a better fit. +* You can hide and show the chart and the fields list using the available collapse and expand button in the corresponding area. -* To turn off the display of the chart, click -image:images/chart-icon.png[icon button for opening Show/Hide chart menu, width=24px] -to open the *Chart options* menu, and then click *Hide chart*. - -* To change the chart height, drag the resize handle -image:images/resize-icon.png[two-line icon for increasing or decreasing the height of the chart, width=24px] +* Adjust the width and height of each area by dragging their border to the size you want. -The chart size is saved in your browser. - -* To reset the height, open the *Chart options* menu, and then select *Reset to default height*. +The size of each area is saved in your browser for the next time you open **Discover**. [float] [[document-explorer-customize]] === Modify the document table -Customize the appearance of the document table and its contents by resizing the columns and rows, -sorting and modifying the fields, and filtering the documents. +Customize the appearance of the document table and its contents to your liking. + +image:images/discover-customize-table.png[Options to customize the table in Discover] [float] [[document-explorer-columns]] ==== Reorder and resize the columns -* To move a single column, click its header. In the dropdown menu, -click *Move left* or *Move right*. +* To move a single column, open the column's contextual options, and select *Move left* or *Move right* in the available options. * To move multiple columns, click *Columns*. In the pop-up, drag the column names to their new order. @@ -46,17 +38,31 @@ In the pop-up, drag the column names to their new order. + Column widths are stored with a saved search. When you visualize saved searches on dashboards, the saved search appears the same as in **Discover**. +[float] +[[document-explorer-density]] +==== Customize the table density + +You can adjust the density of the table from the **Display options** located in the table toolbar. This can be particularly useful when scrolling through many results. [float] [[document-explorer-row-height]] ==== Adjust the row height To set the row height to one or more lines, or automatically -adjust the height to fit the contents, click the row height icon -image:images/row-height-icon.png[icon to open the Row height pop-up]. +adjust the height to fit the contents, open the **Display options** in the table toolbar, and adjust it as you need. + +You can define different settings for the header row and body rows. + +[float] +[[document-explorer-sample-size]] +==== Limit the sample size + +When the number of results returned by your search query (displayed at the top of the **Documents** or **Results** tab) is greater than the value of <>, the number of results displayed in the table is limited to the configured value by default. You can adjust the initial sample size for searches to any number between 10 and `discover:sampleSize` from the **Display options** located in the table toolbar. + +On the last page of the table, a message indicates that you've reached the end of the loaded search results. From that message, you can choose to load more results to continue exploring. + +image:images/discover-limit-sample-size.png[Limit sample size in Discover] -[role="screenshot"] -image::images/document-explorer-row-height.png[Row height settings for the document table, width="50%"] [float] [[document-explorer-sort-data]] @@ -70,7 +76,7 @@ column header, and then select the sort order. To sort by multiple fields: -. Click the *field sorted* option. +. Click the *Sort fields* option. + [role="screenshot"] image::images/document-explorer-sort-data.png[Pop-up in document table for sorting columns, width="50%"] @@ -106,62 +112,18 @@ Narrow your results to a subset of documents so you're comparing just the data o . Select the documents you want to compare. -. Click the *documents selected* option, and then select *Show selected documents only*. +. Click the *Selected* option, and then select *Show selected documents only*. + [role="screenshot"] -image::images/document-explorer-compare-data.png[Compare data in the document table, width="50%"] - -[float] -[[document-explorer-configure-table]] -==== Set the number of rows per page - -To change the numbers of rows you want to display on each page, use the *Rows per page* menu. The default is 100 rows per page. - -[role="screenshot"] -image::images/document-table-rows-per-page.png["Menu with options for setting the number of rows in the document table"] +image::images/document-explorer-compare-data.png[Compare data in the document table, width="40%"] +You can also compare individual field values using the <>. [float] -[[document-explorer-expand-documents]] - -=== Go inside a document - -Dive into an individual document to inspect its fields, set filters, and view -the documents that occurred before and after it. - -. Click the expand icon -image:images/expand-icon-2.png[double arrow icon to open a flyout with the document details]. -+ -You can view the document in two ways. The **Table** view displays the document fields row-by-row. -The **JSON** (JavaScript Object Notation) view allows you to look at how {es} returns the document. -+ -[role="screenshot"] -image::images/document-table-expanded.png[Expanded view of the document table] -+ -. In the *Table* view, scan through the fields and their values, or search for a field by name. - -. When you find a field of interest, -hover your mouse over the *Actions* column -to: -.. Filter the results to include or exclude specific fields or values. -.. Toggle the field in or out the document table. -.. Pin the field so it stays at the top. - -. To navigate to the next and previous documents, click the < and > arrows at the top of the view. +[[document-explorer-configure-table]] +==== Set the number of results per page -. To create a view of the document that you can bookmark and share, click **Single document**. -+ -[role="screenshot"] -image::images/discover-view-single-document.png[Discover single document view] -+ -The link is valid for the time the document is available in Elasticsearch. To create a customized view of the document, -you can create <>. +To change the numbers of results you want to display on each page, use the *Rows per page* menu. The default is 100 results per page. -. To view documents that occurred before or after the event you are looking at, click **Surrounding documents**. -+ -Documents are displayed using the same set of columns as the *Discover* view from which -the context was opened. The filters you applied are also carried over. Pinned -filters remain active, while other filters are copied in a disabled state. -+ [role="screenshot"] -image::images/discover-context.png[Image showing context view feature, with anchor documents highlighted in blue] +image::images/document-table-rows-per-page.png["Menu with options for setting the number of results in the document table"] diff --git a/docs/discover/get-started-discover.asciidoc b/docs/discover/get-started-discover.asciidoc new file mode 100644 index 0000000000000..ec44f977f4aac --- /dev/null +++ b/docs/discover/get-started-discover.asciidoc @@ -0,0 +1,356 @@ +[[discover-get-started]] +== Explore fields and data with Discover + +Learn how to use *Discover* to: + +- **Select** and **filter** your {es} data. +- **Explore** the fields and content of your data in depth. +- **Present** your findings in a visualization. + +*Prerequisites:* + +- If you don’t already have {kib}, https://www.elastic.co/cloud/elasticsearch-service/signup?baymax=docs-body&elektra=docs[start a free trial] on Elastic Cloud. +- You must have data in {es}. Examples on this page use the +<>, but you can use your own data. +- You should have an understanding of {ref}/documents-indices.html[{es} documents and indices] +and <>. + + +[float] +[[find-the-data-you-want-to-use]] +=== Load data into Discover + +Select the data you want to explore, and then specify the time range in which to view that data. + +. Find **Discover** in the navigation menu or by using the <>. + +. Select the data view that contains the data you want to explore. ++ +TIP: {kib} requires a <> to access your Elasticsearch data. A {data-source} can point to one or more indices, {ref}/data-streams.html[data streams], or {ref}/alias.html[index aliases]. When adding data to {es} using one of the many integrations available, sometimes data views are created automatically, but you can also create your own. ++ +If you're using sample data, data views are automatically created and are ready to use. ++ +[role="screenshot"] +image::images/discover-data-view.png[How to set the {data-source} in Discover, width="40%"] + +. If needed, adjust the <>, for example by setting it to the *Last 7 days*. ++ +The range selection is based on the default time field in your data view. +If you are using the sample data, this value was set when the data view was created. +If you are using your own data view, and it does not have a time field, the range selection is not available. + +**Discover** is populated with your data and you can view various areas with different information: + +* All fields detected are listed in a dedicated panel. +* A chart allows you to visualize your data. +* A table displays the results of your search. +By default, the table includes a column for the time field and a *Summary* column with an overview of each result. +You can modify the document table to display your fields of interest. + +You can later filter the data that shows in the chart and in the table by specifying a query and changing the time range. + +[float] +[[explore-fields-in-your-data]] +=== Explore the fields in your data + +**Discover** provides utilities designed to help you make sense of your data: + +. In the sidebar, check the available fields. It's very common to have hundreds of fields. Use the search at the top of that sidebar to look for specific terms in the field names. ++ +In this example, we've entered `ma` in the search field to find the `manufacturer` field. ++ +[role="screenshot"] +image:images/discover-sidebar-available-fields.png[Fields list that displays the top five search results, width=40%] ++ +TIP: You can combine multiple keywords or characters. For example, `geo dest` finds `geo.dest` and `geo.src.dest`. + +. Select a field to view its most frequent values. ++ +**Discover** shows the top 10 values and the number of records used to calculate those values. + +. Select the *Plus* icon to add fields to the results table. +You can also drag them from the list into the table. ++ +[role="screenshot"] +image::images/discover-add-icon.png[How to add a field as a column in the table, width="50%"] ++ +When you add fields to the table, the **Summary** column is replaced. ++ +[role="screenshot"] +image:images/document-table.png[Document table with fields for manufacturer, customer_first_name, and customer_last_name] + +. Arrange the view to your liking to display the fields and data you care most about using the various display options of **Discover**. For example, you can change the order and size of columns, expand the table to be in full screen or collapse the chart and the list of fields. Check <>. + +. **Save** your changes to be able to open the same view later on and explore your data further. + + +[float] +[[add-field-in-discover]] +==== Add a field to your {data-source} + +What happens if you forgot to define an important value as a separate field? Or, what if you +want to combine two fields and treat them as one? This is where {ref}/runtime.html[runtime fields] come into play. +You can add a runtime field to your {data-source} from inside of **Discover**, +and then use that field for analysis and visualizations, +the same way you do with other fields. + +. In the sidebar, select *Add a field*. + +. Select the **Type** of the new field. + +. **Name** the field. Name it in a way that corresponds to the way other fields of the data view are named. +You can set a custom label and description for the field to make it more recognizable in your data view. + +. Define the value that you want the field to show. By default, the field value is retrieved from the source data if it already contains a field with the same name. You can customize this with the following options: + +** **Set value**: Define a script that will determine the value to show for the field. For more information on adding fields and Painless scripting language examples, +refer to <>. +** **Set format**: Set your preferred format for displaying the value. Changing the format can affect the value and prevent highlighting in Discover. + +. In the advanced settings, you can adjust the field popularity to make it appear higher or lower in the fields list. By default, Discover orders popular fields from most selected to least selected. + +. **Save** your new field. + +You can now find it in the list of fields and add it to the table. + +In the following example, we're adding 2 fields: A simple "Hello world" field, and a second field that combines and transforms the `customer_first_name` and `customer_last_name` fields of the sample data into a single "customer" field: + +**Hello world field example**: + +* **Name**: `hello` +* **Type**: `Keyword` +* **Set value**: enabled +* **Script**: ++ +```ts +emit("Hello World!"); +``` + +**Customer field example**: + +* **Name**: `customer` +* **Type**: `Keyword` +* **Set value**: enabled +* **Script**: ++ +```ts +String str = doc['customer_first_name.keyword'].value; +char ch1 = str.charAt(0); +emit(doc['customer_last_name.keyword'].value + ", " + ch1); +``` + +[float] +==== Visualize aggregated fields +If a field can be {ref}/search-aggregations.html[aggregated], you can quickly +visualize it in detail by opening it in **Lens** from **Discover**. **Lens** is the default visualization editor in {kib}. + +. In the list of fields, find an aggregatable field. For example, with the sample data, you can look for `day_of_week`. ++ +[role="screenshot"] +image:images/discover-day-of-week.png[Top values for the day_of_week field, plus Visualize button, width=50%] + +. In the popup, click **Visualize**. ++ +{kib} creates a **Lens** visualization best suited for this field. + +. In **Lens**, from the *Available fields* list, drag and drop more fields to refine the visualization. In this example, we're adding the `manufacturer.keyword` field onto the workspace, which automatically adds a breakdown of the top values to the visualization. ++ +[role="screenshot"] +image:images/discover-from-visualize.png[Visualization that opens from Discover based on your data] + +. Save the visualization if you'd like to add it to a dashboard or keep it in the Visualize library for later use. + +For geo point fields (image:images/geoip-icon.png[Geo point field icon, width=20px]), +if you click **Visualize**, +your data appears in a map. + +[role="screenshot"] +image:images/discover-maps.png[Map containing documents] + + +[float] +[[compare-documents-in-discover]] +==== Compare documents + +You can use *Discover* to compare and diff the field values of multiple results or documents in the table. + +. Select the results you want to compare from the Documents or Results tab in Discover. + +. From the **Selected** menu in the table toolbar, choose **Compare selected**. The comparison view opens and shows the selected results next to each other. + +. Compare the values of each field. By default the first result selected shows as the reference for displaying differences in the other results. When the value remains the same for a given field, it's displayed in green. When the value differs, it's displayed in red. ++ +TIP: You can change the result used as reference by selecting **Pin for comparison** in the contextual menu of any other result. ++ +image:images/discover-compare-rows.png[Comparison view in Discover] + +. Optionally, customize the **Comparison settings** to your liking. You can for example choose to not highlight the differences, to show them more granularly at the line, word, or character level, or even to hide fields where the value matches for all results. + +. Exit the comparison view at any time using the **Exit comparison mode** button. + +[float] +[[copy-row-content]] +==== Copy results as text or JSON + +You can quickly copy the content currently displayed in the table for one or several results to your clipboard. + +. Select the results you want to copy. + +. Open the **Selected** menu in the table toolbar, and select **Copy selection as text** or **Copy documents as JSON**. + +The content is copied to your clipboard in the selected format. +Fields that are not currently added to the table are ignored. + +[float] +[[look-inside-a-document]] +==== Explore individual result or document details in depth + +[[document-explorer-expand-documents]] +Dive into an individual document to view its fields and the documents +that occurred before and after it. + +. In the document table, click the expand icon +image:images/expand-icon-2.png[double arrow icon to open a flyout with the document details] +to show document details. ++ +[role="screenshot"] +image:images/document-table-expanded.png[Table view with document expanded] + +. Scan through the fields and their values. You can filter the table in several ways: +** If you find a field of interest, +hover your mouse over the *Field* or *Value* columns for filters and additional options. +** Use the search above the table to filter for specific fields or values, or filter by field type using the options to the right of the search field. +** You can pin some fields by clicking the left column to keep them displayed even if you filter the table. ++ +TIP: You can restrict the fields listed in the detailed view to just the fields that you explicitly added to the **Discover** table, using the **Selected only** toggle. In ES|QL mode, you also have an option to hide fields with null values. + +. To navigate to a view of the document that you can bookmark and share, select ** View single document**. + +. To view documents that occurred before or after the event you are looking at, select +**View surrounding documents**. + + + + +[float] +[[search-in-discover]] +=== Search and filter data + +[float] +==== Default mode: Search and filter using KQL + +One of the unique capabilities of **Discover** is the ability to combine +free text search with filtering based on structured data. +To search all fields, enter a simple string in the query bar. + +[role="screenshot"] +image:images/discover-search-field.png[Search field in Discover] + +To search particular fields and +build more complex queries, use the <>. +As you type, KQL prompts you with the fields you can search and the operators +you can use to build a structured query. + +For example, search the ecommerce sample data for documents where the country matches US: + +. Enter `g`, and then select *geoip.country_iso_code*. +. Select *:* for equals, and *US* for the value, and then click the refresh button or press the Enter key. +. For a more complex search, try: ++ +```ts +geoip.country_iso_code : US and products.taxless_price >= 75 +``` + +[[filter-in-discover]] +With the query input, you can filter data using the KQL or Lucene languages. You can also use the **Add filter** function available next to the query input to build your filters one by one or define them as Query DSL. + +For example, exclude results from the ecommerce sample data view where day of week is not Wednesday: + +. Click image:images/add-icon.png[Add icon] next to the query bar. +. In the *Add filter* pop-up, set the field to *day_of_week*, the operator to *is not*, +and the value to *Wednesday*. ++ +[role="screenshot"] +image:images/discover-add-filter.png[Add filter dialog in Discover] + +. Click **Add filter**. +. Continue your exploration by adding more filters. +. To remove a filter, click the close icon (x) next to its name in the filter bar. + +[float] +==== Search and filter using ES|QL + +You can use **Discover** with the Elasticsearch Query Language, ES|QL. When using ES|QL, +you don't have to select a data view. It's your query that determines the data to explore and display in Discover. + +You can switch to the ES|QL mode of Discover from the application menu bar. + +Note that in ES|QL mode, the **Documents** tab is named **Results**. + +Learn more about how to use ES|QL queries in <>. + + + +[float] +[[save-discover-search]] +==== Save your search for later use + +Save your search so you can use it later, generate a CSV report, or use it to create visualizations, dashboards, and Canvas workpads. +Saving a search saves the query text, filters, +and current view of *Discover*, including the columns selected in +the document table, the sort order, and the {data-source}. + +. In the application menu bar, click **Save**. + +. Give your search a title and a description. + +. Optionally store <> and the time range with the search. + +. Click **Save**. + +[float] +[[share-your-findings]] +==== Share your search + +To share your search and **Discover** view with a larger audience, click *Share* in the application menu bar. +For detailed information about the sharing options, refer to <>. + + +[float] +[[alert-from-Discover]] +=== Generate alerts + +From *Discover*, you can create a rule to periodically +check when data goes above or below a certain threshold within a given time interval. + +. Ensure that your data view, +query, and filters fetch the data for which you want an alert. +. In the application menu bar, click *Alerts > Create search threshold rule*. ++ +The *Create rule* form is pre-filled with the latest query sent to {es}. +. <> and <>. + +. Click *Save*. + +For more about this and other rules provided in {alert-features}, go to <>. + + +[float] +=== What’s next? + +* <>. + +* <> to better meet your needs. + +[float] +=== Troubleshooting + +This section references common questions and issues encountered when using Discover. +Also check the following blog post: {blog-ref}troubleshooting-guide-common-issues-kibana-discover-load[Learn how to resolve common issues with Discover.] + +**Some fields show as empty while they should not be, why is that?** + +This can happen in several cases: + +* With runtime fields and regular keyword fields, when the string exceeds the value set for the {ref}/ignore-above.html[ignore_above] setting used when indexing the data into {es}. +* Due to the structure of nested fields, a leaf field added to the table as a column will not contain values in any of its cells. Instead, add the root field as a column to view a JSON representation of its values. Learn more in https://www.elastic.co/de/blog/discover-uses-fields-api-in-7-12[this blog post]. \ No newline at end of file diff --git a/docs/discover/images/discover-add-filter.png b/docs/discover/images/discover-add-filter.png index 3ce158fc4fb84..f72d4074b4b85 100644 Binary files a/docs/discover/images/discover-add-filter.png and b/docs/discover/images/discover-add-filter.png differ diff --git a/docs/discover/images/discover-compare-rows.png b/docs/discover/images/discover-compare-rows.png new file mode 100644 index 0000000000000..868a17fd7ca2d Binary files /dev/null and b/docs/discover/images/discover-compare-rows.png differ diff --git a/docs/discover/images/discover-customize-table.png b/docs/discover/images/discover-customize-table.png new file mode 100644 index 0000000000000..a0aba47f6cd15 Binary files /dev/null and b/docs/discover/images/discover-customize-table.png differ diff --git a/docs/discover/images/discover-data-view.png b/docs/discover/images/discover-data-view.png index 869fc9b928811..e6c3a9aa832d5 100644 Binary files a/docs/discover/images/discover-data-view.png and b/docs/discover/images/discover-data-view.png differ diff --git a/docs/discover/images/discover-limit-sample-size.png b/docs/discover/images/discover-limit-sample-size.png new file mode 100644 index 0000000000000..1e8628ebace55 Binary files /dev/null and b/docs/discover/images/discover-limit-sample-size.png differ diff --git a/docs/discover/images/document-explorer-compare-data.png b/docs/discover/images/document-explorer-compare-data.png index 36560dcabd13e..2a980f8977393 100644 Binary files a/docs/discover/images/document-explorer-compare-data.png and b/docs/discover/images/document-explorer-compare-data.png differ diff --git a/docs/discover/images/document-table-expanded.png b/docs/discover/images/document-table-expanded.png index a6fee908b668f..f73c7d08fe09f 100644 Binary files a/docs/discover/images/document-table-expanded.png and b/docs/discover/images/document-table-expanded.png differ diff --git a/docs/discover/images/document-table.png b/docs/discover/images/document-table.png index 8fbabe4703b24..ab9141cbb9b54 100644 Binary files a/docs/discover/images/document-table.png and b/docs/discover/images/document-table.png differ diff --git a/docs/discover/images/hello-field.png b/docs/discover/images/hello-field.png index 261cb00acfa4c..8aee22bf2a847 100644 Binary files a/docs/discover/images/hello-field.png and b/docs/discover/images/hello-field.png differ diff --git a/docs/user/discover.asciidoc b/docs/user/discover.asciidoc index 4c0cfac39b312..7cab19889f278 100644 --- a/docs/user/discover.asciidoc +++ b/docs/user/discover.asciidoc @@ -8,6 +8,7 @@ What pages on your website contain a specific word or phrase? What events were logged most recently? What processes take longer than 500 milliseconds to respond? +[[save-your-search]] With *Discover*, you can quickly search and filter your data, get information about the structure of the fields, and display your findings in a visualization. You can also customize and save your searches and place them on a dashboard. @@ -16,331 +17,10 @@ You can also customize and save your searches and place them on a dashboard. image::images/hello-field.png[A view of the Discover app] -[float] -=== Explore and query your data - -This tutorial shows you how to use *Discover* to search large amounts of -data and understand what’s going on at any given time. - -You’ll learn to: - -- **Select** data for your exploration, set a time range for that data, -search it with the {kib} Query Language, and filter the results. -- **Explore** the details of your data, view individual documents, and create tables -that summarize the contents of the data. -- **Present** your findings in a visualization. - -At the end of this tutorial, you’ll be ready to start exploring with your own -data in *Discover*. - -*Prerequisites:* - -- If you don’t already have {kib}, set it up with https://www.elastic.co/cloud/elasticsearch-service/signup?baymax=docs-body&elektra=docs[our free trial]. -- You must have data in {es}. This tutorial uses the -<>, but you can use your own data. -- You should have an understanding of {ref}/documents-indices.html[{es} documents and indices] -and <>. - - -[float] -[[find-the-data-you-want-to-use]] -=== Find your data - -Tell {kib} where to find the data you want to explore, and then specify the time range in which to view that data. - -. Go to **Discover**. - -. Select the data you want to work with. -+ -{kib} uses a <> to tell it where to find -your {es} data. -To view the ecommerce sample data, open the {data-source} menu, and then select **Kibana Sample Data Ecommerce**. -+ -[role="screenshot"] -image::images/discover-data-view.png[How to set the {data-source} in Discover, width="40%"] - -+ -To create a data view for your own data, -click *Create a data view*. -For details, refer to <> - -. Adjust the <> to view data for the *Last 7 days*. -+ -The range selection is based on the default time field in your data. -If you are using the sample data, this value was set when you added the data. -If you are using your own data, and it does not have a time field, the range selection is not available. - -. To view the count of documents for a given time in the specified range, -click and drag the mouse over the chart. - -[float] -[[explore-fields-in-your-data]] -=== Explore the fields in your data - -**Discover** includes a table -that shows all the documents that match your search. -By default, the document table includes a column for the time field and a column that lists all other fields in the document. -You’ll modify the document table to display your fields of interest. - -. In the sidebar, enter `ma` in the search field to find the `manufacturer` field. -+ -[role="screenshot"] -image:images/discover-sidebar-available-fields.png[Fields list that displays the top five search results, width=50%] -+ -NOTE: You can use wildcards in field searches. For example, `goe*dest` finds `geo.dest` and `geo.src.dest`. - -. In the *Available fields* list, click `manufacturer` to view its most popular values. -+ -**Discover** shows the top 10 values and the number of records used to calculate those values. - -. Click image:images/add-icon.png[Add icon] to toggle the field into the document table. -You can also drag the field from the *Available fields* list into the document table. -+ -[role="screenshot"] -image::images/discover-add-icon.png[How to add a field as a column in the table, width="50%"] - -. Find the `customer_first_name` and `customer_last_name` fields and add -them to the document table. Your table should look similar to this: -+ -[role="screenshot"] -image:images/document-table.png[Document table with fields for manufacturer, customer_first_name, and customer_last_name] - - -. Optionally try out these actions: -+ -* To rearrange the table columns, click a -column header, and then select *Move left* or *Move right*. -+ -* To copy the name or values in a column to the clipboard, click the column header and select the desired **Copy** option. -+ -* To view more of the document table, -click -image:images/chart-icon.png[icon button for opening Show/Hide chart menu, width=24px] -to open the *Chart options* menu, -and then select *Hide chart*. -+ -* For keyboard shortcuts on the document table, click -image:images/keyboard-shortcut-icon.png[icon button for opening list of keyboard shortcuts, width=24px]. -+ -* To set the row height to one or more lines, or automatically -adjust the height to fit the contents, click -image:images/row-height-icon.png[icon to open the Row height pop-up, width=24px]. -+ -* To toggle the table in and out of fullscreen mode, click the fullscreen icon -image:images/fullscreen-icon.png[icon to display the document table in fullscreen mode]. - - - - - - -[float] -[[add-field-in-discover]] -=== Add a field to your {data-source} - -What happens if you forgot to define an important value as a separate field? Or, what if you -want to combine two fields and treat them as one? This is where {ref}/runtime.html[runtime fields] come into play. -You can add a runtime field to your {data-source} from inside of **Discover**, -and then use that field for analysis and visualizations, -the same way you do with other fields. - -. In the sidebar, click *Add a field*. - -. In the *Create field* form, enter `hello` for the name. - -. Turn on *Set value*. - -. Define the script using the Painless scripting language. Runtime fields require an `emit()`. -+ -```ts -emit("Hello World!"); -``` - -. Click *Save*. - -. In the sidebar, search for the *hello* field, and then add it to the document table. -+ -[role="screenshot"] -image:images/hello-field.png[hello field in the document tables] - -. Create a second field named `customer` that combines customer last name and first initial. -+ -```ts -String str = doc['customer_first_name.keyword'].value; -char ch1 = str.charAt(0); -emit(doc['customer_last_name.keyword'].value + ", " + ch1); -``` -. Remove `customer_first_name` and `customer_last_name` from the document table, and then add `customer`. -+ -[role="screenshot"] -image:images/customer.png[Customer last name, first initial in the document table] -+ -For more information on adding fields and Painless scripting language examples, -refer to <>. - - -[float] -[[search-in-discover]] -=== Search your data - -One of the unique capabilities of **Discover** is the ability to combine -free text search with filtering based on structured data. -To search all fields, enter a simple string in the query bar. - -[role="screenshot"] -image:images/discover-search-field.png[Search field in Discover] - - -To search particular fields and -build more complex queries, use the <>. -As you type, KQL prompts you with the fields you can search and the operators -you can use to build a structured query. - -Search the ecommerce data for documents where the country matches US: - -. Enter `g`, and then select *geoip.country_iso_code*. -. Select *:* for equals some value and *US*, and then click the refresh button or press the Enter key. -. For a more complex search, try: -+ -```ts -geoip.country_iso_code : US and products.taxless_price >= 75 -``` - -[float] -[[filter-in-discover]] -=== Filter your data - -Whereas the query defines the set of documents you are interested in, -filters enable you to zero in on subsets of those documents. -You can filter results to include or exclude specific fields, filter for a value in a range, -and more. - -Exclude documents where day of week is not Wednesday: - -. Click image:images/add-icon.png[Add icon] next to the query bar. -. In the *Add filter* pop-up, set the field to *day_of_week*, the operator to *is not*, -and the value to *Wednesday*. -+ -[role="screenshot"] -image:images/discover-add-filter.png[Add filter dialog in Discover] - -. Click **Add filter**. -. Continue your exploration by adding more filters. -. To remove a filter, -click the close icon (x) next to its name in the filter bar. - -[float] -[[look-inside-a-document]] -=== Look inside a document - -Dive into an individual document to view its fields and the documents -that occurred before and after it. - -. In the document table, click the expand icon -image:images/expand-icon-2.png[double arrow icon to open a flyout with the document details] -to show document details. -+ -[role="screenshot"] -image:images/document-table-expanded.png[Table view with document expanded] - -. Scan through the fields and their values. If you find a field of interest, -hover your mouse over the *Actions* column for filters and other options. - -. To create a view of the document that you can bookmark and share, click **Single document**. - -. To view documents that occurred before or after the event you are looking at, click -**Surrounding documents**. - - - -[float] -[[save-your-search]] -=== Save your search for later use - -Save your search so you can use it later, generate a CSV report, or use it to create visualizations, dashboards, and Canvas workpads. -Saving a search saves the query text, filters, -and current view of *Discover*, including the columns selected in -the document table, the sort order, and the {data-source}. - -. In the toolbar, click **Save**. - -. Give your search a title. - -. Optionally store <> and the time range with the search. - -. Click **Save**. - -[float] -=== Visualize your findings -If a field can be {ref}/search-aggregations.html[aggregated], you can quickly -visualize it from **Discover**. - -. In the sidebar, find and then click `day_of_week`. -+ -[role="screenshot"] -image:images/discover-day-of-week.png[Top values for the day_of_week field, plus Visualize button, width=50%] - - -. In the popup, click **Visualize**. -+ -{kib} creates a visualization best suited for this field. - -. From the *Available fields* list, drag and drop `manufacturer.keyword` onto the workspace. -+ -[role="screenshot"] -image:images/discover-from-visualize.png[Visualization that opens from Discover based on your data] - -. Save your visualization for use on a dashboard. -+ -For geo point fields (image:images/geoip-icon.png[Geo point field icon, width=20px]), -if you click **Visualize**, -your data appears in a map. -+ -[role="screenshot"] -image:images/discover-maps.png[Map containing documents] - -[float] -[[share-your-findings]] -=== Share your findings - -To share your findings with a larger audience, click *Share* in the *Discover* toolbar. -For detailed information about the sharing options, refer to <>. - -[float] -[[alert-from-Discover]] -=== Generate alerts - -From *Discover*, you can create a rule to periodically -check when data goes above or below a certain threshold within a given time interval. - -. Ensure that your data view, -query, and filters fetch the data for which you want an alert. -. In the toolbar, click *Alerts > Create search threshold rule*. -+ -The *Create rule* form is pre-filled with the latest query sent to {es}. -. <> and <>. - -. Click *Save*. - -For more about this and other rules provided in {alert-features}, go to <>. - - -[float] -=== What’s next? - -* <>. - -* <>. - -* <> to better meet your needs. - -[float] -=== Troubleshooting - -* {blog-ref}troubleshooting-guide-common-issues-kibana-discover-load[Learn how to resolve common issues with Discover.] +-- +include::{kibana-root}/docs/discover/get-started-discover.asciidoc[] --- include::{kibana-root}/docs/discover/document-explorer.asciidoc[] include::{kibana-root}/docs/discover/search-for-relevance.asciidoc[] diff --git a/docs/user/images/hello-field.png b/docs/user/images/hello-field.png new file mode 100644 index 0000000000000..8aee22bf2a847 Binary files /dev/null and b/docs/user/images/hello-field.png differ