Package org.apache.lucene.search

Class SortField

java.lang.Object

org.apache.lucene.search.SortField

Direct Known Subclasses:

SortedNumericSortField, SortedSetSortField

public class SortField
extends Object

Stores information about how to sort documents by terms in an individual field. Fields must be indexed in order to sort by them.

Sorting on a numeric field that is indexed with both doc values and points may use an optimization to skip non-competitive documents. This optimization relies on the assumption that the same data is stored in these points and doc values.

Sorting on a SORTED(_SET) field that is indexed with both doc values and term index may use an optimization to skip non-competitive documents. This optimization relies on the assumption that the same data is stored in these term index and doc values.

Created: Feb 11, 2004 1:25:29 PM

Since:

lucene 1.4

See Also:

Sort

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	SortField.Provider	A SortFieldProvider for field sorts
static class	SortField.Type	Specifies the type of the terms to be sorted, or special types such as CUSTOM

Field Summary

Fields

Modifier and Type	Field	Description
static SortField	FIELD_DOC	Represents sorting by document number (index order).
static SortField	FIELD_SCORE	Represents sorting by document score (relevance).
protected Object	missingValue
static Object	STRING_FIRST	Pass this to setMissingValue(java.lang.Object) to have missing string values sort first.
static Object	STRING_LAST	Pass this to setMissingValue(java.lang.Object) to have missing string values sort last.

Constructor Summary

Constructors

Constructor	Description
SortField(String field, FieldComparatorSource comparator)	Creates a sort with a custom comparison function.
SortField(String field, FieldComparatorSource comparator, boolean reverse)	Creates a sort, possibly in reverse, with a custom comparison function.
SortField(String field, SortField.Type type)	Creates a sort by terms in the given field with the type of term values explicitly given.
SortField(String field, SortField.Type type, boolean reverse)	Creates a sort, possibly in reverse, by terms in the given field with the type of term values explicitly given.

Method Summary

Modifier and Type	Method	Description
boolean	equals(Object o)	Returns true if o is equal to this.
Comparator<BytesRef>	getBytesComparator()
FieldComparator<?>	getComparator(int numHits, Pruning pruning)	Returns the FieldComparator to use for sorting.
FieldComparatorSource	getComparatorSource()	Returns the FieldComparatorSource used for custom sorting
String	getField()	Returns the name of the field.
IndexSorter	getIndexSorter()	Returns an IndexSorter used for sorting index segments by this SortField.
Object	getMissingValue()	Return the value to use for documents that don't have a value.
boolean	getOptimizeSortWithIndexedData()	Deprecated.
boolean	getOptimizeSortWithPoints()	Deprecated. This is a duplicate method for SortField#getOptimizeSortWithIndexedData.
boolean	getReverse()	Returns whether the sort should be reversed.
SortField.Type	getType()	Returns the type of contents in the field.
int	hashCode()	Returns a hash code for this SortField instance.
boolean	needsScores()	Whether the relevance score is needed to sort documents.
protected static SortField.Type	readType(DataInput in)
SortField	rewrite(IndexSearcher searcher)	Rewrites this SortField, returning a new SortField if a change is made.
void	setBytesComparator(Comparator<BytesRef> b)
void	setMissingValue(Object missingValue)	Set the value to use for documents that don't have a value.
void	setOptimizeSortWithIndexedData(boolean optimizeSortWithIndexedData)	Deprecated. should only be used for compatibility with 8.x indices that got created with inconsistent data across fields, or the wrong sort configuration in the index sort
void	setOptimizeSortWithPoints(boolean optimizeSortWithPoints)	Deprecated. should only be used for compatibility with 8.x indices that got created with inconsistent data across fields, or the wrong sort configuration in the index sort.
String	toString()

Methods inherited from class java.lang.Object

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

Field Detail

FIELD_SCORE

public static final SortField FIELD_SCORE

Represents sorting by document score (relevance).

FIELD_DOC

public static final SortField FIELD_DOC

Represents sorting by document number (index order).

missingValue

protected Object missingValue

STRING_FIRST

public static final Object STRING_FIRST

Pass this to setMissingValue(java.lang.Object) to have missing string values sort first.

STRING_LAST

public static final Object STRING_LAST

Pass this to setMissingValue(java.lang.Object) to have missing string values sort last.

Constructor Detail

SortField

public SortField(String field,
                 SortField.Type type)

Creates a sort by terms in the given field with the type of term values explicitly given.

Parameters:

field - Name of field to sort by. Can be null if type is SCORE or DOC.

type - Type of values in the terms.

SortField

public SortField(String field,
                 SortField.Type type,
                 boolean reverse)

Creates a sort, possibly in reverse, by terms in the given field with the type of term values explicitly given.

Parameters:

field - Name of field to sort by. Can be null if type is SCORE or DOC.

type - Type of values in the terms.

reverse - True if natural order should be reversed.

SortField

public SortField(String field,
                 FieldComparatorSource comparator)

Creates a sort with a custom comparison function.

Parameters:

field - Name of field to sort by; cannot be null.

comparator - Returns a comparator for sorting hits.

SortField

public SortField(String field,
                 FieldComparatorSource comparator,
                 boolean reverse)

Creates a sort, possibly in reverse, with a custom comparison function.

Parameters:

field - Name of field to sort by; cannot be null.

comparator - Returns a comparator for sorting hits.

reverse - True if natural order should be reversed.

Method Detail

readType

protected static SortField.Type readType(DataInput in)
                                  throws IOException

Throws:

IOException

getMissingValue

public Object getMissingValue()

Return the value to use for documents that don't have a value. A value of null indicates that default should be used.

setMissingValue

public void setMissingValue(Object missingValue)

Set the value to use for documents that don't have a value.

getField

public String getField()

Returns the name of the field. Could return null if the sort is by SCORE or DOC.

Returns:

Name of field, possibly null.

getType

public SortField.Type getType()

Returns the type of contents in the field.

Returns:

One of the constants SCORE, DOC, STRING, INT or FLOAT.

getReverse

public boolean getReverse()

Returns whether the sort should be reversed.

Returns:

True if natural order should be reversed.

getComparatorSource

public FieldComparatorSource getComparatorSource()

Returns the FieldComparatorSource used for custom sorting

toString

public String toString()

Overrides:

toString in class Object

equals

public boolean equals(Object o)

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 Object

hashCode

public int hashCode()

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 Object

setBytesComparator

public void setBytesComparator(Comparator<BytesRef> b)

getBytesComparator

public Comparator<BytesRef> getBytesComparator()

getComparator

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

Returns the FieldComparator to use for sorting.

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

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

rewrite

public SortField rewrite(IndexSearcher searcher)
                  throws IOException

Rewrites this SortField, returning a new SortField if a change is made. Subclasses should override this define their rewriting behavior when this SortField is of type SortField.Type.REWRITEABLE

Parameters:

searcher - IndexSearcher to use during rewriting

Returns:

New rewritten SortField, or this if nothing has changed.

Throws:

IOException - Can be thrown by the rewriting

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

needsScores

public boolean needsScores()

Whether the relevance score is needed to sort documents.

getIndexSorter

public IndexSorter getIndexSorter()

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

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

setOptimizeSortWithIndexedData

@Deprecated
public void setOptimizeSortWithIndexedData(boolean optimizeSortWithIndexedData)

Deprecated.

should only be used for compatibility with 8.x indices that got created with inconsistent data across fields, or the wrong sort configuration in the index sort

Enables/disables numeric sort optimization to use the indexed data.

Enabled by default. By default, sorting on a numeric field activates point sort optimization that can efficiently skip over non-competitive hits. Sort optimization has a number of requirements, one of which is that SortField.Type matches the Point type with which the field was indexed (e.g. sort on IntPoint field should use SortField.Type.INT). Another requirement is that the same data is indexed with points and doc values for the field.

By default, sorting on a SORTED(_SET) field activates sort optimization that can efficiently skip over non-competitive hits. Sort optimization requires that the same data is indexed with term index and doc values for the field.

Parameters:

optimizeSortWithIndexedData - providing false disables the optimization, in cases where these requirements can't be met.

getOptimizeSortWithIndexedData

@Deprecated
public boolean getOptimizeSortWithIndexedData()

Deprecated.

Returns whether sort optimization should be optimized with indexed data

Returns:

whether sort optimization should be optimized with indexed data

setOptimizeSortWithPoints

@Deprecated
public void setOptimizeSortWithPoints(boolean optimizeSortWithPoints)

Deprecated.

should only be used for compatibility with 8.x indices that got created with inconsistent data across fields, or the wrong sort configuration in the index sort. This is a duplicate method for SortField#setOptimizeSortWithIndexedData.

Enables/disables numeric sort optimization to use the Points index.

Enabled by default. By default, sorting on a numeric field activates point sort optimization that can efficiently skip over non-competitive hits. Sort optimization has a number of requirements, one of which is that SortField.Type matches the Point type with which the field was indexed (e.g. sort on IntPoint field should use SortField.Type.INT). Another requirement is that the same data is indexed with points and doc values for the field.

Parameters:

optimizeSortWithPoints - providing false disables the optimization, in cases where these requirements can't be met.

getOptimizeSortWithPoints

@Deprecated
public boolean getOptimizeSortWithPoints()

Deprecated.

This is a duplicate method for SortField#getOptimizeSortWithIndexedData.

Returns whether sort optimization should be optimized with points index

Returns:

whether sort optimization should be optimized with points index