Last updated May 22, 2024

Searching using the v2 search API

The v2 search API provides a fast way of searching content within Confluence. We highly recommend that all plugin authors switch to this API where possible.

To illustrate how to use this API, we have included a simple code snippet for a basic search that:

  • searches for all content labeled with administration in the space with key DOC.
  • sorts these results with the latest modified content displayed first.
  • limits the number of results to 10.
public class V2SearchExample {

    private SearchManager searchManager;

    public V2SearchExample(SearchManager searchManager) {
        this.searchManager = searchManager;

    public void search() {    
        SearchQuery query = BooleanQuery.andQuery(new LabelQuery("administration"), new InSpaceQuery("DOC"));
        SearchSort sort = new ModifiedSort(SearchSort.Order.DESCENDING); // latest modified content first
        SearchFilter searchFilter = SiteSearchPermissionsSearchFilter.getInstance();
        ContentSearch search = new ContentSearch(query, sort, searchFilter, 0, 10);
        SearchResults searchResults;
        try {
            searchResults =;
        } catch (InvalidSearchException e) {
            // discard search and assign empty results
            searchResults = new DefaultSearchResults(Collections.emptyList(), 0);

        for (SearchResult searchResult : searchResults.getAll()) {
            System.out.println("Title: " + searchResult.getDisplayTitle());
            System.out.println("Content: " + searchResult.getContent());
            System.out.println("SpaceKey: " + searchResult.getSpaceKey());
        System.out.println("Total number of results: " + searchResults.getUnfilteredResultsCount());

Further comments:

  • Please ensure you include in your search. This is a bundled filter that will handle permission checking and content filtering automatically for you.
  • The number of results returned is limited to 10 and starting offset is set to 0 using ContentSearch parameters.
  • The search runs using This invocation returns search results populated with data from the index targeted by the search.
    • ContentSearch and ChangesSearch will target the content and change indexes respectively. Any other implementations of ISearch passed to the searchManager should return which search index to target via search.getSearchIndexes().
    • It is not recommended to target multiple indexes in a single search. This is only supported for compatibility reasons and is orders of magnitude less performant than searching each index independently.
    • To iterate over the search results returned, you can get a reference to the list of search results with searchResults.getAll() or an iterator to this list using searchResults.iterator().
    • You can extract common information about a search result like title, body, and space key from the search result using getDisplayTitle(), getContent(), and getSpaceKey() respectively. For more accessors, see the API documentation for
    • This invocation does not go to the database to construct any search results. If you want the search to return com.atlassian.bonnie.Searchable objects from the database, call searchManager.searchEntities(search) instead.
  • An exception is thrown in one of the following variants:
    • There is an error mapping a v2 search object to the corresponding Lucene search object.
    • No mapper could be found to map one of the search objects. (The mapper plugin responsible for mapping this search may have been uninstalled.)
  • If an exception is thrown as described above, you should simply discard the search.

Rate this page: