Package org.apache.lucene.search

# Class DoubleValuesSource

java.lang.Object
org.apache.lucene.search.DoubleValuesSource

All Implemented Interfaces:
  `SegmentCacheable`

public abstract class DoubleValuesSource extends Object implements SegmentCacheable
Base class for producing `DoubleValues`

To obtain a `DoubleValues` object for a leaf reader, clients should call `rewrite(IndexSearcher)` against the top-level searcher, and then call `getValues(LeafReaderContext, DoubleValues)` on the resulting DoubleValuesSource.

DoubleValuesSource objects for NumericDocValues fields can be obtained by calling `fromDoubleField(String)`, `fromFloatField(String)`, `fromIntField(String)` or `fromLongField(String)`, or from `fromField(String, LongToDoubleFunction)` if special long-to-double encoding is required.

Scores may be used as a source for value calculations by wrapping a `Scorer` using `fromScorer(Scorable)` and passing the resulting DoubleValues to `getValues(LeafReaderContext, DoubleValues)`. The scores can then be accessed using the `SCORES` DoubleValuesSource.

## Field Summary

Fields
Modifier and Type
Field
Description
`static final DoubleValuesSource`
`SCORES`
A DoubleValuesSource that exposes a document's score

## Constructor Summary

Constructors
Constructor
Description
`DoubleValuesSource()`

## Method Summary

Modifier and Type
Method
Description
`static DoubleValuesSource`
`constant(double value)`
Creates a DoubleValuesSource that always returns a constant value
`abstract boolean`
`equals(Object obj)`
`Explanation`
`explain(LeafReaderContext ctx, int docId, Explanation scoreExplanation)`
An explanation of the value for the named document.
`static DoubleValuesSource`
`fromDoubleField(String field)`
Creates a DoubleValuesSource that wraps a double-valued field
`static DoubleValuesSource`
`fromField(String field, LongToDoubleFunction decoder)`
Creates a DoubleValuesSource that wraps a generic NumericDocValues field
`static DoubleValuesSource`
`fromFloatField(String field)`
Creates a DoubleValuesSource that wraps a float-valued field
`static DoubleValuesSource`
`fromIntField(String field)`
Creates a DoubleValuesSource that wraps an int-valued field
`static DoubleValuesSource`
`fromLongField(String field)`
Creates a DoubleValuesSource that wraps a long-valued field
`static DoubleValuesSource`
`fromQuery(Query query)`
Create a DoubleValuesSource that returns the score of a particular query
`static DoubleValues`
`fromScorer(Scorable scorer)`
Returns a DoubleValues instance that wraps scores returned by a Scorer.
`SortField`
`getSortField(boolean reverse)`
Create a sort field based on the value of this producer
`abstract DoubleValues`
`getValues(LeafReaderContext ctx, DoubleValues scores)`
Returns a `DoubleValues` instance for the passed-in LeafReaderContext and scores
`abstract int`
`hashCode()`
`abstract boolean`
`needsScores()`
Return true if document scores are needed to calculate values
`abstract DoubleValuesSource`
`rewrite(IndexSearcher reader)`
Return a DoubleValuesSource specialised for the given IndexSearcher
`static DoubleValues`
`similarityToQueryVector(LeafReaderContext ctx, byte[] queryVector, String vectorField)`
Returns a DoubleValues instance for computing the vector similarity score per document against the byte query vector
`static DoubleValues`
`similarityToQueryVector(LeafReaderContext ctx, float[] queryVector, String vectorField)`
Returns a DoubleValues instance for computing the vector similarity score per document against the float query vector
`final LongValuesSource`
`toLongValuesSource()`
Convert to a LongValuesSource by casting the double values to longs
`final LongValuesSource`
`toSortableLongDoubleValuesSource()`
Convert to `LongValuesSource` by calling `NumericUtils.doubleToSortableLong(double)`
`abstract String`
`toString()`

### Methods inherited from class java.lang.Object

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

### Methods inherited from interface org.apache.lucene.search.SegmentCacheable

`isCacheable`

## Field Details

### SCORES

public static final DoubleValuesSource SCORES
A DoubleValuesSource that exposes a document's score

If this source is used as part of a values calculation, then callers must not pass `null` as the `DoubleValues` parameter on `getValues(LeafReaderContext, DoubleValues)`

## Constructor Details

### DoubleValuesSource

public DoubleValuesSource()

## Method Details

### getValues

public abstract DoubleValues getValues(LeafReaderContext ctx, DoubleValues scores) throws IOException
Returns a `DoubleValues` instance for the passed-in LeafReaderContext and scores

If scores are not needed to calculate the values (ie `returns false`, callers may safely pass `null` for the `scores` parameter.

Throws:
  `IOException`

### needsScores

public abstract boolean needsScores()
Return true if document scores are needed to calculate values

### explain

public Explanation explain(LeafReaderContext ctx, int docId, Explanation scoreExplanation) throws IOException
An explanation of the value for the named document.

Parameters:
  `ctx` - the readers context to create the `Explanation` for.
  `docId` - the document's id relative to the given context's reader
Returns:
  an Explanation for the value
Throws:
  `IOException` - if an `IOException` occurs

### rewrite

public abstract DoubleValuesSource rewrite(IndexSearcher reader) throws IOException
Return a DoubleValuesSource specialised for the given IndexSearcher

Implementations should assume that this will only be called once. IndexReader-independent implementations can just return `this`

Queries that use DoubleValuesSource objects should call rewrite() during `Query.createWeight(IndexSearcher, ScoreMode, float)` rather than during `Query.rewrite(IndexSearcher)` to avoid IndexReader reference leakage.

For the same reason, implementations that cache references to the IndexSearcher should return a new object from this method.

Throws:
  `IOException`

### getSortField

public SortField getSortField(boolean reverse)
Create a sort field based on the value of this producer

Parameters:
  `reverse` - true if the sort should be decreasing

### hashCode

public abstract int hashCode()

Overrides:
  `hashCode` in class `Object`

### equals

public abstract boolean equals(Object obj)

Overrides:
  `equals` in class `Object`

### toString

public abstract String toString()

Overrides:
  `toString` in class `Object`

### toLongValuesSource

public final LongValuesSource toLongValuesSource()
Convert to a LongValuesSource by casting the double values to longs

### toSortableLongDoubleValuesSource

public final LongValuesSource toSortableLongDoubleValuesSource()
Convert to `LongValuesSource` by calling `NumericUtils.doubleToSortableLong(double)`

### similarityToQueryVector

public static DoubleValues similarityToQueryVector(LeafReaderContext ctx, byte[] queryVector, String vectorField) throws IOException
Returns a DoubleValues instance for computing the vector similarity score per document against the byte query vector

Parameters:
  `ctx` - the context for which to return the DoubleValues
  `queryVector` - byte query vector
  `vectorField` - knn byte field name
Returns:
  DoubleValues instance
Throws:
  `IOException` - if an `IOException` occurs

### similarityToQueryVector

public static DoubleValues similarityToQueryVector(LeafReaderContext ctx, float[] queryVector, String vectorField) throws IOException
Returns a DoubleValues instance for computing the vector similarity score per document against the float query vector

Parameters:
  `ctx` - the context for which to return the DoubleValues
  `queryVector` - float query vector
  `vectorField` - knn float field name
Returns:
  DoubleValues instance
Throws:
  `IOException` - if an `IOException` occurs

### fromField

public static DoubleValuesSource fromField(String field, LongToDoubleFunction decoder)
Creates a DoubleValuesSource that wraps a generic NumericDocValues field

Parameters:
  `field` - the field to wrap, must have NumericDocValues
  `decoder` - a function to convert the long-valued doc values to doubles

### fromDoubleField

public static DoubleValuesSource fromDoubleField(String field)
Creates a DoubleValuesSource that wraps a double-valued field

### fromFloatField

public static DoubleValuesSource fromFloatField(String field)
Creates a DoubleValuesSource that wraps a float-valued field

### fromLongField

public static DoubleValuesSource fromLongField(String field)
Creates a DoubleValuesSource that wraps a long-valued field

### fromIntField

public static DoubleValuesSource fromIntField(String field)
Creates a DoubleValuesSource that wraps an int-valued field

### constant

public static DoubleValuesSource constant(double value)
Creates a DoubleValuesSource that always returns a constant value

### fromScorer

public static DoubleValues fromScorer(Scorable scorer)
Returns a DoubleValues instance that wraps scores returned by a Scorer.

Note: If you intend to call `Scorable.score()` on the provided `scorer` separately, you may want to consider wrapping the collector with `ScoreCachingWrappingScorer.wrap(LeafCollector)` to avoid computing the actual score multiple times.

### fromQuery

public static DoubleValuesSource fromQuery(Query query)
Create a DoubleValuesSource that returns the score of a particular query