This documentation refers to the on-premises edition of MongoDB Charts beta. Read the Atlas service documentation to learn how to use MongoDB Charts beta with your Atlas project.


A heatmap represents data in a tabular format as a range of color. A darker, or more intense, color represents a larger aggregated value for a particular data point.

Heatmap Encoding Channels

Heatmaps provide the following encoding channels:

Encoding Channel Description
X Axis A category encoding channel that creates a category along the X axis for each unique value in this field.
Y Axis A category encoding channel that creates a category along the Y axis for each unique value in this field.
Intensity An aggregation encoding channel that changes the shading of the matrix elements to reflect the aggregated value of this field. Darker colors in the visualization reflect greater aggregated values.


Heatmaps support sorting and limiting for the X Axis encoding channel, but not the Y Axis channel.

Use Cases

Heatmaps reveal patterns or trends within your data. Use heatmaps when the exact data values are not as important as depicting higher-level trends and relationships between your data points. They can also highlight any significant outliers, or points which strongly go against the general direction of your data. A heatmap is a good choice to display:

  • A comparison of average room rental prices based on location and property type.
  • Geographic data, such as election results across different districts or population density.
  • The number of customer orders across various store locations by month of the year.


Heatmaps work especially well with binned data. With naturally ordered datasets, heatmaps highlight areas of concentration within the data.


The following chart visualizes data pertaining to movies. Each document in the collection represents a movie and contains general information about the film as well as ratings from critics. This heatmap shows the mean (average) Metacritic rating for different movie genres (Y Axis) over time (X Axis):

Heatmap example

We bin the years along the X Axis into decades and aggregate to find the mean metacritic score of films from each genre released in each decade.

The intensity field of metacritic shades each grid element based on the mean metacritic field of all of the intersecting documents based on the X and Y axes fields. Based on the chart, we see that from 1930-1940 there are a few genres with very high average Metacritic scores, and over time a more even distribution of film ratings begins to occur.


If the space is white, there are no movies from that decade of that particular genre in the dataset.

←   Grid Charts Scatter Chart  →