github-mirrors/kibana
1
0
Fork 0
mirror of https://github.com/elastic/kibana.git synced 2025-04-23 17:28:26 -04:00
Code Issues Projects Releases Packages Wiki Activity

[DOCS] Updates Discover documentation (#51837)

Browse source 
* [DOCS] Updates View in Context doc in Discover

* [DOCS] Updates Discover docs on viewing document data

* [DOCS] Adds workflow to Discover docs

* [DOCS] Updates Discover docs intro page

* [DOCS] More updates to Discover docs

* [DOCS] More updates to Discover docs

* [DOCS] Incorporates review comments in Discover docs

* [DOCS] Edits to discover intro

* [DOCS] Edits to Discover docs

* [DOCS] Incorporates edits in Discover docs
This commit is contained in:
gchaps 2019-12-17 11:48:55 -08:00 • committed by GitHub
parent e5c562b5c1
commit 099ec54c72
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
12 changed files with 289 additions and 237 deletions
Download patch file Download diff file Expand all files Collapse all files

128
docs/discover/context.asciidoc
View file

@ -1,90 +1,66 @@
[[document-context]]
== Viewing Document Context
== Viewing a document in context
For certain applications it can be useful to inspect a window of documents
surrounding a specific event. The context view enables you to do just that for
<<index-patterns, index patterns>> that are configured to contain time-based events.
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 show the context surrounding an anchor document, click the *Expand* button
image:images/ExpandButton.jpg[Expand Button] to the left of the document's
table entry and then click the *View surrounding documents* link.
To open the Context view, click the expand icon (<) in the document table, and then click
*View surrounding documents.*
image::images/Expanded-Document.png[Expanded Document]
{nbsp}
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.
The context view displays a number of documents before and after the anchor
document. The anchor document itself is highlighted in blue. The view is sorted
by the time field specified in the index pattern configuration and uses the
same set of columns as the Discover view the context was opened from. If there
are multiple documents with the same time field value, the internal document
order is used as a secondary sorting criterion by default.
[NOTE]
--
The field used for tiebreaking in case of equal time field values can be
configured using the advanced setting `context:tieBreakerFields` in
<<advanced-options, *Management > Advanced Settings*>>, which defaults to the
`_doc` field. The value of this setting can be a comma-separated list of field
names, which will be checked in sequence for suitability when a context is
about to be displayed. The first suitable field is then 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.
While not required, it is recommended to only
use fields which 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.
--
[role="screenshot"]
image::images/Discover-ContextView.png[Context View]
NOTE: The number of documents displayed by default can be configured
via the `context:defaultSize` setting in <<advanced-options, *Management >
Advanced Settings*>>.
[float]
[[change-context-size]]
=== Changing the Context Size
You can change the number documents displayed before and after the anchor
document independently.
To increase the number of displayed documents that are newer than the anchor
document, click the *Load 5 more* button above the document list or enter the
desired number into the input box right of the button.
image::images/Discover-ContextView-SizePicker-Newer.png[]
{nbsp}
To increase the number of displayed documents that are older than the anchor
document, click the *Load 5 more* button below the document list or enter the
desired number into the input box right of the button.
image::images/Discover-ContextView-SizePicker-Older.png[]
{nbsp}
NOTE: The default number of documents loaded with each button click can be
configured via the `context:step` setting in <<advanced-options, *Management >
Advanced Settings*>>.
[float]
[[filter-context]]
=== Filtering the Context
=== Filter the context
Depending on how the documents are partitioned into index patterns, the context
view might contain a large number of documents not related to the event under
investigation. In order to adapt the focus of the context view to the task at
hand, you can use filters to restrict the documents considered by Kibana for
display in the context view.
When switching from the discover view to the context view, the previously
applied filters are carried over. Pinned filters remain active while normal
filters are copied in a disabled state. You can selectively re-enabled them to
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.
New filters can be added via the *Add a filter* link in the filter bar, by
clicking the filter icons appearing when hovering a field, or by expanding
documents and clicking the filter icons in the table.
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.
image::images/Discover-ContextView-FilterMontage.png[]
[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.

96
docs/discover/document-data.asciidoc
View file

@ -1,69 +1,55 @@
[[document-data]]
== Viewing Document Data
== Viewing document data
When you submit a search query, the 500 most recent documents that match the query
are listed in the Documents table. You can configure the number of documents shown
in the table by setting the `discover:sampleSize` property in <<advanced-options,
Advanced Settings>>. By default, the table shows the localized version of the time
field configured for the selected <<index-patterns, index pattern>> and the document `_source`. You can
<<adding-columns, add fields to the Documents table>> from the Fields list.
You can <<sorting, sort the listed documents>> by any indexed field that's included
in the table.
To view a document's field data, click the *Expand* button
image:images/ExpandButton.jpg[Expand Button] to the left of the document's table
entry.
image::images/Expanded-Document.png[]
To view the original JSON document (pretty-printed), click the *JSON* tab.
To view the document data as a separate page, click the *View single document*
link. You can bookmark and share this link to provide direct access to a
particular document.
To display or hide a field's column in the Documents table, click the
image:images/add-column-button.png[Add Column] *Toggle column in table* button.
To collapse the document details, click the *Collapse* button
image:images/CollapseButton.jpg[Collapse Button].
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]]
=== Sorting the Document List
You can sort the documents in the Documents table by the values in any indexed
field. If a time field is configured for the current index pattern, the
documents are sorted in reverse chronological order by default.
=== Modify the document table
To change the sort order, hover over the name of the field you want to sort by
and click the sort button. Click again to reverse the sort order.
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 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 move left (<<) or move right icon (>>).
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]
[[adding-columns]]
=== Adding Field Columns to the Documents Table
By default, the Documents table shows the localized version of the time field
that's configured for the selected index pattern and the document `_source`.
You can add fields to the table from the Fields list or from a document's
field data.
=== 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:
To add a field column from the Fields list, hover over the field and click its
*add* button.
* 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.
To add a field column from a document's field data, expand the document
and click the field's
image:images/add-column-button.png[Add Column] *Toggle column in table* button.
* View the document data as a separate page. You can bookmark and
share the link for direct access to a particular document.
Added field columns replace the `_source` column in the Documents table. The added
fields are also added to the *Selected Fields* list.
[role="screenshot"]
image::images/Expanded-Document.png[]
To rearrange the field columns, hover over the header of the column you want to move
and click the *Move left* or *Move right* button.
image:images/Discover-MoveColumn.jpg[Move Column]
[float]
[[removing-columns]]
=== Removing Field Columns from the Documents Table
To remove a field column from the Documents table, hover over the header of the
column you want to remove and click the *Remove* button
image:images/RemoveFieldButton.jpg[Remove Field Button].
=== 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>>.

193
docs/discover/field-filter.asciidoc
View file

@ -1,127 +1,132 @@
[[field-filter]]
== Filtering by Field
You can filter the search results to display only those documents that contain
a particular value in a field. You can also create negative filters that
exclude documents that contain the specified field value.
== Filtering by field
You add field filters from the Fields list, the Documents table, or by manually
adding a filter. In addition to creating positive and negative filters, the
Documents table enables you to filter on whether or not a field is present. The
applied filters are shown below the Query bar. Negative filters are shown in red.
*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.
To add a filter from the Fields list:
[float]
=== Add a filter
. Click the name of the field you want to filter on. This displays the top
five values for that field.
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[height=317]
. To add a positive filter, click the *Positive Filter* button
image:images/PositiveFilter.jpg[Positive Filter].
This includes only those documents that contain that value in the field.
. To add a negative filter, click the *Negative Filter* button
image:images/NegativeFilter.jpg[Negative Filter].
This excludes documents that contain that value in the field.
To add a filter from the Documents table:
. Expand a document in the Documents table by clicking the *Expand* button
image:images/ExpandButton.jpg[Expand Button] to the left of the document's
table entry.
. 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.
+
image::images/Expanded-Document.png[]
. To add a positive filter, click the *Positive Filter* button
image:images/PositiveFilter.jpg[Positive Filter Button] to the right of the
field name. This includes only those documents that contain that value in the
field.
. To add a negative filter, click the *Negative Filter* button
image:images/NegativeFilter.jpg[Negative Filter Button] to the right of the
field name. This excludes documents that contain that value in the field.
. To filter on whether or not documents contain the field, click the
*Exists* button image:images/ExistsButton.jpg[Exists Button] to the right of the
field name. This includes only those documents that contain the field.
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.
To manually add a filter:
. Click *Add Filter*. A popup will be displayed for you to create the filter.
. Choose a field to filter by. This list of fields will include fields from the
index pattern you are currently querying against.
. Try also these filtering options:
+
image::images/add_filter_field.png[]
. Choose an operation for your filter.
* 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:
+
image::images/add_filter_operator.png[]
The following operators can be selected:
[horizontal]
`is`:: Filter where the value for the field matches the given value.
`is not`:: Filter where the value for the field does not match the given value.
`is one of`:: Filter where the value for the field matches one of the specified values.
`is not one of`:: Filter where the value for the field does not match any of the specified values.
`is between`:: Filter where the value for the field is in the given range.
`is not between`:: Filter where the value for the field is not in the given range.
`exists`:: Filter where any value is present for the field.
`does not exist`:: Filter where no value is present for the field.
. Choose the value(s) for your filter. Values from your indices may be suggested
as selections if you are filtering against an aggregatable field.
`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.
+
image::images/add_filter_value.png[]
. (Optional) Specify a label for the filter. If you specify a label, it will be
displayed below the query bar instead of the filter definition.
. Click *Save*. The filter will be applied to your search and be displayed below
the query bar.
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 the advanced setting, `filterEditor:suggestValues`, to `false`.
turn off the suggestions by setting `filterEditor:suggestValues` to `false`
in <<advanced-options,
Advanced Settings>>.
[float]
[[filter-pinning]]
=== Managing Filters
=== Edit, disable, and delete filters
To modify a filter, click on it and click one of the action buttons.
To modify a filter, click its tag, and then select one of the following actions.
image::images/filter-allbuttons.png[]
*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.
&nbsp;
*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.
Pin across all apps :: Pinned filters
persist 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.
Note that a filter is based on a particular index field--if the indices being
searched don't contain the field in a pinned filter, it has no effect.
Edit Filter :: <<filter-edit, Edit the
filter>> definition. Enables you to manually update the filter and
specify a label for the filter.
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. Diagonal stripes indicate
that a filter is disabled.
Remove Filter :: Remove the filter.
To apply a filter action to all of the applied filters,
click *Actions* and select the action.
[float]
[[filter-edit]]
=== Editing a Filter
You can edit a filter by changing the field, operator, or value associated
with the filter (see the Add Filter section above), or by directly modifying
the filter query that is performed to filter your search results. This
enables you to create more complex filters that are based on multiple fields.
=== Modify the filter query
. To edit the filter query, first click the edit button for the filter, then
click *Edit Query DSL*.
+
image::images/edit_filter_query.png[]
. You can then edit the query for the filter.
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, you could use a
{ref}/query-dsl-bool-query.html[bool query] to create a filter for the
sample log data that displays the hits that originated from Canada or China that resulted in a 404 error:
+
////
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]
{

BIN
docs/discover/images/move-icon.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 1.5 KiB

BIN
docs/discover/images/sort-icon.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 1.4 KiB

12
docs/discover/viewing-field-stats.asciidoc
View file

@ -1,14 +1,14 @@
[[viewing-field-stats]]
== Viewing Field Data Statistics
From the Fields list, you can see how many of the documents in the Documents
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.
Data can be visualized in various ways. The quick visualize can only be
applied to aggregatable fields. The keyword fields can be visualized and
they are available in the side bar if we uncheck "Hide missing fields".
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.
To view field data statistics, click the name of a field in the fields list.
image:images/filter-field.png[Field Statistics,height=317]
image:images/filter-field.png[Field Statistics,height=317]

BIN
docs/images/Discover-ContextView-SizePicker-Newer.png
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 5.1 KiB

BIN
docs/images/Discover-ContextView-SizePicker-Older.png
View file

Binary file not shown.
Side by side

Before

Width:  |  Height:  |  Size: 4.9 KiB

BIN
docs/images/Discover-ContextView.png
View file

Binary file not shown.
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 105 KiB

After

Width:  |  Height:  |  Size: 120 KiB

Before After
Before After

BIN
docs/images/Discover-Start.png
View file

Binary file not shown.
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 385 KiB

After

Width:  |  Height:  |  Size: 204 KiB

Before After
Before After

BIN
docs/images/Expanded-Document.png
View file

Binary file not shown.
Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 77 KiB

After

Width:  |  Height:  |  Size: 138 KiB

Before After
Before After

97
docs/user/discover.asciidoc
View file

@ -3,15 +3,100 @@
[partintro]
--
*Discover* enables you to explore your data with {kib}'s data discovery functions.
You have access to every document in every index that matches the selected <<index-patterns, index pattern>>.
You can submit search queries, filter the search results, and view document data.
You can also see the number of documents that match the search query and get field value statistics.
If a time field is configured for the selected index pattern, the distribution of
documents over time is displayed in a histogram at the top of the page.
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.
With *Discover*, you can:
* 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
[role="screenshot"]
image::images/Discover-Start.png[Discover]
[float]
=== Set up your index pattern
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. The current index pattern is in the upper left.
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
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>> in the upper right,
you can specify a common or recently-used time range, a relative time
from now, or an absolute time range.
[float]
=== Search 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.
[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>>.
[role="screenshot"]
image::images/filter-field.png[height=317]
[float]
=== Add and remove fields
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 in the left sidebar.
For example, if you add the `currency`, `customer_last_name`, and `day_of_week` fields,
the document table includes columns for those three fields.
[float]
=== Examine document contents
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.
[float]
=== View a document in context
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>>.
[float]
=== Save and share your search
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.
--
include::{kib-repo-dir}/discover/set-time-filter.asciidoc[]