[[heatmap-chart]]
== Heatmap Chart

A heat map is a graphical representation of data where the individual values contained in a matrix are represented as colors.
The color for each matrix position is determined by the _metrics_ aggregation. The following aggregations are available for
this chart:

include::y-axis-aggs.asciidoc[]

The _buckets_ aggregations determine what information is being retrieved from your data set.

Before you choose a buckets aggregation, specify if you are defining buckets for X or Y axis within a single chart
or splitting into multiple charts. A multiple chart split must run before any other aggregations.
When you split a chart, you can change if the splits are displayed in a row or a column by clicking
the *Rows | Columns* selector.

This chart's X and Y axis supports the following aggregations. Click the linked name of each aggregation to visit the main
Elasticsearch documentation for that aggregation.

*Date Histogram*:: A {ref}/search-aggregations-bucket-datehistogram-aggregation.html[_date histogram_] is built from a
numeric field and organized by date. You can specify a time frame for the intervals in seconds, minutes, hours, days,
weeks, months, or years. You can also specify a custom interval frame by selecting *Custom* as the interval and
specifying a number and a time unit in the text field. Custom interval time units are *s* for seconds, *m* for minutes,
*h* for hours, *d* for days, *w* for weeks, and *y* for years. Different units support different levels of precision,
down to one second. Intervals are labeled at the start of the interval, using the date-key returned by Elasticsearch. 
For example, the tooltip for a monthly interval will show the first day of the month.

*Histogram*:: A standard {ref}/search-aggregations-bucket-histogram-aggregation.html[_histogram_] is built from a
numeric field. Specify an integer interval for this field. Select the *Show empty buckets* checkbox to include empty
intervals in the histogram.
*Range*:: With a {ref}/search-aggregations-bucket-range-aggregation.html[_range_] aggregation, you can specify ranges
of values for a numeric field. Click *Add Range* to add a set of range endpoints. Click the red *(x)* symbol to remove
a range.
*Date Range*:: A {ref}/search-aggregations-bucket-daterange-aggregation.html[_date range_] aggregation reports values
that are within a range of dates that you specify. You can specify the ranges for the dates using
{ref}/common-options.html#date-math[_date math_] expressions. Click *Add Range* to add a set of range endpoints.
Click the red *(x)* symbol to remove a range.
*IPv4 Range*:: The {ref}/search-aggregations-bucket-iprange-aggregation.html[_IPv4 range_] aggregation enables you to
specify ranges of IPv4 addresses. Click *Add Range* to add a set of range endpoints. Click the red *(x)* symbol to
remove a range.
*Terms*:: A {ref}/search-aggregations-bucket-terms-aggregation.html[_terms_] aggregation enables you to specify the top
or bottom _n_ elements of a  given field to display, ordered by count or a custom metric.
*Filters*:: You can specify a set of {ref}/search-aggregations-bucket-filters-aggregation.html[_filters_] for the data.
You can specify a filter as a query string or in JSON format, just as in the Discover search bar. Click *Add Filter* to
add another filter. Click the image:images/labelbutton.png[Label button icon] *label* button to open the label field, where
you can type in a name to display on the visualization.
*Significant Terms*:: Displays the results of the experimental
{ref}/search-aggregations-bucket-significantterms-aggregation.html[_significant terms_] aggregation.

Enter a string in the *Custom Label* field to change the display label.

You can click the *Advanced* link to display more customization options for your metrics or bucket aggregation:

*Exclude Pattern*:: Specify a pattern in this field to exclude from the results.
*Include Pattern*:: Specify a pattern in this field to include in the results.
*JSON Input*:: A text field where you can add specific JSON-formatted properties to merge with the aggregation
definition, as in the following example:

[source,shell]
{ "script" : "doc['grade'].value * 1.2" }

The availability of these options varies depending on the aggregation you choose.

Select the *Options* tab to change the following aspects of the chart:

*Show Tooltips*:: Check this box to enable the display of tooltips.
*Highlight*:: Check this box to enable highlighting of elements with same label
*Legend Position*:: You can select where to display the legend (top, left, right, bottom)


*Color Schema*:: You can select an existing color schema or go for custom and define your own colors in the legend
*Reverse Color Schema*:: Checking this checkbox will reverse the color schema.
*Color Scale*:: You can switch between linear, log and sqrt scales for color scale.
*Scale to Data Bounds*:: The default Y axis bounds are zero and the maximum value returned in the data. Check
this box to change both upper and lower bounds to match the values returned in the data.
*Number of Colors*:: Number of color buckets to create. Minimum is 2 and maximum is 10.
*Percentage Mode*:: Enabling this will show legend values as percentages.
*Custom Range*:: You can define custom ranges for your color buckets. For each of the color bucket you need to specify
the minimum value (inclusive) and the maximum value (exclusive) of a range.
*Show Label*:: Enables showing labels with cell values in each cell
  *Rotate*:: Allows rotating the cell value label by 90 degrees.