The {metadata-report} macro shows metadata from matching pages in a tabular report.

You can use the macro to display multiple pieces of metadata from a single page or a group of pages.

Any metadata created with the Comala Metadata App {metadata} or {metadata-list} macros can be displayed in the report. 

The macro will also retrieve values for any Confluence internal metadata, such as Page alongside metadata created with the Comala Metadata App.

The macro can be used to select: 

  • a selection of multiple metadata values from a single page
  • a selection of multiple metadata values from a group of pages in the same space

The macro can also be configured to calculate a sum of all the retrieved values for an individual metadata value name



The list of fields (columns) to be included in the report. This can include added metadata and internal metadata.

Limits the content to only that which has the specified label(s).

A comma-separated list produces ANY pages that match while using + will give ALL pages.

Parentheses may be used to build up complex expressions, e.g |labels=(yellow,red)+fruit


Specify the space key from which the pages are listed.

(blue star) Only a single space key can be specified in the macro.

current page (@self)

Use @self for the current page (the default), @parent for the parent page, or the name of any page†, e.g MySpace:MyPage.

If this is specified and the pages option is not, then the search will run over only the children of the pages listed here (or children of the current page if this field is left blank as the default @self is used)

(warning) If the page title includes a ","(comma), as the comma is a page title separator in a list for the parameter, the macro may truncate the list.

To avoid the problem of a comma in a page title truncating a list, from Comala Metadata v4.2.8 you can specify a page using its id by using id:123456 in the parameter list instead of the page title.



Specify a set of pages to grab from the root page(s).


  • @children
  • @ancestors
  • @descendants
  • @identity

For example, |root=@self|pages=@children will give all children of the current page. This can be used in combination with the labels option to find all children with a particular label.


Specify columns in the report that should link back to the content.

Specifies the maximum number of results in a report. Default is 500.

What order should results be sorted in?

  • ascending – A→Z
  • descending – Z→A

You can combine this with sort.


Specifies which column in the report should be sorted by.

You can also include a hint for the sort method before the sort direction. For instance "Name as istring asc" or "Name as istring" will apply a case-insensitive comparison, considering values as string.

Other choices include

  • "as date"
  • "as number"
  • "as string" (case-sensitive)

Default is case-insensitive comparison.


Specifies a comma-separated list of values to be totalled.

Specifies the content type to search within for the specified metadata value names.

  • page
  • blogpost


The metadata value that will be used for a calculation


To retrieve multiple metadata values from a page or pages, choose the Metadata report macro from the Confluence macro browser:

The macro editor allows you to configure the macro before you Insert the macro to the page:

metadata report macro browser editor showing fields, space key and link options

The macro requires you to enter at least one metadata value name into Fields. Multiple metadata values can be retrieved by adding a comma separated list of metadata value names.

Adding the metadata value names and choosing to Insert the macro adds the macro placeholder to the page being edited.

This displays a table on the page of the metadata value names and their values from the child pages of the current page.

For example, the macro placeholder above would display the values for three pieces of metadata for each of the child pages:

The retrieved metadata values for the metadata are displayed in a separate row for each child page.

If the metadata value names are not found, or there is no value has added, the table will display the metadata value names specified in the macro but with no value(s) added. The columns are in order of listing of the metadata value names in the macro editor.

Additional options in the macro editor allow you to customise the macro.

Customizing the {metadata-report} macro to select pages for the report

The choice of source pages for the metadata report can be customized as follows:

  • Space key determines the space for the page metadata to be listed
  • Content type - pages or blog posts
  • Root defaults to the current page and will report the metadata values on the child pages of the current page. 

You can choose the root to be parent page of the current page using @parent or the specify the name of a page for the root page. If these are added then the source for the metadata report will be limited to the metadata on the specified root page. 

To retrieve the metadata from a related group of pages to a specified root page, you must use the Pages option :

The Pages option can be used with the Labels option to select pages with a particular label from a group of related pages.

Macro Totals option

The report can provide totals for certain columns of metadata values using the Totals option. 

In this example two metadata value names are added to the Totals option as a comma separated list:

This displays the metadata values from each page and a sum of their values for each metadata value name:

Note: null returned metadata values in a column to be summed may result in an error and text based values will return a zero sum.

Other macro options

The macro also has options to:

  • sort the retrieved metadata values in ascending or descending order.
  • display a set number of results.

Reference Markup

The basic format of the macro is:


This results in a tabular report for the specified on the current page (with three child pages):

Usage with the Comala Document Management app

The {metadata-report} macro is supported by the Comala Document Management app.

Related Comala Metadata App macros

Related documentation