> For the complete documentation index, see [llms.txt](https://docs.buildings.ability.abb/collection/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.buildings.ability.abb/collection/platform/live-cockpit/widgets/predefined-widgets/ranking.md).

# Ranking

Use the predefined **Ranking** widget to compare the latest numeric values of assets with the same asset type. It displays up to ten matching assets, with the highest value first.

For example, compare the current power demand of heat pumps to identify the largest consumers, or compare temperature readings across devices of the same type.

## Prerequisites

* You can edit the target dashboard.
* You can access assets of the required type with a numeric value for the attribute you want to compare.
* If you want to filter by tags, the relevant tags are already assigned to those assets.

## Configure the Ranking

1. Open the [dashboard](https://docs.buildings.ability.abb/collection/platform/live-cockpit/add-widgets-to-the-dashboard.md) in **Live Cockpit** **\[A]**.
2. Select **+ Widget**.
3. Select **Ranking** from **Builtin**.\
   ▷ The **Add Widget: Ranking** dialog opens.

<figure><img src="https://2013058394-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOqGnkz52o2zVUsEGEZGk%2Fuploads%2Fgit-blob-b68b90f5afa760717254dc387220e9b9e676aa7b%2Franking-widget-configuration.png?alt=media" alt="Builtin Ranking configuration for the VIRTUAL Heat Pump asset type and Power attribute, with asset selection, tag filters, and Add Widget marked"><figcaption><p>Choose the asset type, attribute, and optional tag filter.</p></figcaption></figure>

| Reference | Control           | Purpose                                                                                                                                                       |
| --------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **\[B]**  | **Asset type**    | Limits the ranking to assets of one type.                                                                                                                     |
| **\[C]**  | **Attribute**     | The numeric attribute whose latest stored value determines each asset's position.                                                                             |
| **\[D]**  | Tag matching mode | **All the selected required** includes assets with every selected tag. **One of the selected** includes assets with at least one selected tag.                |
| **\[E]**  | **Tags**          | Optional asset tags that narrow the ranking, for example to equipment at one location. Leave this empty to include matching assets without a tag restriction. |
| **\[F]**  | **Add Widget**    | Saves the configuration and adds the ranking to the dashboard.                                                                                                |

4. Select an **Asset type** **\[B]**.
5. Select an **Attribute** **\[C]**, such as **Power**.
6. Select the required tags in **Tags** **\[E]**, if you want to narrow the selection.
7. Select the tag matching mode **\[D]**, if you use a tag filter.
8. Choose a **Width** that makes the asset names and values easy to read.
9. Select **Add Widget** **\[F]**.\
   ▷ The dashboard displays the ranked assets.

Changing **Asset type** clears **Attribute**. Select the attribute again before saving.

The optional **Primary asset (for title and alarms)** supplies the widget's header and alarm context. The ranked assets are determined separately by **Asset type**, **Attribute**, and **Tags**. For subtitles, descriptions, and later configuration changes, see [Operating Widgets](https://docs.buildings.ability.abb/collection/platform/live-cockpit/widgets/operating-widgets.md).

## Read the Result

<figure><img src="https://2013058394-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOqGnkz52o2zVUsEGEZGk%2Fuploads%2Fgit-blob-c35a087c2ea5d37d718cfc491f09a65b10bddcdc%2Franking-widget-result.png?alt=media" alt="Dashboard Ranking widget showing seven heat-pump assets with Power values in kilowatts, ordered from highest to lowest"><figcaption><p>A populated ranking using the latest Power values.</p></figcaption></figure>

The table **\[G]** contains two columns:

* **Assets:** The names of the matching assets. The column heading includes the selected asset type.
* **Values:** The selected attribute's latest stored value, including its configured unit. The column heading includes the attribute name.

In this example, **VIRTUAL Heat Pump assets** identifies the asset group and **Power values** shows each asset's latest power reading in kW. The first row has the highest reading among the matching assets.

A higher power value means greater demand at that reading; it does not by itself indicate a fault or poor efficiency. Compare similar equipment and consider its operating load.

Only assets you can access participate in the ranking. If more than ten assets match, the widget shows the ten highest values. If an expected asset is missing, check its asset type, attribute value, tags, and your access to it.

For comparisons over a selected day, week, month, or year, use [Scoreboard: Usage Comparison](https://docs.buildings.ability.abb/collection/platform/insight-analytics/analytics-types/scoreboard-usage-comparison.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.buildings.ability.abb/collection/platform/live-cockpit/widgets/predefined-widgets/ranking.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
