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 labelled 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.
SearchQuery query = BooleanQuery.composeAndQuery(new LabelQuery("administration"), new InSpaceQuery("DOC"));
SearchSort sort = new ModifiedSort(SearchSort.Order.DESCENDING); // latest modified content first
SearchFilter securityFilter = SiteSearchPermissionsSearchFilter.getInstance();
ResultFilter resultFilter = new SubsetResultFilter(10);

Search search = new Search(query, sort, securityFilter, resultFilter);

SearchResults searchResults;
	searchResults =;
catch (InvalidSearchException e)
	// discard search and assign empty results
	searchResults = LuceneSearchResults.EMPTY_RESULTS;

// iterating over search results
for (SearchResult searchResult : searchResults.getAll())
    System.out.println("Title: " + searchResult.getDisplayTitle());
    System.out.println("Content: " + searchResult.getContent());
    System.out.println("SpaceKey: " + searchResult.getSpaceKey());

// total number of results found
System.out.println("Total number of results: " + searchResults.getUnfilteredResultsCount());

Further comments:

  • (warning) 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 has been limited with the use of This class efficiently filters search results during search time.
  • The search is executed using This invocation returns search results populated with data from your index.
    • 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().
    • Common information about a search result like title, body and space key can be extracted 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 com.atlassian.bonnie.Searchable objects from the database to be returned by the search, call searchManager.searchEntities(search) instead.
  • An exception is thrown when either:
    • there is an error mapping a v2 search object to the corresponding Lucene search object, or
    • no mapper could be found to map one of the search objects. (The mapper plugin responsible for mapping this search may have been uninstalled.)
  • You should simply discard the search if an exception is thrown as described above.

Was this page helpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport