com.atlassian.jira.issue.search

Interface SearchProvider

All Known Implementing Classes:

LuceneSearchProvider

public interface SearchProvider

SearchProvider allows running advanced searches against the Jira Lucene Issue index as opposed to database (SQL) based queries. If possible, it is recommended to use SearchService instead, which is part of jira-api and is decoupled from the Lucene library. Use SearchProvider if you need to

• optimize performance by loading only a limited number of fields with fieldsToLoad
• restrict results beyond query by setting additional Lucene query
• [advanced use] collect all results by providing a Collector

See Also:

SearchService}

Method Summary

Modifier and Type	Method and Description
long	getHitCount(SearchQuery query) Return the number of documents that match the query
long	getHitCount(SearchQuery query, Long timeout) Return the number of documents that match the query
void	search(SearchQuery query, org.apache.lucene.search.Collector collector) Run a search against the Issue index with the collector called for each document that matches the query.
SearchResults<DocumentWithId>	search(SearchQuery query, PagerFilter pager) Run a search against the Issue index, loading all fields for each document.
SearchResults<DocumentWithId>	search(SearchQuery query, PagerFilter pager, Set<String> fieldsToLoad) Run a search against the Issue index, loading only a restricted subset of fields for each document.

Method Detail

search

SearchResults<DocumentWithId> search(SearchQuery query,
                                     PagerFilter pager,
                                     Set<String> fieldsToLoad)
                              throws SearchException

Run a search against the Issue index, loading only a restricted subset of fields for each document.

Results ordering

Results are sorted according to Query.getOrderByClause() and Lucene scoring.

Parameters:

query - Query to define which Lucene documents should be returned.

pager - PagerFilter to restrict the portion of documents matching the query that will be returned.

fieldsToLoad - Set of fields that should be loaded. Only these fields will be available in the returned document. Empty set means only document id will be loaded.

Returns:

SearchResults with Lucene documents (and their internal ids) with only specific fields loaded

Throws:

SearchException

See Also:

DocumentWithId

search

SearchResults<DocumentWithId> search(SearchQuery query,
                                     PagerFilter pager)
                              throws SearchException

Run a search against the Issue index, loading all fields for each document. If possible, use the more performant method search(SearchQuery, PagerFilter, Set), loading only a subset of fields.

Results ordering

Results are sorted according to Query.getOrderByClause() and Lucene scoring.

Parameters:

query - Query to define which Lucene documents should be returned.

pager - PagerFilter to restrict the portion of documents matching the query that will be returned.

Returns:

SearchResults with Lucene documents (and their internal ids) with all fields loaded

Throws:

SearchException

See Also:

DocumentWithId

getHitCount

long getHitCount(SearchQuery query)
          throws SearchException

Return the number of documents that match the query

Parameters:

query - Query to define which Lucene documents should be counted.

Returns:

Throws:

SearchException

getHitCount

long getHitCount(SearchQuery query,
                 Long timeout)
          throws SearchException

Return the number of documents that match the query

Parameters:

query - Query to define which Lucene documents should be counted.

timeout - Query timeout in milliseconds

Returns:

Throws:

SearchException

search

void search(SearchQuery query,
            org.apache.lucene.search.Collector collector)
     throws SearchException

Run a search against the Issue index with the collector called for each document that matches the query.

Results ordering

This method disrespects sorting from Query.getOrderByClause(). The collector will be called according to Lucene's internal index structure. The docIds passed to LeafCollector.collect(int) are in order that is safe to be used with DocValuesIterator.advanceExact(int) method.

Performance

This method offers the best performance when processing all data. As opposed to search(SearchQuery, PagerFilter) and search(SearchQuery, PagerFilter, Set), it does not load all returned documents into the memory at once. For each result it calls LeafCollector.collect(int) with the document id and leaves it up to the Collector implementation to decide what to do: load all or only specific fields, save just the document id, or ignore the given id completely.

Throws:

SearchException