The heatmap shows query activity across partitions over time. Each partition is represented as a row, and color brightness indicates query frequency — bright yellow means the highest frequency, black means the lowest. Use the heatmap to spot hot partitions and uneven data distribution before they become performance bottlenecks.
The heatmap only covers databases that use automatic partitioning (AUTO mode) in the current instance.
Prerequisites
Before you begin, ensure that you have:
An instance running PolarDB-X V5.4.14 or later. See Release notes and View and update the version of an instance
A privileged account, required to enable data collection for the first time. See Manage database accounts
Key concepts
Hot partition: A partition that receives a disproportionately high volume of queries compared to other partitions. Hot partitions can become a performance bottleneck in a distributed database.
Partition merging: When the total number of original partitions scanned exceeds 1,600, the system merges statistics to keep the display manageable. The merge groups partitions within the same logical table on the same data node. Merging affects only the statistics view, not the underlying data.
Limits
Limit | Details |
Single-database partition limit | If a single logical database has more than 8,000 partitions, data collection is skipped for that database by default. To raise the limit, update the |
Collection task scan limit | Each collection task scans at most 8,000 partitions by default. To raise the limit, update the |
Display limit | If the number of partitions scanned exceeds 3,200, the heatmap displays TOO BIG. When the total number of original partitions scanned exceeds 1,600, the system merges statistics; if the partition count still exceeds 3,200 after merging, TOO BIG is also displayed. |
No data | If no data has been collected yet, the heatmap displays NO DATA. |
Enable or disable data collection
Data collection must be enabled before the heatmap can display any data. Use a privileged account to run the following SQL commands.
Enable:
SET ENABLE_SET_GLOBAL = true;
SET GLOBAL ENABLE_PARTITIONS_HEATMAP_COLLECTION = true;Disable:
SET ENABLE_SET_GLOBAL = true;
SET GLOBAL ENABLE_PARTITIONS_HEATMAP_COLLECTION = false;Data collected before you disable the feature remains visible in the heatmap.
Collect statistics for specific databases or tables
By default, the system collects statistics for all databases and tables. To limit collection to specific targets and reduce overhead, set the PARTITIONS_HEATMAP_COLLECTION_ONLY parameter.
Syntax:
SET ENABLE_SET_GLOBAL = true;
SET GLOBAL PARTITIONS_HEATMAP_COLLECTION_ONLY = '{database}#{table1}&{table2},{database2}#{table1}';Examples:
Collect statistics for the customer and order tables in tpcc, and the nation table in tpch:
SET ENABLE_SET_GLOBAL = true;
SET GLOBAL PARTITIONS_HEATMAP_COLLECTION_ONLY = 'tpcc#customer&order,tpch#nation';Collect statistics for all tables in tpcc and tpch:
SET ENABLE_SET_GLOBAL = true;
SET GLOBAL PARTITIONS_HEATMAP_COLLECTION_ONLY = 'tpcc,tpch';Collect statistics for the customer and order tables across all databases:
SET ENABLE_SET_GLOBAL = true;
SET GLOBAL PARTITIONS_HEATMAP_COLLECTION_ONLY = '#customer,#order';Or equivalently:
SET ENABLE_SET_GLOBAL = true;
SET GLOBAL PARTITIONS_HEATMAP_COLLECTION_ONLY = '#customer&order';Collect statistics for all tables in all databases (default behavior):
SET ENABLE_SET_GLOBAL = true;
SET GLOBAL PARTITIONS_HEATMAP_COLLECTION_ONLY = '';View the heatmap
Log on to the PolarDB-X console.
In the top navigation bar, select the region where the instance is deployed.
On the Instances page, click the PolarDB-X 2.0 tab.
Click the instance ID.
In the left-side navigation pane, choose Diagnosis and optimization > Heatmap.
The heatmap page has four sections:
Section | What it shows |
Left-side histogram | Rectangles representing logical databases, logical tables, and logical partitions. Rectangle length indicates data volume — a longer rectangle means more data. |
Bottom histogram | Total queried rows aggregated by time. Click a point in time to see how many rows were queried across all partitions at that moment. |
Right-side histogram | Total queried rows aggregated by partition. Click a partition to see its query total. |
Heatmap (center) | Color brightness per partition per time interval. Bright yellow = highest query frequency; black = lowest. |
Turn on Data Node View to reorganize the left-side histogram by data node. In this mode, the left-side histogram shows storage nodes, logical databases, logical tables, and logical partitions, making it easier to see whether query load is evenly spread across physical data nodes and to identify which node holds a hot partition.
Inspect a specific data point
Hover over any cell in the heatmap to see the following details:
Field | Description |
Colored box | The color matches the heatmap cell. It shows the queried rows per minute during the collection period. |
Started At | Start of the collection period. |
Ended At | End of the collection period. |
Current Number of Rows | The number of rows in the partition at the time the heatmap was opened — not at Started At or Ended At. |
Data Node | The data node where the partition resides. A dash ( |
Database | The logical database the partition belongs to. |
Table | The logical table the partition belongs to. |
Partition | The name of the logical partition. |