Last updated Apr 25, 2024

Search extensions

What are search extensions?

A Search extension assigns custom properties to Confluence content and enables search filtering using those properties. In the REST API, they allow you to write Confluence Query Language (CQL) queries on content using your custom properties as terms.

What can I build with search extensions?

Search extensions allow you to build apps with powerful filtering capabilities for content.

For example, search extensions could be used to create:

An app that ranks each page in Confluence and allows the user to search for only highly ranked pages.
An app that intelligently categorizes pages and allows search filtering on this category.

Extend the search API with content properties

By storing properties against a piece of content and declaring them as indexable by the Confluence search, you can write CQL queries that use them as terms.

For example, if you decide to save a 'last viewed date' on every page, you can then use CQL to query the Content API for all pages viewed in the past week, month, or year.

This might look like:

1
2
type = page and lastViewedDate > now(-7d)

Custom search and macro filters

Filtering content by querying the REST API as a developer is useful, but we should also make filtering possible for end users. With [UI support], you can use your content properties to add powerful search filters to macros that aggregate and display content, like the content by label macro. As well as macros, your filters will also appear in the search screen, allowing users to refine their search queries.

custom search and macro filters

Filter your search results by a custom property set on the content

How do I build search extensions?

Content properties are key-value pairs stored on a page or blog post in Confluence. To get started with search extensions, you'll need to use the REST API to store content properties (which must be valid JSON) against a piece of content.

To integrate with search, you'll need to define some extractions to declare the fields and nested data you want to be indexable by Confluence. You'll also want to define an alias for simpler CQL querying, and UI support for your fields to be filterable by users on the search screen. You can declare both of these in your atlassian-connect.json file.

What other patterns might be helpful?

Page extensions

Page extensions may also provide another useful way of surfacing metadata related to a page.

Let's do this!

Get going by following our Getting started tutorial and referring to related documentation listed on the right hand side of this page.

Integrations