[[visualize]]
== Visualize

You can use Kibana's _Visualize_ app to design and create data visualizations. You can save these visualizations, use
them individually, or combine visualizations into a _dashboard_. A visualization can be based on one of the following 
data source types:

* A new interactive search
* A saved search
* An existing saved visualization

Visualizations are based on the {ref}/search-aggregations.html[aggregation] feature introduced in Elasticsearch 1. 

[float]
[[getting-started]]
=== Creating a New Visualization

To start the New Visualization wizard, click on the *Visualize* tab at the top left of the screen. Alternately, you can 
click the *New Visualization* button image:images/K4NewDocument.png[New Document button] in the toolbar panel to the 
right of the search bar. The wizard guides you through the following steps:

[float]
[[newvis01]]
==== Step 1: Choose the Visualization Type

The New Visualization wizard starts with the following screen:

image:images/NewViz01.png[]

The data table, Markdown, and metric elements aren't visualizations, but all the elements on the list can be included 
in a <<dashboard,Dashboard>>.

You can also open a saved visualization that you created earlier. The saved visualization selector includes a text 
field to filter by visualization name and a link to the Object Editor, accessible through *Settings > Edit Saved 
Objects*, to manage your saved visualizations.

If your new visualization is a Markdown widget, selecting that type takes you to a text entry field where you enter the 
text to display in the widget. For all other types of visualization, selecting the type takes you to data source 
selection.

[float]
[[newvis02]]
==== Step 2: Choose a Data Source

You can choose a new or saved search to serve as the data source for your visualization. Searches are based on an 
_index pattern_, which is a regular expression that matches the indices you want to visualize. After selecting _new 
search_, select an index pattern from the drop-down to bring up the visualization editor. 

// How is this drop-down populated? Is it just a list of all indices in the cluster? Can I configure the contents?

When you create a visualization from a saved search and save the visualization, the search is tied to the visualization.
When you make changes to the search that is linked to the visualization, the visualization updates automatically.

[float]
[[visualization-editor]]
==== Step 3: The Visualization Editor

The visualization editor enables you to configure and edit visualizations. The visualization editor has the following 
main elements:

image:images/VizEditor.png[]

1. <<toolbar-panel,Toolbar Panel>>
2. <<aggregation-builder,Aggregation Builder>>
3. <<preview-canvas,Preview Canvas>>

[float]
[[toolbar-panel]]
===== Toolbar Panel

The toolbar panel has a search field for interactive data searches, as well as toolbars to manage saving and loading
visualizations. For visualizations based on saved searches, the search bar is initially disabled. Double-click the 
grayed-out search field to enable interactive searching.

// Why does it behave this way? I'd like to be able to say 'for saved searches interactive searches are disabled
// because $REASONS'.

The toolbar at the right of the search box has buttons for creating new visualizations, saving the current 
visualization, loading an existing visualization, sharing or embedding the visualization, and refreshing the data for 
the current visualization.

[float]
[[aggregation-builder]]
===== Aggregation Builder

Use the aggregation builder on the left of the screen to configure the 
{ref}/search-aggregations.html#\_metrics_aggregations[metric] and 
{ref}/search-aggregations.html#\_bucket_aggregations[bucket] aggregations used in your visualization. Buckets are 
analogous to SQL `GROUP BY` statements. For more information on aggregations, see the main
{ref}/search-aggregations.html[Elasticsearch documentation].

In bar or line chart visualizations, use _metric_ for the y-axis and _buckets_ are used for the x-axis, segment bar 
colors, and row/column splits. For pie charts, use the metric for the slice size and the bucket for the number of 
slices.

// "Other visualizations may use these in new and different ways." < Such as? Would it be useful to add an appendix
// on advanced visualizations or a cookbook of neat nonintuitive vis tricks?

Choose the metric aggregation for your visualization's Y axis, such as count, average, sum, min, max, or cardinality 
(unique count). Use bucket aggregations for the visualization's X axis, color slices, and row/column splits. Common 
bucket aggregations include date histogram, range, terms, filters, and significant terms.

You can set the order in which buckets execute. In Elasticsearch, the first aggregation determines the data set 
for any subsequent aggregations. The following example involves a date bar chart of Web page hits for the top 5 file 
extensions.

To use the same extension across all hits, set this order:

1.  *Color:* Terms aggregation of extensions
2.  *X-Axis:* Date bar chart of `@timestamp`

Elasticsearch collects the records for the top 5 extensions, then creates a date bar chart for each extension.

To chart the top 5 extensions for each hour, use the following order:

1.  *X-Axis:* Date bar chart of `@timestamp` (with 1 hour interval)
2.  *Color:* Terms aggregation of extensions

For these requests, Elasticsearch creates a date bar chart from all the records, then groups the top five extensions 
inside each bucket, which in this example is a one-hour interval.

NOTE: Remember, each subsequent bucket slices the data from the previous bucket.

To render the visualization on the _preview canvas_, click the *Apply* button at the bottom of the aggregation builder.

[float]
[[preview-canvas]]
===== Preview Canvas

The preview canvas displays a preview of the visualization you've defined in the aggregation builder. To refresh the 
visualization preview, clicking the *Refresh* button image:images/K4Refresh.png[Refresh button] on the toolbar.