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.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
@Named
public class V2SearchExample {

    @ConfluenceImport
    private SearchManager searchManager;

    @Inject
    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 = searchManager.search(search);
        } 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 com.atlassian.confluence.search.v2.searchfilter.SiteSearchPermissionsSearchFilter 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 searchManager.search(search). 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 com.atlassian.confluence.search.v2.SearchResult.
- 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 com.atlassian.confluence.search.v2.InvalidSearchException 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.

See the Java API Reference page for more information.

Searching using the v2 search API

Related topics