Class ToParentBlockJoinCollector

Collects parent document hits for a Lucene.Net.Search.Query containing one more more BlockJoinQuery clauses, sorted by the specified parent Lucene.Net.Search.Sort. Note that this cannot perform arbitrary joins; rather, it requires that all joined documents are indexed as a doc block (using AddDocuments(IEnumerable<IEnumerable<IIndexableField>>, Analyzer) or UpdateDocuments(Term, IEnumerable<IEnumerable<IIndexableField>>, Analyzer). Ie, the join is computed at index time.

The parent Lucene.Net.Search.Sort must only use fields from the parent documents; sorting by field in the child documents is not supported.

You should only use this collector if one or more of the clauses in the query is a ToParentBlockJoinQuery. This collector will find those query clauses and record the matching child documents for the top scoring parent documents.

Multiple joins (star join) and nested joins and a mix of the two are allowed, as long as in all cases the documents corresponding to a single row of each joined parent table were indexed as a doc block.

For the simple star join you can retrieve the Lucene.Net.Search.Grouping.ITopGroups<TGroupValue> instance containing each ToParentBlockJoinQuery's matching child documents for the top parent groups, using GetTopGroups(ToParentBlockJoinQuery, Sort, int, int, int, bool). Ie, a single query, which will contain two or more ToParentBlockJoinQuery's as clauses representing the star join, can then retrieve two or more Lucene.Net.Search.Grouping.ITopGroups<TGroupValue> instances.

For nested joins, the query will run correctly (ie, match the right parent and child documents), however, because Lucene.Net.Search.Grouping.TopGroups<TGroupValue> is currently unable to support nesting (each group is not able to hold another Lucene.Net.Search.Grouping.TopGroups<TGroupValue>), you are only able to retrieve the Lucene.Net.Search.Grouping.TopGroups<TGroupValue> of the first join. The Lucene.Net.Search.Grouping.TopGroups<TGroupValue> of the nested joins will not be correct.

See http://lucene.apache.org/core/4_8_0/join/ for a code sample.

Note

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

Inheritance

object

ToParentBlockJoinCollector

Implements

ICollector

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Namespace: Lucene.Net.Search.Join

Assembly: Lucene.Net.Join.dll

Syntax

public class ToParentBlockJoinCollector : ICollector

Constructors

ToParentBlockJoinCollector(Sort, int, bool, bool)

Creates a ToParentBlockJoinCollector. The provided sort must not be null. If you pass true trackScores, all ToParentBlockQuery instances must not use None.

Declaration

public ToParentBlockJoinCollector(Sort sort, int numParentHits, bool trackScores, bool trackMaxScore)

Parameters

Type	Name	Description
Sort	sort
int	numParentHits
bool	trackScores
bool	trackMaxScore

Properties

AcceptsDocsOutOfOrder

Return true if this collector does not require the matching docIDs to be delivered in int sort order (smallest to largest) to Collect(int).

Most Lucene Query implementations will visit matching docIDs in order. However, some queries (currently limited to certain cases of Lucene.Net.Search.BooleanQuery) can achieve faster searching if the Lucene.Net.Search.ICollector allows them to deliver the docIDs out of order.

Many collectors don't mind getting docIDs out of order, so it's important to return true here.

Declaration

public virtual bool AcceptsDocsOutOfOrder { get; }

Property Value

Type	Description
bool

MaxScore

Returns the highest score across all collected parent hits, as long as trackMaxScores=true was passed ToParentBlockJoinCollector(Sort, int, bool, bool) on construction. Else, this returns NaN.

Declaration

public virtual float MaxScore { get; }

Property Value

Type	Description
float

Methods

Collect(int)

Called once for every document matching a query, with the unbased document number.

Note: The collection of the current segment can be terminated by throwing a Lucene.Net.Search.CollectionTerminatedException. In this case, the last docs of the current Lucene.Net.Index.AtomicReaderContext will be skipped and Lucene.Net.Search.IndexSearcher will swallow the exception and continue collection with the next leaf.

Note: this is called in an inner search loop. For good search performance, implementations of this method should not call Doc(int) or Document(int) on every hit. Doing so can slow searches by an order of magnitude or more.

Declaration

public virtual void Collect(int parentDoc)

Parameters

Type	Name	Description
int	parentDoc

GetTopGroups(ToParentBlockJoinQuery, Sort, int, int, int, bool)

Returns the Lucene.Net.Search.Grouping.ITopGroups<TGroupValue> for the specified BlockJoinQuery. The groupValue of each GroupDocs will be the parent docID for that group. The number of documents within each group is calculated as minimum of maxDocsPerGroup and number of matched child documents for that group. Returns null if no groups matched.

Declaration

public virtual ITopGroups<int> GetTopGroups(ToParentBlockJoinQuery query, Sort withinGroupSort, int offset, int maxDocsPerGroup, int withinGroupOffset, bool fillSortFields)

Parameters

Type	Name	Description
ToParentBlockJoinQuery	query	Search query
Sort	withinGroupSort	Sort criteria within groups
int	offset	Parent docs offset
int	maxDocsPerGroup	Upper bound of documents per group number
int	withinGroupOffset	Offset within each group of child docs
bool	fillSortFields	Specifies whether to add sort fields or not

Returns

Type	Description
ITopGroups<int>	Lucene.Net.Search.Grouping.ITopGroups<TGroupValue> for specified query

Exceptions

Type	Condition
IOException	if there is a low-level I/O error

GetTopGroupsWithAllChildDocs(ToParentBlockJoinQuery, Sort, int, int, bool)

Returns the Lucene.Net.Search.Grouping.TopGroups<TGroupValue> for the specified BlockJoinQuery. The groupValue of each GroupDocs will be the parent docID for that group. The number of documents within each group equals to the total number of matched child documents for that group. Returns null if no groups matched.

Declaration

public virtual ITopGroups<int> GetTopGroupsWithAllChildDocs(ToParentBlockJoinQuery query, Sort withinGroupSort, int offset, int withinGroupOffset, bool fillSortFields)

Parameters

Type	Name	Description
ToParentBlockJoinQuery	query	Search query
Sort	withinGroupSort	Sort criteria within groups
int	offset	Parent docs offset
int	withinGroupOffset	Offset within each group of child docs
bool	fillSortFields	Specifies whether to add sort fields or not

Returns

Type	Description
ITopGroups<int>	Lucene.Net.Search.Grouping.ITopGroups<TGroupValue> for specified query

Exceptions

Type	Condition
IOException	if there is a low-level I/O error

SetNextReader(AtomicReaderContext)

Called before collecting from each Lucene.Net.Index.AtomicReaderContext. All doc ids in Collect(int) will correspond to Lucene.Net.Index.IndexReaderContext.Reader.

Add Lucene.Net.Index.AtomicReaderContext.DocBase to the current Lucene.Net.Index.IndexReaderContext.Reader's internal document id to re-base ids in Collect(int).

Declaration

public virtual void SetNextReader(AtomicReaderContext context)

Parameters

Type	Name	Description
AtomicReaderContext	context	next atomic reader context

SetScorer(Scorer)

Called before successive calls to Collect(int). Implementations that need the score of the current document (passed-in to Collect(int)), should save the passed-in Lucene.Net.Search.Scorer and call scorer.GetScore() when needed.

Declaration

public virtual void SetScorer(Scorer scorer)

Parameters

Type	Name	Description
Scorer	scorer

Implements

Lucene.Net.Search.ICollector