kibana/docs/user/discover.asciidoc

[[discover]]
= Discover

[partintro]
--
You have questions about your data.
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?

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.

[role="screenshot"]
image::images/discover.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
<<gs-get-data-into-kibana,ecommerce sample data set>>, but you can use your own data.
- You should have an understanding of {ref}/documents-indices.html[{es} documents and indices]
and <<kibana-concepts-analysts, {kib} concepts>>.


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

. Open the main menu, and select **Discover**.

. Select the data you want to work with.
+
{kib} uses a <<data-views,{data-source}>> to tell it where to find
your {es} data.
To view the ecommerce sample data, open the {data-source} menu, and select **kibana_sample_data_ecommerce**.
+
[role="screenshot"]
image::images/discover-data-view.png[How to set the {data-source} in Discover, width=50%]
+
To create a data view for your own data,
click *Create a data view*.
For details, refer to <<data-views, Create a data view.>>

. Adjust the <<set-time-filter,time range>> 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.

. Scan through the list of **Available fields** until you find the `manufacturer` field.
You can also search for the field by name.
+
[role="screenshot"]
image:images/discover-sidebar-available-fields.png[Fields list that displays the top five search results, width=50%]

. Click the `manufacturer` field to view its five most popular values.
+
[role="screenshot"]
image:images/find-manufacturer-field.png[Fields list that displays the top five search results, width=75%]

. Click image:images/add-icon.png[Add icon] to toggle the field into the document table.

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

. To rearrange the table columns, click a
column header, and then select *Move left* or *Move right*.

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

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

. Open the data view menu, and then click *Add a field to this data view*.

. 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 fields list, 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 <<runtime-fields, Explore your data with runtime fields>>.


[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 <<kuery-query,Kibana Query language>>.
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 *Refresh*.
. 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] to the left of the query bar.
. In the *Add filter* pop-up, set *Field* to *day_of_week*, *Operator* to *is not*, and *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,
click
image:images/actions-icon.png[three dots icon next to data view dropdown] in the *Actions* column for filters and other controls.

. 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, and then click **Save**.

[float]
=== Visualize your findings
If a field can be {ref}/search-aggregations.html[aggregated], you can quickly
visualize it from **Discover**.

. From the **Available fields** list, click  `day_of_week`, and then click **Visualize**.
+
[role="screenshot"]
image:images/discover-visualize.png[Discover sidebar field popover with visualize button, width=75%]
+
{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 <<reporting-getting-started,Reporting>>.

[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}.
. <<rule-type-es-query, Configure your query>> and <<action-types, select a connector type>>.

. Click *Save*.

For more about this and other rules provided in {kib} {alert-features}, go to <<alerting-getting-started>>.


[float]
=== What’s next?

* <<kuery-query, Learn more about the structure of a KQL query>>.

* <<discover-search-for-relevance, Search for relevance>>.

* <<kibana-discover-settings, Configure Discover>> to better meet your needs.
Go to **Advanced Settings** to configure the number of documents to show,
the table columns that display by default, and more.

--
include::{kib-repo-dir}/discover/document-explorer.asciidoc[]

include::{kib-repo-dir}/discover/search-for-relevance.asciidoc[]

include::{kib-repo-dir}/discover/save-search.asciidoc[]

include::{kib-repo-dir}/discover/search-sessions.asciidoc[]

include::{kib-repo-dir}/discover/field-statistics.asciidoc[]