Searching with Metadata (v 2.0)

Introduction

Except when filtering via expert filter criteria, Metadata uses Confluence Query Language (CQL) in all of its features. The filtering via expert filter criteria follows the Confluence Search Syntax, which is based on the Lucene search syntax. Lucene search syntax strings may also be used in the Confluence search.

You can access metadata which has been configured via Metadata for Confluence as well as default Confluence metadata like "Creator", "Created" and "Label". 

Please refer to the next sections for a more detailed explanation how to search for and filter metadata in the Confluence search as well as searching and filtering in Metadata for Confluence macros.

Topics include:

Metadata in Confluence Search

SINCE VERSION 2.0 SINCE CONFLUENCE 5.9

Filtering Confluence Search Results (CQL)

With Metadata for Confluence, you can add filters to your search based on available metadata. This feature uses CQL.

Go to the Confluence search results page, e.g. by clicking in the quick search field at the top-right of every Confluence page and hitting Enter. To filter your search results, perform the following steps:

1. Click on the "Add a filter" link on the bottom left.
   
2. Start typing to filter the available metadata fields or use your mouse to select the metadata field you want to filter for.
   Metadata fields which are only available in a specific Confluence space, will show the space name in brackets.
   To filter for a metadataset, first type and select "Metadataset", then enter the desired set, equivalent to 3.
3. After selecting a metadata field, enter the metadata field value(s) you are looking for or select them from the suggestions (if available).
4. Repeat step 2 to 4 until you have added all desired filters.

Image 1: Add Metadata Field Filters in Confluence Search

Search results will now show all Confluence pages whose metadata match the configured filters.

Added filters will work as if connected with an AND operator. Meaning: When using the filter option, it is not possible e.g. to search for pages that match either filter criteria 1 or filter criteria 2. To build more complex search queries, refer to the next section: Using Lucene Search Syntax in Confluence Search.

CQL search is also used for the Metadata Overview macro and (to some extent) the Display Metadata macro.

Using Lucene Search Syntax in Confluence Search

As mentioned in the introduction, you may use Lucene search syntax to search for metadata in the Confluence search. If you enter such a term in the Confluence search, the search results will show all Confluence pages whose metadata match the entered criteria.

In the next section you will find instructions to build basic search terms according to Lucene search syntax. The section Examples for syntax of Expert Filter Criteria shows more complex search queries, which will also work in the Confluence search (provided you configured your metadata accordingly).

Back to Top

Search Terms Based on Lucene Search Syntax

Search queries according to the Lucene search syntax necessitate knowing the keys of metadata sets and fields. Basic search queries look as follows:

//search for space set
metadataset:KEY_OF_METADATASET

//search for space field
metadatafield:KEY_OF_METADATAFIELD

//search for metadata value for a space metadata field
KEY_OF_METADATAFIELD:VALUE_OF_METADATAFIELD

//search for global set
global.metadataset:KEY_OF_METADATASET

//search for global field
global.metadatafield:KEY_OF_METADATAFIELD

//search for metadata value for a global metadata field
KEY_OF_METADATAFIELD:VALUE_OF_METADATAFIELD

However, you do not have to guess the correct name. The following section describes how to determine the keys of metadata sets/fields.

Determining the Key of a Metadata Set/Field 

As a User

Confluence users can determine the key of metadata fields or sets by moving their mouse over the metadata set or field title within the metadata overview.

Image 1: Metadata Set Key (click to enlarge)

To display the key, go to a page where the metadata field or set has been added. Open the metadata overview by clicking the colorful Metadata icon at the top-left. Now hover your mouse over the metadata set (displayed at the top) or the metadata field (entries below) whose key you want to know. A small tooltip containing the respective key will be shown.

If you cannot find the metadata field, check if you have selected the correct metadata set.

As a Space Administrator

As a Space Administrator, you can additionally go to a page and open "Space tools" > "Metadata". To find the correct metadata field key, click the tab "Metadata fields" or open the tab "Metadata sets", respectively. 

Space metadata fields are displayed at the top, global metadata fields at the bottom.

Image 2: Metadata Field Keys (click to enlarge)   

 Back to Top

Troubleshooting

When entering keys of metadata fields or sets in a macro or the Confluence search, make sure:

• There are no spaces
• They are written completely in lower case
• Words are only divided by "." (full stop) or ":" (colon) respectively, if you are searching.

Examples for syntax of Expert Filter Criteria 

Expert Filter Criteria are based on the Lucene search syntax. They are available in the Metadata Overview macro and the Confluence search.

Basic search terms with Lucene search syntax are explained at the beginning of this section. Find more complex examples below.

1) Show the metadata of all pages where the location (a space metadata field) is either "Stuttgart" or "Dresden":

// Expert Filter Criteria 
metadatafield.location:Stuttgart OR metadatafield.location:Dresden

2) Show the metadata of all pages where the contact person (a global metadata field) is Katherine Smith and the location (a space metadata field) is "Dresden":

// Expert Filter Criteria 
global.metadatafield.contactperson:ksmith AND metadatafield.location:Dresden

3) Show all pages with the metadata set "projects" in the space "Products" (with space key "PROD")

// Expert Filter Criteria 
metadataset:metadataset.projects AND spacekey:PROD

Back to Top