[DOCS] Updates Discover docs (#82773) (#83462)

* [DOCS] Updates Discover docs

* Update docs/user/discover.asciidoc

Co-authored-by: Kaarina Tungseth <kaarina.tungseth@elastic.co>

* Update docs/user/discover.asciidoc

Co-authored-by: Kaarina Tungseth <kaarina.tungseth@elastic.co>

* Update docs/user/discover.asciidoc

Co-authored-by: Kaarina Tungseth <kaarina.tungseth@elastic.co>

* Update docs/user/discover.asciidoc

Co-authored-by: Kaarina Tungseth <kaarina.tungseth@elastic.co>

* Update docs/user/discover.asciidoc

Co-authored-by: Kaarina Tungseth <kaarina.tungseth@elastic.co>

* Update docs/user/discover.asciidoc

Co-authored-by: Kaarina Tungseth <kaarina.tungseth@elastic.co>

* Update docs/user/discover.asciidoc

Co-authored-by: Kaarina Tungseth <kaarina.tungseth@elastic.co>

* Update docs/user/discover.asciidoc

Co-authored-by: Kaarina Tungseth <kaarina.tungseth@elastic.co>

* Update docs/user/discover.asciidoc

Co-authored-by: Kaarina Tungseth <kaarina.tungseth@elastic.co>

* [DOCS] Incorporates review comments

* [DOCS] More changes based on edits

* [DOCS] Edits per lastest review

* [DOCS] Added redirects

Co-authored-by: Kaarina Tungseth <kaarina.tungseth@elastic.co>

Co-authored-by: Kaarina Tungseth <kaarina.tungseth@elastic.co>
This commit is contained in:
gchaps 2020-11-16 12:38:13 -08:00 committed by GitHub
parent d684acdaef
commit 38964ede3e
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
13 changed files with 191 additions and 358 deletions

View file

@ -1,66 +0,0 @@
[[document-context]]
== View a document in context
Once you've narrowed your search to a specific event,
you might want to inspect the documents that occurred
immediately before and after the event. With the Context view,
you can do just that for index patterns that contain time-based events.
To open the Context view, click the expand icon (<) in the document table, and then click
*View surrounding documents.*
The documents are sorted
by the time field specified in the index pattern and displayed using the
same set of columns as the *Discover* view from which the context was opened.
The anchor document is highlighted in blue.
[role="screenshot"]
image::images/Discover-ContextView.png[Image showing context view feature, with anchor documents highlighted in blue]
[float]
[[filter-context]]
=== Filter the context
The
filters you applied in *Discover* are carried over to the Context view. Pinned filters remain active, while normal
filters are copied in a disabled state. You can re-enable these filters to
refine your context view.
If the Context view contains a large number of documents not related to the event under
investigation, you can use filters to restrict the documents to
display.
[float]
[[change-context-size]]
=== Change the number of surrounding documents
By default, the five newest and oldest
documents are listed. To increase the number of documents that surround the anchor document,
click *Load*. Five documents are added with each click.
[float]
[[configure-context-ContextView]]
=== Configure the context view
To configure the Context view, use these settings in <<advanced-options,
Advanced Settings>>.
[horizontal]
`context:defaultSize`:: The number of documents to display by default.
`context:step`:: The default number of documents to load with each button click.
`context:tieBreakerFields`:: The field to use for tiebreaking in case of equal time field values.
The default is the
`_doc` field.
+
You can enter a comma-separated list of field
names, which is checked in sequence for suitability when a context is
displayed. The first suitable field is used as the tiebreaking
field. A field is suitable if the field exists and is sortable in the index
pattern the context is based on.
+
Although not required, it is recommended to only
use fields that have {ref}/doc-values.html[doc values] enabled to achieve
good performance and avoid unnecessary {ref}/modules-fielddata.html[field
data] usage. Common examples for suitable fields include log line numbers,
monotonically increasing counters and high-precision timestamps.

View file

@ -1,55 +0,0 @@
[[document-data]]
== View document data
When you submit a search query in *Discover*, the most recent documents that match the query
are listed in the documents table.
By default, the table includes columns for
the time field and the document `_source`, which shows all fields and values in the document.
[float]
[[sorting]]
=== Modify the document table
Use the following commands to
tailor the documents table to suit your needs.
[horizontal]
Add a field column::
Hover over the list of *Available fields* and then click *add* next to each field you want to include as a column in the table.
The first field you add replaces the `_source` column.
Change sort order:: By default, columns are sorted by the values in the field.
If a time field is configured for the current index pattern,
the documents are sorted in reverse chronological order.
+
To change the sort order, hover over the column
and click image:images/sort-icon.png[].
The first click sorts by ascending order, the second click sorts by descending order, and the third
click removes the field from the sorted fields.
Move a field column:: Hover over the column header and click the (<<) or (>>) icons.
Remove&nbsp;a&nbsp;field&nbsp;column&nbsp;:: Hover over the list of *Specified fields*
and then click *remove*.
Or, use the (x) control in the column header.
[float]
=== Drill down into field-level details
To view the document data in either table or JSON format, click the expand icon (>).
The expanded view provides these options for viewing your document:
* View the events that surround your document.
For example, you might want to see the 10 documents that occurred
immediately before and after your event.
* View the document data as a separate page. You can bookmark and
share the link for direct access to a particular document.
[role="screenshot"]
image::images/Expanded-Document.png[Image showing expanded view, with JSON and table viewing options]
[float]
=== Configure the number of documents to show
By default, the documents table includes the 500 most recent documents that
match the query. To change this number, set the `discover:sampleSize` property in <<advanced-options,
Advanced Settings>>.

View file

@ -1,155 +0,0 @@
[[field-filter]]
== Filter by field
*Discover* offers
various types of filters, so you can restrict your documents to the exact data you want.
For example, you might look at the results for a
particular period of time. Or, you might include&mdash;or exclude&mdash;
all HTTP redirects that come from a specific IP and port.
[float]
=== Add a filter
A quick way to add a filter is from the fields list.
. Click the field to filter on.
+
You'll see the number of documents that contain
the field, the top 5 values for the field, and the percentage of documents
that contain each value.
+
[role="screenshot"]
image::images/filter-field.png[Picture showing top 5 values for each field, and correspnding percentage of documents that contain each value]
. Use the image:images/PositiveFilter.jpg[Positive Filter] icon to
show only documents that contain that value,
or image:images/NegativeFilter.jpg[Negative Filter] to exclude all documents with that value.
+
If there is no data to display, you might need to set a <<set-time-filter, date time filter>>.
You can choose a time from the quick filter or choose your
own using absolute or relative times.
. Try also these filtering options:
+
* To limit the field
list to a particular data type, click *Filter by type*.
You can also filter for whether that type is
aggregatable or searchable.
+
* To filter for whether a field is present, expand the document in
the document table, hover over the field, and click the *Filter for field present* icon.
[float]
=== Filter by condition
You can filter using advanced criteria,
such as if a value is equal to or in between certain values.
. Click *Add Filter*.
. Select a field.
. Select an operation for your filter:
+
[horizontal]
`is`:: The value for the field matches the given value.
`is not`:: The value for the field does not match the given value.
`is one of`:: The field matches one of the specified values.
`is not one of`:: The value for the field does not match any of the specified values.
`is between`:: The value for the field is in the given range.
`is not between`:: The value for the field is not in the given range.
`exists`:: Any value is present for the field.
`does not exist`:: No value is present for the field.
. Choose values for your filter.
+
Values from your indices may be suggested
as selections if you are filtering against an aggregatable field.
. (Optional) Specify a label for the filter.
. Click *Save* to apply the filter to your search.
+
NOTE: If you are experiencing long-running queries as a result of the value suggestions, you can
turn off the suggestions by setting `filterEditor:suggestValues` to `false`
in <<advanced-options,
Advanced Settings>>.
[float]
[[filter-pinning]]
=== Edit, disable, and delete filters
To modify a filter, click its tag, and then select one of the following actions.
*Pin across all apps*::
Persist the filter
when you switch contexts in Kibana. For example, you can pin a filter
in *Discover* and it remains in place when you switch to *Visualize*.
A filter is based on a particular index field&mdash;if the indices being
searched do not contain the field in a pinned filter, it has no effect.
*Edit filter*::
Edit the
filter definition and label.
*Exclude results*::
Switch from a positive
filter to a negative filter, and vice versa.
*Temporarily disable*::
Disable the filter without
removing it. Click again to reenable the filter.
*Delete*::
Delete the filter.
To apply an action to all filters,
click the *Actions* icon, and then select the action.
[float]
[[filter-edit]]
=== Modify the filter query
You can directly modify
the query that filters your search results. This enables you
to create more complex filters using multiple fields.
. Click the filter tag, and then select *Edit > Edit Query DSL*.
. Edit the query for the filter.
+
////
image::images/edit_filter_query_json.png[]
+
////
For example, if you are using the sample log data, you can use the
{ref}/query-dsl-bool-query.html[bool query] to create a filter
that displays the hits that originated from Canada or China that resulted in a 404 error:
+
==========
[source,json]
{
"bool": {
"should": [
{
"term": {
"geoip.country_name.raw": "Canada"
}
},
{
"term": {
"geoip.country_name.raw": "China"
}
}
],
"must": [
{
"term": {
"response": "404"
}
}
]
}
}
==========

Binary file not shown.

After

Width:  |  Height:  |  Size: 830 B

Binary file not shown.

After

Width:  |  Height:  |  Size: 14 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 132 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 198 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 64 KiB

View file

@ -1,14 +0,0 @@
[[viewing-field-stats]]
== View field data statistics
From the fields list, you can see how many of the documents in the documents
table contain a particular field, what the top 5 values are, and what
percentage of documents contain each value.
You can visualize data in various ways. You can only apply the quick visualize
to aggregatable fields. You can visualize the keyword fields, and
they are available in the side bar if you uncheck "Hide missing fields".
To view field data statistics, click the name of a field in the fields list.
image:images/filter-field.png[Fields list that displays the top five search results]

BIN
docs/images/Discover-Start.png Normal file → Executable file

Binary file not shown.

Before

Width:  |  Height:  |  Size: 650 KiB

After

Width:  |  Height:  |  Size: 494 KiB

Before After
Before After

Binary file not shown.

Before

Width:  |  Height:  |  Size: 29 KiB

After

Width:  |  Height:  |  Size: 60 KiB

Before After
Before After

View file

@ -164,3 +164,24 @@ This content has moved. See
This content has moved. See {ref}/index-mgmt.html[Index management].
[role="exclude",id="field-filter"]
== Filter by field
This content has moved. See <<discover, **Discover**>>.
[role="exclude",id="document-context"]
== View a document in context
This content has moved. See <<discover, **Discover**>>.
[role="exclude",id="document-data"]
== View document data
This content has moved. See <<discover, **Discover**>>.
[role="exclude",id="viewing-field-stats"]
== View field data statistics
This content has moved. See <<discover, **Discover**>>.

View file

@ -3,101 +3,211 @@
[partintro]
--
**_Tell {kib} where to find your data, then search and filter it for hidden insights and relationships._**
When you know what your data includes, you can create visualizations
that best display that data and build better dashboards.
*Discover* enables you to explore your data, find
hidden insights and relationships, and get answers to your questions.
Youve added your data, and now youre ready to dig in. 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?
This tutorial shows you how to use *Discover* to quickly search large amounts of
data and understand whats going on at any given time.
With *Discover*, you can:
Youll learn to:
* Access every document in every index that matches your selected index pattern
* Search your data and filter the search results
* Get field-level details about the documents that match your search
* View the events that occurred just before and after a document
- **Select** data for your exploration, and then 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, youll be ready to start exploring with your own
data in *Discover*.
[role="screenshot"]
image::images/Discover-Start.png[Discover]
[float]
[[select-pattern]]
=== Set up your index pattern
=== Prerequisites
- If you dont 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].
The first thing to do in *Discover* is to select an <<index-patterns, index pattern>>, which
defines the data you want to explore and visualize.
If you haven't yet created an index pattern, you can add a <<add-sample-data, sample data set>>,
which has a pre-built index pattern.
[float]
=== Set a time filter
[[whats-you-goal-in-discover]]
=== Step 1. Define your goal
By default, *Discover* shows data for the last 15 minutes.
If you have a time-based index, and no data displays,
you might need to increase the time range. Using the <<set-time-filter, time filter>>,
you can specify a common or recently-used time range, a relative time
from now, or an absolute time range.
When you explore your data in **Discover**, it's common to start with one or two goals:
- **Get an overview of what is happening.**
For example, you might look for
information on the overall health and performance of your ecommerce business,
and then share your findings in a report.
- **Find an answer to a specific question.** You want
to determine your customers' shopping preferences,
and then visualize your findings on a dashboard.
For this tutorial, your goal is to better manage your product inventory. You want to
know the top-selling products and on what day of the week these products sell the most.
[float]
=== Search your data
[[find-the-data-you-want-to-use]]
=== Step 2. Find your data
Now that you have your data and set the time span, you can start asking your questions.
You can search your data using the <<kuery-query, Kibana Query language>>,
which offers a simplified query syntax.
For example, if
you search for `day_of_week : Friday`, you'll get a list of all documents
in which `day_of_week` is set to `Friday`. If you prefer
<<lucene-query, Lucene query syntax>>, you can access it from the KQL menu.
Tell {kib} where to find the data you want to explore, and then specify the time range in which to view that data.
[float]
=== Filter your search results
Next, you'll want narrow your search results to a more manageable data set.
When you click on a name in the field list, you'll see
the top five values for the field, the number of documents that contain the field,
and the percentage of documents that contain each value. From this view, you can
use the (+) magnifier icon to quickly find all
documents that have that value, or (-) to exclude all
documents with that value. For more filter options, see <<field-filter, filtering by field>>.
. Open the main menu, and select **Discover**.
. Select the data you want to work with.
+
{kib} uses an <<index-patterns,index pattern>> to tell it where to find
your {es} data.
To view the ecommerce sample data, make sure the index pattern is set to **kibana_sample_data_ecommerce**.
+
[role="screenshot"]
image::images/filter-field.png[height=317]
image::images/discover-index-pattern.png[How to set the index pattern in Discover]
. Adjust the time range to view data for the *Last 7 days*.
+
NOTE: 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 histogram.
[float]
=== Add and remove fields
[[explore-fields-in-your-data]]
=== Step 3. Explore the fields in your data
The sortable documents table
lists the documents that match your search.
By default, the table includes columns for the time field and the document `_source`.
To zero in on a specific field, click *add* next to the field name.
For example, if you add the `currency`, `customer_last_name`, and `day_of_week` fields,
the document table includes columns for those three fields.
**Discover** includes a table that shows all the documents that match your search.
By default, the table includes columns for the time field and the document `_source`,
which can be overwhelming. Youll modify this table to display only your fields of interest.
. Scan through the list of **Available fields** to see
whats in your data. You can also search for a field by name.
. Find the `manufacturer` field, and then click it to view the five most popular values for that field.
+
**Discover** fetches a maximum of 500 documents, which it uses to calculate the popular values.
+
[role="screenshot"]
image:images/filter-field.png[Fields list that displays the top five search results]
. Click image:images/add-icon.png[Add icon] to toggle the field into the document table.
. Add `day of week` so your document table looks like this:
+
[role="screenshot"]
image:images/document-table.png[Document table with fields for manufacturer, geo.country_iso_code, and day_of_week]
. To rearrange the table columns, hover the mouse over a
column header, and then use the move and sort controls.
[float]
=== Examine document contents
[[search-in-discover]]
=== Step 4. Search your data
From the documents table, you can expand a document to
examine its field data in either table or JSON format.
The table view provides yet another filtering option&mdash;filtering for whether the field
is present. See <<document-data, Viewing document data>> for details.
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 **Search** field. 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 *equals some value* and *US*, and then click *Update*.
. For a more complex search, try:
+
`geoip.country_iso_code : US and products.taxless_price >= 75`
[float]
=== View a document in context
[[filter-in-discover]]
=== Step 5. Filter your data
Suppose you're troubleshooting your data, and you've narrowed down your results to a single document.
Now you want to to see the events that occurred just before and after the
document that you are looking at. You can do that by expanding the document and
clicking <<document-context, View surrounding documents>>.
Whereas the query defines the set of documents you are interested in,
filters enable you to zero in on different subsets of those documents.
You can filter results to include or exclude specific fields, filter for a value in a range,
and more. The **Add filter** popup prompts you with the fields you can filter
and the operators you can use.
Exclude documents where day of week is not Wednesday:
. Click **Add filter**.
. Set **Field** to *day_of_week*, **Operator** to *is not*, and **Value** to *Wednesday*.
. Save the 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]
=== Save and share your search
[[look-inside-a-document]]
=== Step 6. Look inside a document
Finally, its time to save and share your data. You can export your data as a CSV file
or create a direct link to share. The *Save* and *Share* actions are in the menu bar.
Dive into an individual document to view its fields and the documents
that occurred before and after it.
. In the document table, expand any document.
+
[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 of its name for filters and other controls.
. To view documents that occurred before or after the event you are looking at, click **View surrounding documents**.
. For direct access to a particular document, click **View single document**.
+
You can bookmark this document and share the link.
[float]
[[save-your-search]]
=== Step 7. Save your search for later use
Save your search so you can repeat it later, generate a CSV report, or use it in visualizations, dashboards, and Canvas workpads.
Saving a search saves the query and the filters.
. In the toolbar, click **Save**.
. Give your search a title, and then click **Save**.
[float]
=== Step 8. Visualize your findings
If a field can be {ref}/search-aggregations.html[aggregated], you can quickly
visualize it from **Discover**.
. From the **Selected fields** list, click `day_of_week`, and then click **Visualize**.
+
{kib} creates a visualization best suited for this field.
. Drag `manufacturer.keyword` from the field list and drop it on
the visualization builder pane.
+
[role="screenshot"]
image:images/visualize-from-discover.png[Visualization that opens from Discover based on your data]
. Save your visualization for use on a dashboard.
[float]
=== Whats next?
* <<kuery-query, Learn more about the structure of a KQL query>>.
* <<kibana-discover-settings, Configure Discover>> to better meet your needs.
In **Advanced Settings**, you can configure the number of documents to show,
the table columns that display by default, and more.
* <<dashboard,Create a dashboard>> with even more visualizations of your findings, such as treemaps, metrics, and tables.
* <<reporting-getting-started, Present your findings in a report>>.
--
@ -106,11 +216,3 @@ include::{kib-repo-dir}/management/index-patterns.asciidoc[]
include::{kib-repo-dir}/discover/set-time-filter.asciidoc[]
include::{kib-repo-dir}/discover/search.asciidoc[]
include::{kib-repo-dir}/discover/field-filter.asciidoc[]
include::{kib-repo-dir}/discover/document-data.asciidoc[]
include::{kib-repo-dir}/discover/context.asciidoc[]
include::{kib-repo-dir}/discover/viewing-field-stats.asciidoc[]