kibana/docs/user/dashboard/lens.asciidoc

[[lens]]
=== Create visualizations with Lens
++++
<titleabbrev>Lens</titleabbrev>
++++

To create a visualization, drag the data fields you want to visualize to the workspace, then *Lens* uses visualization best practices to apply the fields and create a visualization that best displays the data. 

With *Lens*, you can:

* Create area, line, and bar charts with layers to display multiple indices and chart types.
* Change the aggregation function to change the data in the visualization.
* Perform math on aggregations using *Formula*.
* Use time shifts to compare the data in two time intervals, such as month over month.
* Create custom tables.

++++
<script type="text/javascript" async 
src="https://play.vidyard.com/embed/v4.js"></script>
<img
style="width: 100%; margin: auto; display: block;"
class="vidyard-player-embed"
src="https://play.vidyard.com/vVJ69WCgUwGNJSDqjPZbaV.jpg"
data-uuid="vVJ69WCgUwGNJSDqjPZbaV"
data-v="4"
data-type="inline"
/>
</br>
++++

[float]
[[create-the-visualization-panel]]
==== Create visualizations

If you're unsure about the visualization type you want to use, or how you want to display the data, drag the fields you want to visualize onto the workspace, then let *Lens* choose for you. 

If you already know the visualization type you want to use, and how you want to display the data, use the following process:

Choose the visualization type. 

. Before you drag fields to the workspace, open the *Chart type* dropdown, then select the visualization type.  

. To view more visualizations that *Lens* automatically created for the fields, click *Suggestions*. If one of the *Suggestions* meets your visualization needs, click *Save and return* to add it to the dashboard.

Choose the data you want to visualize.

. Drag the fields directly to the layer pane. *Lens* automatically selects the aggregation function.

. If you want to learn more about the data a field contains, click the field.

Edit and delete.

. To change the aggregation *Quick function* and display options, click the field in the layer pane. 

. To delete a field, close the configuration options, then click *X* next to the field.

[float]
[[change-the-fields]]
==== Change the fields list

Change the fields list to display a different index pattern, different time range, or add your own fields.

* To create a visualization with fields in a different index pattern, open the *Change index pattern* dropdown, then select the index pattern. 

* If the fields list is empty, change the <<set-time-filter,time filter>>.

* To add fields, open the action menu (*...*) next to the *Change index pattern* dropdown, then select *Add field to index pattern*.
+
[role="screenshot"]
image:images/runtime-field-menu.png[Dropdown menu located next to index pattern field with items for adding and managing fields, width=50%]
+
For more information about adding fields to index patterns and examples, refer to <<runtime-fields>>.

[float]
[[create-custom-tables]]
==== Create custom tables

Tables are highly customizable, and provide you with text alignment, value formatting, coloring options, and more.

. From the *Chart type* dropdown, select *Table*. 

. Drag the fields you want to visualize to the workspace. 

. To sort or hide the columns, click the arrow next to the column heading, then select an option.
+
All columns that belong to the same layer pane group are sorted in the table.

. To change the display options, click a *Metrics* field, then configure the following options:

* *Display name* &mdash; Specifies the field display name. 

* *Value format* &mdash; Specifies how the field value displays in the table. 

* *Text alignment* &mdash; Aligns the values in the cell to the *Left*, *Center*, or *Right*.

* *Hide column* &mdash; Hides the column for the field.

* *Summary row* &mdash; Adds a row that displays the summary value. When specified, allows you to enter a *Summary label*.

* *Color by value* &mdash; Applies color to the cell or text values. To change the color, click *Edit*. 

[float]
[[drag-and-drop-keyboard-navigation]]
==== Create visualizations with keyboard navigation

To use a keyboard instead of a mouse, use the *Lens* fully accessible and continuously improved drag system.

[role="screenshot"]
image::images/lens_drag_drop_1.gif[Presented Lens drag and drop]

. Select the field in the fields list or layer pane. Most fields have an inner and outer select state. The inner state opens a panel with detailed information or options. 
The outer state allows you to drag the field. Tab through the fields until you get the outer state on the field.
+
[role="screenshot"]
image::images/lens_drag_drop_2.png[Lens drag and drop focus state]

. Complete the following actions:

* To select a field, press Space bar.

* To select where you want to drop the field, use the Left and Right arrows.

* To reorder the fields on the layer pane, use the Up and Down arrows.

* To duplicate an action, use the Left and Right arrows, then select the *Drop a field or click to add* field you want to use.
+
[role="screenshot"]
image::images/lens_drag_drop_3.gif[Using drag and drop to reorder]

. To confirm the action, press Space bar. To cancel, press Esc.

[float]
[[lens-formulas]]
==== Use formulas to perform math

Formulas allow you to perform math on aggregated data. The most common formulas divide two values to produce a percent.

. In the layer pane, click a field.

. Click *Formula*, then enter the formula. 
+
Filter ratio example:: To filter a document set, use `kql=''`, then compare to other documents within the same grouping:
+
```
count(kql='response.status_code > 400') / count()
```
+
Week over week example:: To get the value for each grouping from the previous week, use `shift='1w'`.
+
```
percentile(system.network.in.bytes, percentile=99) /
percentile(system.network.in.bytes, percentile=99, shift='1w')
```
You are unable to combine different time shifts, such as `count(shift="1w") - count()` and `count(shift="1w") - count(shift="1m")`, with the *Top values* function.
+
Percent of total example:: To convert each grouping into a percent of the total, formulas calculate `overall_sum` for all groupings:
+
```
sum(products.base_price) / overall_sum(sum(products.base_price))
```
TIP: For detailed information on formulas, click image:dashboard/images/formula_reference.png[Formula reference icon].

. To accurately display the formula, select *Percent* from the *Value format* dropdown.

[float]
[[compare-data-with-time-offsets]]
==== Compare differences over time

Compare your real-time data set to the results that are offset by a time increment. For example, you can compare the real-time percentage of a user CPU time spent to the results offset by one hour. 

. In the layer pane, click the field you want to offset.

. From the *Add advanced options* dropdown, select *Time shift*.

. Select the time offset increment. 

For a time shift example, refer to <<compare-time-ranges>>.

[float]
[[filter-the-data]]
==== Apply filters

You can use the <<semi-structured-search, KQL query bar>> to focus on a known set of data for the entire visualization, or use the filter options from the layer pane or legend.

[float]
[[filter-with-the-function]]
===== Apply multiple KQL filters

With the *Filters* function, you can apply more than one KQL filter, and apply a KQL filter to a single layer so you can visualize filtered and unfiltered data at the same time.

. In the layer pane, click a field.

. Click the *Filters* function.

. Click *Add a filter*, then enter the KQL filter you want to apply.
+
To try the *Filters* function on your own, refer to <<custom-ranges,Compare a subset of documents to all documents>>.

[float]
[[filter-with-the-advanced-option]]
===== Apply a single KQL filter

With the *Filter by* advanced option, you can assign a color to each filter group in *Bar* and *Line and area* visualizations, and build complex tables. For example, to display failure rate and the overall data.

. In the layer pane, click a field.

. Click *Add advanced options*, then select *Filter by*.

. Enter the KQL filter you want to apply.

[float]
[[filter-with-legend-filters]]
===== Apply legend filters

Apply filters to visualizations directly from the values in the legend. *Bar*, *Line and area*, and *Proportion* visualizations support legend filters.

In the legend, click the field, then choose one of the following options:

* *Filter for value* &mdash; Applies a filter that displays only the field data in the visualization.

* *Filter out value* &mdash; Applies a filter that removes the field data from the visualization.

[float]
[[configure-the-visualization-components]]
==== Configure the visualization components

Each visualiztion type comes with a set of components that you access from the editor toolbar.

The following component menus are available:

* *Visual options* &mdash; Specifies how to display area, line, and bar chart options. For example, you can specify how to display the labels in bar charts.

* *Labels* &mdash; Specifies how to display the labels for donut charts, pie charts, and treemaps. 

* *Legend* &mdash; Specifies how to display the legend. For example, you can display the legend inside the visualization and truncate the legend values.

* *Left axis*, *Bottom axis*, and *Right axis* &mdash; Specify how you want to display the chart axes. For example, add axis labels and change the orientation and bounds.

[float]
[[save-the-lens-panel]]
===== Save and add the panel

Save the panel to the *Visualize Library* and add it to the dashboard, or add it to the dashboard without saving.

To save the panel to the *Visualize Library*:

. Click *Save to library*.

. Enter the *Title* and add any applicable <<managing-tags,*Tags*>>.

. Make sure that *Add to Dashboard after saving* is selected.

. Click *Save and return*.

To save the panel to the dashboard:

. Click *Save and return*.

. Add an optional title to the panel.

.. In the panel header, click *No Title*.

.. On the *Customize panel* window, select *Show panel title*.

.. Enter the *Panel title*, then click *Save*.

[float]
[[lens-faq]]
=== Frequently asked questions

For answers to common *Lens* questions, review the following. 

[discrete]
[[when-should-i-normalize-the-data-by-unit-or-use-a-custom-interval]]
.*When should I normalize the data by unit or use a custom interval?*
[%collapsible]
====
* *Normalize by unit* &mdash; Calculates the average for the interval. When you normalize the data by unit, the data appears less granular, but *Lens* is able to calculate the data faster. 

* *Customize time interval* &mdash; Creates a bucket for each interval. When you customize the time interval, you can use a large time range, but *Lens* calculates the data slower.

To normalize the interval: 

. In the layer pane, click a field.

. Click *Add advanced options > Normalize by unit*. 

. From the *Normalize by unit* dropdown, select an option, then click *Close*.

To create a custom interval:

. In the layer pane, click a field.

. Select *Customize time interval*.

. Change the *Minimum interval*, then click *Close*.
====

[discrete]
[[what-is-the-other-category]]
.*What data is categorized as Other?*
[%collapsible]
====
The *Other* category contains all of the documents that do not match the specified criteria or filters. 
Use *Other* when you want to compare a value, or multiple values, to a whole.

By default, *Group other values as "Other"* is enabled when you use the *Top values* function. 

To disable *Group other values as "Other"*, click a field in the layer pane, click *Advanced*, then deselect *Group other values as "Other"*.
====

[discrete]
[[how-can-i-include-documents-without-the-field-in-the-operation]]
.*How do I add documents without a field?*
[%collapsible]
====
By default, *Lens* retrieves only the documents from the fields. 
For bucket aggregations, such as *Top values*, you can add documents that do not contain the fields, 
which is helpful when you want to make a comparison to the whole documentation set.

. In the layer pane, click a field. 

. Click *Advanced*, then select *Include documents without this field*.
====

[discrete]
[[when-do-i-use-runtime-fields-vs-formula]]
.*When do I use runtime fields vs. formula?*
[%collapsible]
====
Use runtime fields to format, concatenate, and extract document-level fields. Runtime fields work across all of {kib} and are best used for smaller computations without compromising performance.

Use formulas to compare multiple {es} aggregations that can be filtered or shifted in time. Formulas apply only to *Lens* panels and are computationally intensive.
====

[discrete]
[[is-it-possible-to-have-more-than-one-Y-axis-scale]]
.*Can I add more than one y-axis scale?*
[%collapsible]
====
For each y-axis, you can select *Left* and *Right*, and configure a different scale.
====

[discrete]
[[why-is-my-value-with-the-right-color-using-value-based-coloring]]
.*Why is my value the incorrect color when I use value-based coloring?*
[%collapsible]
====
Here's a short list of few different aspects to check:

* Make sure the value falls within the desired color stop value defined in the panel. Color stop values are "inclusive".

* Make sure you have the correct value precision setup. Value formatters could round the numeric values up or down.

* Make sure the correct color continuity option is selected. If the number is below the first color stop value, a continuity of type `Below` or `Above and below range` is required.

* The default values set by the Value type are based on the current data range displayed in the data table.

** If a custom `Number` configuration is used, check that the color stop values are covering the current data range.

** If a `Percent` configuration is used, and the data range changes, the colors displayed are affected.
====

[discrete]
[[can-i-sort-by-multiple-columns]]
.*How do I sort by multiple columns?*
[%collapsible]
====
Multiple column sorting is unsupported, but is supported in *Discover*. For information on how to sort multiple columns in *Discover*, 
refer to <<explore-fields-in-your-data,Explore the fields in your data>>.
====

[float]
[[why-my-field-is-missing-from-the-fields-list]]
.*Why is my field missing from the fields list?*
[%collapsible]
====
The following field types do not appear in the *Available fields* list:

* Full-text
* geo_point
* flattened
* object

Verify if the field appears in the *Empty fields* list. *Lens* uses heuristics to determine if the fields contain values. For sparse data sets, the heuristics are less precise.
====

[float]
[[how-to-handle-gaps-in-time-series-visualizations]]
.*What do I do with gaps in time series visualizations?*
[%collapsible]
====
When you create *Area* and *Line* charts with sparse time series data, open *Visual options* in the editor toolbar, then select a *Missing values* option.
====

[discrete]
[[is-it-possible-to-change-the-scale-of-Y-axis]]
.*Can I statically define the y-axis scale?*
[%collapsible]
====
You can set the scale, or _bounds_, for area, bar, and line charts. You can configure the bounds for all functions, except *Percentile*. Logarithmic scales are unsupported.

To configure the bounds, use the menus in the editor toolbar. Bar and area charts required 0 in the scale between *Lower bound* and *Upper bound*. 
====

[discrete]
[[is-it-possible-to-show-icons-in-datatable]]
.*Is it possible to display icons in data tables?*
[%collapsible]
====
You can display icons with <<managing-index-patterns, field formatter>> in data tables.
====

[discrete]
[[is-it-possible-to-use-saved-serches-in-lens]]
.*How do I visualize saved searches?*
[%collapsible]
====
Visualizing saved searches in unsupported.
====

[discrete]
[[is-it-possible-to-decrease-or-increase-the-number-of-suggestions]]
.*How do I change the number of suggestions?*
[%collapsible]
====
Configuring the *Suggestions* is unsupported.
====

[discrete]
[[is-it-possible-to-have-pagination-for-datatable]]
.*Is it possible to have pagination in a data table?*
[%collapsible]
====
Pagination in a data table is unsupported. To use pagination in data tables, create an <<types-of-visualizations,aggregation-based data table>>.
====

[discrete]
[[is-it-possible-to-select-color-for-specific-bar-or-point]]
.*How do I change the color for a single data point?*
[%collapsible]
====
Specifying the color for a single data point, such as a single bar or line, is unsupported.
====

[discrete]
[[is-it-possible-to-inspect-the-elasticsearch-queries-in-Lens]]
.*How do I inspect {es} queries in visualizations?*
[%collapsible]
====
You can inspect the requests sent by the visualization to {es} using the Inspector. It can be accessed within the editor or in the dashboard.
====

[discrete]
[[how-to-isolate-a-single-series-in-a-chart]]
.*How do I isolate a single series in a chart?*
[%collapsible]
====
For area, line, and bar charts, press Shift, then click the series in the legend. All other series are automatically unselected.
====