---
title: "metadata-matches macro"
canonical: "https://support.appfire.com/space/COMALACM/656580345/metadata-matches%20macro"
format: markdown
---
> Macro (aura-html)

## <span style="color: #091e42">Overview</span>

<span style="color: #091e42">The </span>`metadata-matches`<span style="color: #091e42"> macro totals the number of matching pages with a particular metadata value. This result can be shown directly or can be used as input to another statistics macro.</span>

<span style="color: #091e42">In addition, this macro allows for another metadata value to be calculated for each matching page. If another metadata value name is specified, the macro displays a calculation based on the values of this metadata on the matching pages rather than the count of the number of occurrences.</span>

## Parameters

| Parameter | Required | Default | Notes | Version |
| --- | --- | --- | --- | --- |
| **first parameter** | :check_mark: |  | <span style="color: #000000">The metadata value name whose values will be matched. This can include added metadata and internal metadata.</span><br>The value of the metadata to be matched is added to the macro placeholder (macro body).<br><span style="color: #000000">If a </span>`value-name`<span style="color: #000000"> is NOT specified for a calculation in the </span>`value-name`<span style="color: #000000"> field, then the macro </span><span style="color: #000000">***will return a count of the number of occurrences of this first parameter metadata value***</span><span style="color: #000000">** **</span><span style="color: #000000">specified in the body of the macro placeholder.</span> |  |
| `function` |  | sum | <span style="color: #000000">If a </span>`value-name`<span style="color: #000000"> is specified for a calculation, then the macro will use the specified </span>`function`<span style="color: #000000"> on the values taken from the matching pages and display the calculated value of this </span>`function.`<span style="color: #091e42"> </span><br>- `sum` - returns the sum of each non-empty value (default)
- `average` - returns the average of each non-empty value
- `maximum `- returns the minimum of each non-empty value
- `minimum` - returns the maximum of each non-empty value<br>:info: <span style="color: #091e42">The metadata value that is compared</span>*** includes***** **<span style="color: #091e42">any wiki markup characters used for the value.</span> |  |
| `key` |  | `current space` | <span style="color: #091e42">Limits the content returned to within the space with the given key.</span> |  |
| `root` |  | `current page (@self)` | <span style="color: #000000">Use</span><span style="color: #707070"> </span>`@self`<span style="color: #707070"> </span><span style="color: #000000">for the current page (the default),</span><span style="color: #707070"> </span>`@parent`<span style="color: #707070"> </span><span style="color: #000000">for the parent page, or the name of any page, e.g </span>`MySpace:MyPage`<span style="color: #707070">.</span><br><span style="color: #000000">If this is specified and the pages option is not, then the report will run over only the pages listed here.</span> |  |
| `label` |  |  | <span style="color: #000000">Limits the content to that with the specified label or labels. A comma-separated list produces ANY pages that match.</span> |  |
| `type` |  |  | <span style="color: #091e42">Specifies which Confluence content types should be considered for a report.</span><br>:info: <span style="color: #000000">This feature is based on the Confluence </span><span style="color: #000000">**contentbylabel**</span><span style="color: #000000"> macro, which has the same attribute.</span> |  |
| `value-name` |  | `sum` | Second metadata value that can be used to generate a calculation - the default is `sum`. However, it can also apply the same functions as used in the `metadata-calculate` macro. |  |

## Usage

To retrieve the number of pages with a particular value for metadata

- Choose the **Metadata matches** macro from the Confluence macro browser:

![image](media://ba4a2514-e4a2-413a-9cc1-b4e0b27399b3)

The macro editor requires the metadata value name to be added:

![image](media://df3b6b05-e504-444d-a05e-0e3397c0d462)

The value for the metadata is added to the macro placeholder

![image](media://e6595e49-1313-47a8-9ad0-1cac25872ee0)

The value added to the macro placeholder must include all the values - *here, the value includes some wiki format.*

In this example, the page where the macro is added displays the sum of the number of pages with matching metadata values for the `Current Lifecycle status` metadata value name:

![image](media://0f0f005f-23e3-47c5-abaa-c29454ea62be)

This value can be used for other Confluence statistical macros, such as the Confluence `Chart` macro.

### Adding a metadata value-name for a calculation of the values on the matched pages

Adding a metadata value name to the `value-name` option in the macro editor adds the ability to perform calculations on the values of a specified metadata on the matching pages.

In our example above, the `metadata-matches` macro displays the count of the number of child pages where the `Current Lifecycle status` metadata has a value of `|Active|`.

If another metadata field is added to the value-name field, the macro calculates the values of this second metadata for any occurrences on the matching pages.

In the example, in the macro editor:

- adding an existing metadata name, `Feb Hours`

![image](media://77563df8-d12a-43bf-94d8-1a9ccf589002)

- choosing the `function` as `sum`

![image](media://08af5835-e7cc-4fef-8462-b67d207945f1)

- amends the macro placeholder to show the added `value-name` parameter

![image](media://397c0fe2-9c4f-4aea-8299-cfb87fefcbab)

The macro body still contains the metadata value `|Active|`, the macro only performs the calculation on the pages with this matching value.

The page display the sum based on the values of `Feb Hours` on the matching pages:

![image](media://7ee2dbd1-44bf-4dfa-9d3c-34bd68988860)

In the example, across the matching pages where the metadata `Current Lifecycle status` has a value of `|Active|`, the sum of the metadata `Feb Hours` values is 84.

Another [example of use ](https://appfire.atlassian.net/wiki/spaces/COMALACM/pages/655759394)of the `metadata-matches` macro is to add multiple versions of the macro to populate a table, creating a dashboard of information from a group of pages

<span style="color: #091e42">Multiple versions of the metadata-matches macro can also be added to the Confluence </span>**chart**<span style="color: #091e42"> macro to visualise and present the collated data from each report.</span>

## <span style="color: #091e42">Reference markup</span>

```plaintext
{metadata-matches:Current Lifecycle status}|Active|{metadata-matches}
```

The macro will retrieve the number of times the `Current Lifecycle status` metadata values for the child pages of the current page are equal to `|Active|`.

If the metadata value includes formatting, this must be included in the body of the `metadata-matches` macro.

The report is displayed as a count of the number of pages that currently with this value for the metadata.

 If a calculation is required for a metadata value on these matching pages, an example of the markup required for the default sum of these values is:

```plaintext
{metadata-matches:Current Lifecycle status|value-name=Feb Hours}|Active|{metadata-matches}
```

## Related macros

- [https://appfire.atlassian.net/wiki/spaces/COMALACM/pages/655891311](https://appfire.atlassian.net/wiki/spaces/COMALACM/pages/655891311)
- [https://appfire.atlassian.net/wiki/spaces/COMALACM/pages/655759844](https://appfire.atlassian.net/wiki/spaces/COMALACM/pages/655759844)

## Related pages

- [Searching and reporting](https://appfire.atlassian.net/wiki/spaces/COMALACM/pages/656577723)