Package org.apache.lucene.search.grouping

Class GroupingSearch

  • public class GroupingSearch
extends Object
    Convenience class to perform grouping in a non distributed environment.
    WARNING: This API is experimental and might change in incompatible ways in the next release.

    • Constructor Detail

      • GroupingSearch

        public GroupingSearch​(String groupField)
        Constructs a GroupingSearch instance that groups documents by index terms using DocValues. The group field can only have one token per document. This means that the field must not be analysed.
        Parameters:
        groupField - The name of the field to group by.

      • GroupingSearch

        public GroupingSearch​(GroupSelector<?> groupSelector)
        Constructs a GroupingSearch instance that groups documents using a GroupSelector
        Parameters:
        groupSelector - a GroupSelector that defines groups for this GroupingSearch

      • GroupingSearch

        public GroupingSearch​(ValueSource groupFunction,
                      Map<Object,​Object> valueSourceContext)
        Constructs a GroupingSearch instance that groups documents by function using a ValueSource instance.
        Parameters:
        groupFunction - The function to group by specified as ValueSource
        valueSourceContext - The context of the specified groupFunction

      • GroupingSearch

        public GroupingSearch​(Query groupEndDocs)
        Constructor for grouping documents by doc block. This constructor can only be used when documents belonging in a group are indexed in one block.
        Parameters:
        groupEndDocs - The query that marks the last document in all doc blocks

    • Method Detail

      • search

        public <T> TopGroups<T> search​(IndexSearcher searcher,
                               Query query,
                               int groupOffset,
                               int groupLimit)
                        throws IOException
        Executes a grouped search. Both the first pass and second pass are executed on the specified searcher.
        Parameters:
        searcher - The IndexSearcher instance to execute the grouped search on.
        query - The query to execute with the grouping
        groupOffset - The group offset
        groupLimit - The number of groups to return from the specified group offset
        Returns:
        the grouped result as a TopGroups instance
        Throws:
        IOException - If any I/O related errors occur

      • setCachingInMB

        public GroupingSearch setCachingInMB​(double maxCacheRAMMB,
                                     boolean cacheScores)
        Enables caching for the second pass search. The cache will not grow over a specified limit in MB. The cache is filled during the first pass searched and then replayed during the second pass searched. If the cache grows beyond the specified limit, then the cache is purged and not used in the second pass search.
        Parameters:
        maxCacheRAMMB - The maximum amount in MB the cache is allowed to hold
        cacheScores - Whether to cache the scores
        Returns:
        this

      • setCaching

        public GroupingSearch setCaching​(int maxDocsToCache,
                                 boolean cacheScores)
        Enables caching for the second pass search. The cache will not contain more than the maximum specified documents. The cache is filled during the first pass searched and then replayed during the second pass searched. If the cache grows beyond the specified limit, then the cache is purged and not used in the second pass search.
        Parameters:
        maxDocsToCache - The maximum number of documents the cache is allowed to hold
        cacheScores - Whether to cache the scores
        Returns:
        this

      • disableCaching

        public GroupingSearch disableCaching()
        Disables any enabled cache.
        Returns:
        this

      • setGroupSort

        public GroupingSearch setGroupSort​(Sort groupSort)
        Specifies how groups are sorted. Defaults to Sort.RELEVANCE.
        Parameters:
        groupSort - The sort for the groups.
        Returns:
        this

      • setSortWithinGroup

        public GroupingSearch setSortWithinGroup​(Sort sortWithinGroup)
        Specified how documents inside a group are sorted. Defaults to Sort.RELEVANCE.
        Parameters:
        sortWithinGroup - The sort for documents inside a group
        Returns:
        this

      • setGroupDocsOffset

        public GroupingSearch setGroupDocsOffset​(int groupDocsOffset)
        Specifies the offset for documents inside a group.
        Parameters:
        groupDocsOffset - The offset for documents inside a
        Returns:
        this

      • setGroupDocsLimit

        public GroupingSearch setGroupDocsLimit​(int groupDocsLimit)
        Specifies the number of documents to return inside a group from the specified groupDocsOffset.
        Parameters:
        groupDocsLimit - The number of documents to return inside a group
        Returns:
        this

      • setIncludeMaxScore

        public GroupingSearch setIncludeMaxScore​(boolean includeMaxScore)
        Whether to include the score of the most relevant document per group.
        Parameters:
        includeMaxScore - Whether to include the score of the most relevant document per group
        Returns:
        this

      • setAllGroups

        public GroupingSearch setAllGroups​(boolean allGroups)
        Whether to also compute all groups matching the query. This can be used to determine the number of groups, which can be used for accurate pagination.

        When grouping by doc block the number of groups are automatically included in the TopGroups and this option doesn't have any influence.

        Parameters:
        allGroups - to also compute all groups matching the query
        Returns:
        this

      • getAllMatchingGroups

        public <T> Collection<T> getAllMatchingGroups()
        If setAllGroups(boolean) was set to true then all matching groups are returned, otherwise an empty collection is returned.
        Type Parameters:
        T - The group value type. This can be a BytesRef or a MutableValue instance. If grouping by doc block this the group value is always null.
        Returns:
        all matching groups are returned, or an empty collection

      • setAllGroupHeads

        public GroupingSearch setAllGroupHeads​(boolean allGroupHeads)
        Whether to compute all group heads (most relevant document per group) matching the query.

        This feature isn't enabled when grouping by doc block.

        Parameters:
        allGroupHeads - Whether to compute all group heads (most relevant document per group) matching the query
        Returns:
        this