> For the complete documentation index, see [llms.txt](https://docs.avonnicomponents.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.avonnicomponents.com/flow/tutorials/components/metric/show-a-kpi-from-a-query.md).

# Show a KPI from a query

Show this quarter's won revenue on a flow screen, summed live from Opportunities by the Metric's own query, with no Get Records or loop.

A sales manager opens the forecast flow and the first screen should answer one question: how much have we won this quarter? The Metric can sum the won Opportunities itself, so the number is current every time the screen loads, and the flow needs no Get Records element for it.

<figure><img src="https://27923732-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1FUd4apB9YHgCEMUFbVb%2Fuploads%2FY18OgcwYc8YzGldgRdHT%2Fmetric-kpi-query-result.png?alt=media" alt="Avonni Metric on a flow screen: Won This Quarter, US$482,500, with the description Closed Won opportunities, current quarter" width="450"><figcaption><p>The Metric sums the won Opportunities itself, so the total is current each time the screen loads.</p></figcaption></figure>

## Before you start

* A screen flow with a screen to put the Metric on. [Metric](https://docs.avonnicomponents.com/flow/flow-components/metric.md) covers adding the component.
* Read access to Opportunity and its **Amount**, **Stage** and **Close Date** fields for the users who run the flow.

## Steps

{% stepper %}
{% step %}

### Write the filter as a Text formula

In the flow's **Toolbox**, create a formula resource `WonThisQuarterFilter` of data type **Text**. It is the condition the Metric's query applies:

`"StageName = 'Closed Won' AND CloseDate = THIS_QUARTER"`

`THIS_QUARTER` is a SOQL date literal, so the KPI rolls over to the new quarter on its own and needs no date formulas. If your org runs on a fiscal year, use `THIS_FISCAL_QUARTER`. Use API names (`StageName`, `CloseDate`) and straight quotes, and leave the date literal unquoted.
{% endstep %}

{% step %}

### Point the Value at a query

Add an **Avonni Metric** to the screen and click **Open Component Builder**. In **Primary Metric**:

1. Set **Format Style** to **Currency**, **Currency Code** to `USD` and **Maximum Fraction Digits** to `0`.
2. Open the mode menu of **Value** and pick **Query**.
3. Choose **Opportunity** as the object, `Amount` as the **Field** and **Sum** as the **Aggregate Function**.
4. Switch **Filters** to **Mapped** and select `WonThisQuarterFilter`. The **Filters** box then shows the resource's label, **Won This Quarter Filter**.

<figure><img src="https://27923732-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1FUd4apB9YHgCEMUFbVb%2Fuploads%2FCXLA9YlLiE6b0i5o6wNF%2Fmetric-kpi-query-panel.png?alt=media" alt="Component Builder Primary Metric group: Format Style Currency, Value in Query mode on Opportunity, Field Amount, Aggregate Function Sum, Filters mapped to Won This Quarter Filter" width="320"><figcaption><p>Value in Query mode: Sum of Amount on Opportunity, filtered by the Text formula.</p></figcaption></figure>
{% endstep %}

{% step %}

### Label it

Set **Label** to `Won This Quarter` and **Description** to `Closed Won opportunities, current quarter`. The description tells the reader what is inside the number, which saves a question in the forecast call.
{% endstep %}

{% step %}

### Save and test

Save the flow and run it with **Debug**. The screen shows `Won This Quarter` over the summed amount, for example `$482,500`. Close an Opportunity as **Closed Won** in another tab, rerun the flow, and the total goes up by that amount.
{% endstep %}
{% endstepper %}

## Troubleshooting

<details>

<summary>The metric shows $0</summary>

Check the formula output first: add a Display Text with `{!WonThisQuarterFilter}` to the screen and read it in **Debug**. A missing quote, a quoted date literal (`'THIS_QUARTER'`) or a picklist value spelled differently from the org's `StageName` value returns no records.

</details>

<details>

<summary>An average or a filter on a number field looks wrong</summary>

A blank number field is not `0`. Turn on **Treat Blank Value as Zero** when a blank should count as zero in the aggregate. In a filter, `Field = 0` never matches a blank field. In a **Manual** filter, add a condition that compares the field to the global constant `Null`.

</details>

## Related tutorials

* [Format money, percent and dates](https://docs.avonnicomponents.com/flow/tutorials/components/metric/format-money-percent-and-dates.md): shape the number this tutorial produces.
* [Add a trend against a target](https://docs.avonnicomponents.com/flow/tutorials/components/metric/add-a-trend-against-a-target.md): color the same KPI red or green against the quarter's target.
* [How to make Data Tables reactive](https://docs.avonnicomponents.com/flow/tutorials/reactive-query-tutorials/how-to-make-data-tables-reactive.md): the same Text formula filter, driven by another component on the screen.


---

# 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.avonnicomponents.com/flow/tutorials/components/metric/show-a-kpi-from-a-query.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.
