Package org.apache.lucene.search

Class BinarySortField

java.lang.Object

org.apache.lucene.search.SortField

org.apache.lucene.search.BinarySortField

public class BinarySortField
extends SortField

SortField for BinaryDocValues, usable as an index sort.

Unlike a SortField.Type.STRING sort (backed by SortedDocValues), values are compared directly rather than through a term dictionary, making this a good fit for high-cardinality fields where a dictionary would be pure overhead. Documents are ordered by the unsigned byte order of their sort key (BytesRef.compareTo(org.apache.lucene.util.BytesRef)), optionally reversed, with missing values sorted first or last via SortField.STRING_FIRST / SortField.STRING_LAST (first by default).

By default the sort key is the stored value. A subclass may override getSortKeyDocValues(LeafReader) to derive an order-preserving key from the stored bytes and/or other doc-values fields of the segment (for example to select the minimum of a multi-valued field). Such a subclass must register a SortFieldProvider via SPI so the sort can be read back and used on merge.

This field can also sort search results, comparing values with a linear scan of the binary doc values (without the skipping optimizations available to numeric or SORTED fields).

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

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final class	BinarySortField.Provider	A SortFieldProvider for this sort

Nested classes/interfaces inherited from class org.apache.lucene.search.SortField

SortField.Type

Field Summary

Fields inherited from class org.apache.lucene.search.SortField

FIELD_DOC, FIELD_SCORE, missingValue, reverse, STRING_FIRST, STRING_LAST

Constructor Summary

Constructors

Modifier	Constructor	Description
	BinarySortField(String field, boolean reverse)	Creates a sort, possibly in reverse, by the unsigned byte order of the field's value.
	BinarySortField(String field, boolean reverse, Object missingValue)	Creates a sort, possibly in reverse, by the unsigned byte order of the field's value, with the given handling of missing values.
protected	BinarySortField(String field, boolean reverse, Object missingValue, String providerName)	Creates a sort for a subclass that overrides getSortKeyDocValues(LeafReader).

Method Summary

Modifier and Type	Method	Description
boolean	equals(Object obj)	Returns true if o is equal to this.
FieldComparator<?>	getComparator(int numHits, Pruning pruning)	Returns the FieldComparator to use for sorting.
IndexSorter	getIndexSorter()	Returns an IndexSorter used for sorting index segments by this SortField.
protected BinaryDocValues	getSortKeyDocValues(LeafReader reader)	Returns the per-document sort key, as a BinaryDocValues whose BinaryDocValues.binaryValue() is the bytes to sort on.
int	hashCode()	Returns a hash code for this SortField instance.
String	toString()

Methods inherited from class org.apache.lucene.search.SortField

getComparatorSource, getField, getMissingValue, getOptimizeSortWithIndexedData, getOptimizeSortWithPoints, getReverse, getType, needsScores, readType, rewrite, setMissingValue, setOptimizeSortWithIndexedData, setOptimizeSortWithPoints

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Details

BinarySortField

public BinarySortField(String field,
 boolean reverse)

Creates a sort, possibly in reverse, by the unsigned byte order of the field's value.

Parameters:

field - Name of field to sort by. Must not be null.

reverse - True if natural order should be reversed.

BinarySortField

public BinarySortField(String field,
 boolean reverse,
 Object missingValue)

Creates a sort, possibly in reverse, by the unsigned byte order of the field's value, with the given handling of missing values.

Parameters:

field - Name of field to sort by. Must not be null.

reverse - True if natural order should be reversed.

missingValue - SortField.STRING_FIRST, SortField.STRING_LAST, or null (missing first).

BinarySortField

protected BinarySortField(String field,
 boolean reverse,
 Object missingValue,
 String providerName)

Creates a sort for a subclass that overrides getSortKeyDocValues(LeafReader).

The subclass must supply the name of a dedicated SortFieldProvider (registered via SPI) whose SortFieldProvider.readSortField(org.apache.lucene.store.DataInput) reconstructs the subclass, so that the same sort-key derivation is used when the index sort is read back and on merge.

Parameters:

field - Name of field to sort by. Must not be null.

reverse - True if natural order should be reversed.

missingValue - SortField.STRING_FIRST, SortField.STRING_LAST, or null.

providerName - the SPI name of the companion SortFieldProvider.

Method Details

getSortKeyDocValues

protected BinaryDocValues getSortKeyDocValues(LeafReader reader)
                                       throws IOException

Returns the per-document sort key, as a BinaryDocValues whose BinaryDocValues.binaryValue() is the bytes to sort on. The default returns the field's values unchanged; override to derive a key from the stored bytes and/or other doc-values fields of the segment.

Values are read in increasing docID order; advance any underlying doc values with DocIdSetIterator.nextDoc() only, since at flush time the in-memory doc values do not support advanceExact. The returned key has the same lifetime as BinaryDocValues.binaryValue() (valid until the next call) and need not be a copy.

Throws:

IOException

getIndexSorter

public IndexSorter getIndexSorter()

Description copied from class: SortField

Returns an IndexSorter used for sorting index segments by this SortField.

If the SortField cannot be used for index sorting (for example, if it uses scores or other query-dependent values) then this method should return null

SortFields that implement this method should also implement a companion SortFieldProvider to serialize and deserialize the sort in index segment headers

Overrides:

getIndexSorter in class SortField

getComparator

public FieldComparator<?> getComparator(int numHits,
 Pruning pruning)

Description copied from class: SortField

Returns the FieldComparator to use for sorting.

Overrides:

getComparator in class SortField

Parameters:

numHits - number of top hits the queue will store

pruning - controls how can the comparator to skip documents via LeafFieldComparator.competitiveIterator()

Returns:

FieldComparator to use when sorting

hashCode

public int hashCode()

Description copied from class: SortField

Returns a hash code for this SortField instance. If a FieldComparatorSource was provided, it must properly implement hashCode (unless a singleton is always used).

Overrides:

hashCode in class SortField

equals

public boolean equals(Object obj)

Description copied from class: SortField

Returns true if o is equal to this. If a FieldComparatorSource was provided, it must properly implement equals (unless a singleton is always used).

Overrides:

equals in class SortField

toString

public String toString()

Overrides:

toString in class SortField