Versions Compared

Old Version 19

changes.mady.by.user Ronny Winkler

Saved on

compared with

New Version Current

changes.mady.by.user Enrico Kutscher

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Introduction
Anchor
top
top

Except when filtering via "Expert Filter Criteria (Lucene)", Metadata uses Confluence Query Language (CQL) in all of its features. The filtering via "Expert Filter Criteria (Lucene)" is as the name suggests based on Lucene, however, this feature is deprecated.

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:

Table of Contents
minLevel2
outlinetrue
excludeOther Versions|Introduction
stylenone

Metadata in Confluence Search and Metadata Macros

Status
colourGreen
titleSince version 2.0
Status
colourRed
titleSince Confluence 5.9

Filtering Confluence Search Results (CQL)
Anchor
cql
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.
    (info) Metadata fields which are only available in a specific Confluence space, will show the space name in brackets.
  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

(info) To filter for a Metadata set, follow the above steps but type and select "Metadataset" in step 2. Afterwards choose from the available sets.


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

Info

Added filters will work as if connected with an AND operator. Meaning: When using the filter option, it is not possible to for example 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 Confluence Query Language (CQL) Syntax in Macros (Expert Filter Criteria).

CQL search via the "Add a filter" features is also available in the Metadata Overview and Content by Metadata macros. In addition it is also supported by some for the Confluence default macros like "Content by label".

Using Confluence Query Language (CQL) Syntax in Macros (Expert Filter Criteria)
Anchor
expertcqlsearch
expertcqlsearch

Status
colourGreen
titleSince version 3.0.4

The macros Macro "Metadata Overview" (v 3.3) and Macro "Content by Metadata" (v 3.3) provide an option "Expert filter criteria (CQL)". This input field accepts a search query in the Confluence Query Language (CQL).

A general description on how to search with CQL can be found in the official Confluence advanced searching documentation.

To integrate a condition into a CQL query which restricts the results to content with Metadata please refer to the table below. There you'll find some examples for the different use cases in the correct syntax.

Searching for metadata sets

For global sets

metadataset = "global.metadataset.mytestset"

For space sets (SPACEKEY refers to the key of the space)

metadataset = "metadataset.mytestset" AND space = "SPACEKEY"

Searching for a metadata field value

For global metadata fields

global.metadatafield.mytestfield= "value"

For space metadata fields (SPACEKEY refers to the key of the space)

SPACEKEY.metadatafield.mytestfield= "value"

For space metadata fields in a space whose key starts with a number like the space key '123test' (SPACEKEY refers to the key of the space)

space_SPACEKEY.metadatafield.mytestfield= "value"

For space metadata fields in the personal space of a user. Let's say the personal space of John has the space key '~john', then the CQL condition would look like:

p_space_john.metadatafield.mytestfield= "value"

Example queries for the Expert filter criteria (CQL) option

Insert excerpt
Examples for CQL expert filter criteria (v 3.3)
Examples for CQL expert filter criteria (v 3.3)
nopaneltrue


Back to Top

Determining the Key of a Metadata Set/Field 
Anchor
determinekey
determinekey

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

Note

For the following steps, you need Space Administrator permissions.

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 Back to Top

Status
colourYellow
titledeprecated
 Using Lucene Search Syntax in Confluence Search
Anchor
lucenesearch
lucenesearch

Note: This feature is deprecated and will be removed in one of the future releases. Please use use Confluence Query Language instead.

Expand

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).


Anchor
keys
keys

Search Terms Based on Lucene Search Syntax

Status
colourGreen
titlesince version 3.0

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

Field TypeSyntaxExample
Multi Select

fieldkey:"_value_"

fieldkey:_value_

fieldkey:_val*

metadatafield.multiselect:"_option_"

metadatafield.multiselect:_option_

metadatafield.multiselect:_opt*

metadatafield.multiselect:"_splitted_option_"

metadatafield.multiselect:"_option1_" AND metadatafield.multiselect:_option2_

Date

fieldkey:"yyyyMMdd"

fieldkey:yyyyMMdd

metadatafield.date:"20170830"

metadatafield.date:20170830

metadatafield.date:201708*

Single Select (Dropdown)

fieldkey:"_value_"

fieldkey:_value_

fieldkey:_val*

metadatafield.dropdown:"_option_"

metadatafield.dropdown:_option_

metadatafield.dropdown:_opt*

metadatafield.dropdown:"_splitted_option_"

Groupfieldkey:"_subname1 _subname2" AND fieldkey:"_group2"

metadatafield.group:"_groupname"

metadatafield.group:_groupname

metadatafield.group:"_groupsubname1 _groupsubname2"

Link

fieldkey:"pageId"

fieldkey:pageId

fieldkey:"url"

fieldkey:"_alternativetitle"

metadatafield.link:"123456"

metadatafield.link:123456

metadatafield.link:"http://www.communardo.de"

metadatafield.link:"_alternativetitle"

metadatafield.link:_alternativetitle

metadatafield.link:_alt*

metadatafield.link:"_title _with _subtitle"

Single Select (Radio Buttons)

fieldkey:"_value_"

fieldkey:_value_

fieldkey:_val*

metadatafield.radiobutton:"_option_"

metadatafield.radiobutton:_option_

metadatafield.radiobutton:_opt*

metadatafield.radiobutton:"_splitted_option_"

Textfieldkey:"value"metadatafield.text:"any text"
User

fieldkey:"username"

fieldkey:username

metadatafield.user:"communardoworker"

metadatafield.user:communardoworker

The examples above would be space metadata fields. Global fields start with global.metadatafield.name.

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

Note

When entering specific field values in your search, you have to take the following changes into account:

  • ü → ue
  • ä → ae
  • ö → oe


Examples for Syntax of Lucene Expert Filter Criteria 
Anchor
examplesfilter
examplesfilter

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 all pages where the location (a space metadata field) is either "Stuttgart" or "Dresden":

Code Block
// Expert Filter Criteria 
metadatafield.location:"Stuttgart" OR metadatafield.location:"Dresden"

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

Code Block
// 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")

Code Block
// Expert Filter Criteria 
metadataset:metadataset.projects AND spacekey:"PROD"


Back to Top

Include Page
_Version Switch
_Version Switch