Class GroupingSearch

Convenience class to perform grouping in a non distributed environment.

Note

This API is experimental and might change in incompatible ways in the next release.

Inheritance

System.Object

GroupingSearch

Inherited Members

System.Object.Equals(System.Object)

System.Object.Equals(System.Object, System.Object)

System.Object.GetHashCode()

System.Object.GetType()

System.Object.MemberwiseClone()

System.Object.ReferenceEquals(System.Object, System.Object)

System.Object.ToString()

Namespace: Lucene.Net.Search.Grouping

Assembly: Lucene.Net.Grouping.dll

Syntax

public class GroupingSearch

Constructors

GroupingSearch(ValueSource, IDictionary)

Constructs a GroupingSearch instance that groups documents by function using a Lucene.Net.Queries.Function.ValueSource instance.

Declaration

public GroupingSearch(ValueSource groupFunction, IDictionary valueSourceContext)

Parameters

Type	Name	Description
Lucene.Net.Queries.Function.ValueSource	groupFunction	The function to group by specified as Lucene.Net.Queries.Function.ValueSource
System.Collections.IDictionary	valueSourceContext	The context of the specified groupFunction

GroupingSearch(Filter)

Constructor for grouping documents by doc block. This constructor can only be used when documents belonging in a group are indexed in one block.

Declaration

public GroupingSearch(Filter groupEndDocs)

Parameters

Type	Name	Description
Lucene.Net.Search.Filter	groupEndDocs	The filter that marks the last document in all doc blocks

GroupingSearch(String)

Constructs a GroupingSearch instance that groups documents by index terms using the Lucene.Net.Search.FieldCache. The group field can only have one token per document. This means that the field must not be analysed.

Declaration

public GroupingSearch(string groupField)

Parameters

Type	Name	Description
System.String	groupField	The name of the field to group by.

Methods

DisableCaching()

Disables any enabled cache.

Declaration

public virtual GroupingSearch DisableCaching()

Returns

Type	Description
GroupingSearch	this

GetAllGroupHeads()

Returns the matching group heads if SetAllGroupHeads(Boolean) was set to true or an empty bit set.

Declaration

public virtual IBits GetAllGroupHeads()

Returns

Type	Description
Lucene.Net.Util.IBits	The matching group heads if SetAllGroupHeads(Boolean) was set to true or an empty bit set

GetAllMatchingGroups()

If SetAllGroups(Boolean) was set to true then all matching groups are returned, otherwise an empty collection is returned.

Declaration

public virtual ICollection GetAllMatchingGroups()

Returns

Type	Description
System.Collections.ICollection	all matching groups are returned, or an empty collection

Remarks

LUCENENET specific used to get the groups if the type is unknown or if the code expects any type, since GetAllMatchingGroups<T>() will throw an exception if the return type is incorrect.

GetAllMatchingGroups<T>()

If SetAllGroups(Boolean) was set to true then all matching groups are returned, otherwise an empty collection is returned.

Declaration

public virtual ICollection<T> GetAllMatchingGroups<T>()

Returns

Type	Description
System.Collections.Generic.ICollection<T>	all matching groups are returned, or an empty collection

Type Parameters

Name	Description
T	The group value type. This can be a Lucene.Net.Util.BytesRef or a Lucene.Net.Util.Mutable.MutableValue instance. If grouping by doc block this the group value is always null.

GroupByDocBlock<TGroupValue>(IndexSearcher, Filter, Query, Int32, Int32)

Declaration

protected virtual ITopGroups<TGroupValue> GroupByDocBlock<TGroupValue>(IndexSearcher searcher, Filter filter, Query query, int groupOffset, int groupLimit)

Parameters

Type	Name	Description
Lucene.Net.Search.IndexSearcher	searcher
Lucene.Net.Search.Filter	filter
Lucene.Net.Search.Query	query
System.Int32	groupOffset
System.Int32	groupLimit

Returns

Type	Description
ITopGroups<TGroupValue>

Type Parameters

Name	Description
TGroupValue

GroupByField<TGroupValue>(IndexSearcher, Filter, Query, Int32, Int32)

Declaration

protected virtual ITopGroups<TGroupValue> GroupByField<TGroupValue>(IndexSearcher searcher, Filter filter, Query query, int groupOffset, int groupLimit)

Parameters

Type	Name	Description
Lucene.Net.Search.IndexSearcher	searcher
Lucene.Net.Search.Filter	filter
Lucene.Net.Search.Query	query
System.Int32	groupOffset
System.Int32	groupLimit

Returns

Type	Description
ITopGroups<TGroupValue>

Type Parameters

Name	Description
TGroupValue

GroupByFunction<TMutableValue>(IndexSearcher, Filter, Query, Int32, Int32)

Declaration

protected virtual ITopGroups<TMutableValue> GroupByFunction<TMutableValue>(IndexSearcher searcher, Filter filter, Query query, int groupOffset, int groupLimit)
    where TMutableValue : MutableValue

Parameters

Type	Name	Description
Lucene.Net.Search.IndexSearcher	searcher
Lucene.Net.Search.Filter	filter
Lucene.Net.Search.Query	query
System.Int32	groupOffset
System.Int32	groupLimit

Returns

Type	Description
ITopGroups<TMutableValue>

Type Parameters

Name	Description
TMutableValue

Search(IndexSearcher, Filter, Query, Int32, Int32)

Executes a grouped search. Both the first pass and second pass are executed on the specified searcher.

Declaration

public virtual ITopGroups<object> Search(IndexSearcher searcher, Filter filter, Query query, int groupOffset, int groupLimit)

Parameters

Type	Name	Description
Lucene.Net.Search.IndexSearcher	searcher	The Lucene.Net.Search.IndexSearcher instance to execute the grouped search on.
Lucene.Net.Search.Filter	filter	The filter to execute with the grouping
Lucene.Net.Search.Query	query	The query to execute with the grouping
System.Int32	groupOffset	The group offset
System.Int32	groupLimit	The number of groups to return from the specified group offset

Returns

Type	Description
ITopGroups<System.Object>	the grouped result as a ITopGroups<TGroupValue> instance

Exceptions

Type	Condition
System.IO.IOException	If any I/O related errors occur

Search(IndexSearcher, Query, Int32, Int32)

Executes a grouped search. Both the first pass and second pass are executed on the specified searcher.

Declaration

public virtual ITopGroups<object> Search(IndexSearcher searcher, Query query, int groupOffset, int groupLimit)

Parameters

Type	Name	Description
Lucene.Net.Search.IndexSearcher	searcher	The Lucene.Net.Search.IndexSearcher instance to execute the grouped search on.
Lucene.Net.Search.Query	query	The query to execute with the grouping
System.Int32	groupOffset	The group offset
System.Int32	groupLimit	The number of groups to return from the specified group offset

Returns

Type	Description
ITopGroups<System.Object>	the grouped result as a ITopGroups<TGroupValue> instance

Exceptions

Type	Condition
System.IO.IOException	If any I/O related errors occur

Search<TGroupValue>(IndexSearcher, Filter, Query, Int32, Int32)

Executes a grouped search. Both the first pass and second pass are executed on the specified searcher.

Declaration

public virtual ITopGroups<TGroupValue> Search<TGroupValue>(IndexSearcher searcher, Filter filter, Query query, int groupOffset, int groupLimit)

Parameters

Type	Name	Description
Lucene.Net.Search.IndexSearcher	searcher	The Lucene.Net.Search.IndexSearcher instance to execute the grouped search on.
Lucene.Net.Search.Filter	filter	The filter to execute with the grouping
Lucene.Net.Search.Query	query	The query to execute with the grouping
System.Int32	groupOffset	The group offset
System.Int32	groupLimit	The number of groups to return from the specified group offset

Returns

Type	Description
ITopGroups<TGroupValue>	the grouped result as a ITopGroups<TGroupValue> instance

Type Parameters

Name	Description
TGroupValue	The expected return type of the search.

Exceptions

Type	Condition
System.IO.IOException	If any I/O related errors occur

Search<TGroupValue>(IndexSearcher, Query, Int32, Int32)

Executes a grouped search. Both the first pass and second pass are executed on the specified searcher.

Declaration

public virtual ITopGroups<TGroupValue> Search<TGroupValue>(IndexSearcher searcher, Query query, int groupOffset, int groupLimit)

Parameters

Type	Name	Description
Lucene.Net.Search.IndexSearcher	searcher	The Lucene.Net.Search.IndexSearcher instance to execute the grouped search on.
Lucene.Net.Search.Query	query	The query to execute with the grouping
System.Int32	groupOffset	The group offset
System.Int32	groupLimit	The number of groups to return from the specified group offset

Returns

Type	Description
ITopGroups<TGroupValue>	the grouped result as a ITopGroups<TGroupValue> instance

Type Parameters

Name	Description
TGroupValue	The expected return type of the search.

Exceptions

Type	Condition
System.IO.IOException	If any I/O related errors occur

SearchByField(IndexSearcher, Filter, Query, Int32, Int32)

Executes a grouped search base on the field specified via the constructor. Both the first pass and second pass are executed on the specified searcher.

Declaration

public virtual ITopGroups<BytesRef> SearchByField(IndexSearcher searcher, Filter filter, Query query, int groupOffset, int groupLimit)

Parameters

Type	Name	Description
Lucene.Net.Search.IndexSearcher	searcher	The Lucene.Net.Search.IndexSearcher instance to execute the grouped search on.
Lucene.Net.Search.Filter	filter	The filter to execute with the grouping
Lucene.Net.Search.Query	query	The query to execute with the grouping
System.Int32	groupOffset	The group offset
System.Int32	groupLimit	The number of groups to return from the specified group offset

Returns

Type	Description
ITopGroups<Lucene.Net.Util.BytesRef>	the grouped result as a ITopGroups<TGroupValue> instance

Exceptions

Type	Condition
System.IO.IOException	If any I/O related errors occur

SearchByField(IndexSearcher, Query, Int32, Int32)

Executes a grouped search base on the field specified via the constructor. Both the first pass and second pass are executed on the specified searcher.

Declaration

public virtual ITopGroups<BytesRef> SearchByField(IndexSearcher searcher, Query query, int groupOffset, int groupLimit)

Parameters

Type	Name	Description
Lucene.Net.Search.IndexSearcher	searcher	The Lucene.Net.Search.IndexSearcher instance to execute the grouped search on.
Lucene.Net.Search.Query	query	The query to execute with the grouping
System.Int32	groupOffset	The group offset
System.Int32	groupLimit	The number of groups to return from the specified group offset

Returns

Type	Description
ITopGroups<Lucene.Net.Util.BytesRef>	the grouped result as a ITopGroups<TGroupValue> instance

Exceptions

Type	Condition
System.IO.IOException	If any I/O related errors occur

SearchByFunction<TMutableValue>(IndexSearcher, Filter, Query, Int32, Int32)

Executes a grouped search base on the function specified by a Lucene.Net.Queries.Function.ValueSource passed via the constructor. Both the first pass and second pass are executed on the specified searcher.

Declaration

public virtual ITopGroups<TMutableValue> SearchByFunction<TMutableValue>(IndexSearcher searcher, Filter filter, Query query, int groupOffset, int groupLimit)
    where TMutableValue : MutableValue

Parameters

Type	Name	Description
Lucene.Net.Search.IndexSearcher	searcher	The Lucene.Net.Search.IndexSearcher instance to execute the grouped search on.
Lucene.Net.Search.Filter	filter	The filter to execute with the grouping
Lucene.Net.Search.Query	query	The query to execute with the grouping
System.Int32	groupOffset	The group offset
System.Int32	groupLimit	The number of groups to return from the specified group offset

Returns

Type	Description
ITopGroups<TMutableValue>	the grouped result as a ITopGroups<TGroupValue> instance

Type Parameters

Name	Description
TMutableValue

Exceptions

Type	Condition
System.IO.IOException	If any I/O related errors occur

SearchByFunction<TMutableValue>(IndexSearcher, Query, Int32, Int32)

Executes a grouped search base on the function specified by a Lucene.Net.Queries.Function.ValueSource passed via the constructor. Both the first pass and second pass are executed on the specified searcher.

Declaration

public virtual ITopGroups<TMutableValue> SearchByFunction<TMutableValue>(IndexSearcher searcher, Query query, int groupOffset, int groupLimit)
    where TMutableValue : MutableValue

Parameters

Type	Name	Description
Lucene.Net.Search.IndexSearcher	searcher	The Lucene.Net.Search.IndexSearcher instance to execute the grouped search on.
Lucene.Net.Search.Query	query	The query to execute with the grouping
System.Int32	groupOffset	The group offset
System.Int32	groupLimit	The number of groups to return from the specified group offset

Returns

Type	Description
ITopGroups<TMutableValue>	the grouped result as a ITopGroups<TGroupValue> instance

Type Parameters

Name	Description
TMutableValue

Exceptions

Type	Condition
System.IO.IOException	If any I/O related errors occur

SetAllGroupHeads(Boolean)

Whether to compute all group heads (most relevant document per group) matching the query.

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

Declaration

public virtual GroupingSearch SetAllGroupHeads(bool allGroupHeads)

Parameters

Type	Name	Description
System.Boolean	allGroupHeads	Whether to compute all group heads (most relevant document per group) matching the query

Returns

Type	Description
GroupingSearch	this

SetAllGroups(Boolean)

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.

Declaration

public virtual GroupingSearch SetAllGroups(bool allGroups)

Parameters

Type	Name	Description
System.Boolean	allGroups	to also compute all groups matching the query

Returns

Type	Description
GroupingSearch	this

SetCaching(Int32, Boolean)

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.

Declaration

public virtual GroupingSearch SetCaching(int maxDocsToCache, bool cacheScores)

Parameters

Type	Name	Description
System.Int32	maxDocsToCache	The maximum number of documents the cache is allowed to hold
System.Boolean	cacheScores	Whether to cache the scores

Returns

Type	Description
GroupingSearch	this

SetCachingInMB(Double, Boolean)

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.

Declaration

public virtual GroupingSearch SetCachingInMB(double maxCacheRAMMB, bool cacheScores)

Parameters

Type	Name	Description
System.Double	maxCacheRAMMB	The maximum amount in MB the cache is allowed to hold
System.Boolean	cacheScores	Whether to cache the scores

Returns

Type	Description
GroupingSearch	this

SetFillSortFields(Boolean)

Whether to also fill the sort fields per returned group and groups docs.

Declaration

public virtual GroupingSearch SetFillSortFields(bool fillSortFields)

Parameters

Type	Name	Description
System.Boolean	fillSortFields	Whether to also fill the sort fields per returned group and groups docs

Returns

Type	Description
GroupingSearch	this

SetGroupDocsLimit(Int32)

Specifies the number of documents to return inside a group from the specified groupDocsOffset.

Declaration

public virtual GroupingSearch SetGroupDocsLimit(int groupDocsLimit)

Parameters

Type	Name	Description
System.Int32	groupDocsLimit	The number of documents to return inside a group

Returns

Type	Description
GroupingSearch	this

SetGroupDocsOffset(Int32)

Specifies the offset for documents inside a group.

Declaration

public virtual GroupingSearch SetGroupDocsOffset(int groupDocsOffset)

Parameters

Type	Name	Description
System.Int32	groupDocsOffset	The offset for documents inside a

Returns

Type	Description
GroupingSearch	this

SetGroupSort(Sort)

Specifies how groups are sorted. Defaults to RELEVANCE.

Declaration

public virtual GroupingSearch SetGroupSort(Sort groupSort)

Parameters

Type	Name	Description
Lucene.Net.Search.Sort	groupSort	The sort for the groups.

Returns

Type	Description
GroupingSearch	this

SetIncludeMaxScore(Boolean)

Whether to include the score of the most relevant document per group.

Declaration

public virtual GroupingSearch SetIncludeMaxScore(bool includeMaxScore)

Parameters

Type	Name	Description
System.Boolean	includeMaxScore	Whether to include the score of the most relevant document per group

Returns

Type	Description
GroupingSearch	this

SetIncludeScores(Boolean)

Whether to include the scores per doc inside a group.

Declaration

public virtual GroupingSearch SetIncludeScores(bool includeScores)

Parameters

Type	Name	Description
System.Boolean	includeScores	Whether to include the scores per doc inside a group

Returns

Type	Description
GroupingSearch	this

SetInitialSize(Int32)

Sets the initial size of some internal used data structures. This prevents growing data structures many times. This can improve the performance of the grouping at the cost of more initial RAM.

The SetAllGroups(Boolean) and SetAllGroupHeads(Boolean) features use this option. Defaults to 128.

Declaration

public virtual GroupingSearch SetInitialSize(int initialSize)

Parameters

Type	Name	Description
System.Int32	initialSize	The initial size of some internal used data structures

Returns

Type	Description
GroupingSearch	this

SetSortWithinGroup(Sort)

Specified how documents inside a group are sorted. Defaults to RELEVANCE.

Declaration

public virtual GroupingSearch SetSortWithinGroup(Sort sortWithinGroup)

Parameters

Type	Name	Description
Lucene.Net.Search.Sort	sortWithinGroup	The sort for documents inside a group

Returns

Type	Description
GroupingSearch	this