DoubleValuesSource (Lucene 10.5.0 core API)
Description: declaration: package: org.apache.lucene.search, class: DoubleValuesSource

Package org.apache.lucene.search

# Class DoubleValuesSource

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

All Implemented Interfaces:
  `SegmentCacheable`

Direct Known Subclasses:
  `FullPrecisionFloatVectorSimilarityValuesSource`, `LateInteractionFloatValuesSource`

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
  `SortField`
  `getSortField(boolean reverse, double missingValue)`
  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

  - ### getSortField

    public SortField getSortField(boolean reverse, double missingValue)
    Create a sort field based on the value of this producer
    Parameters:
      `reverse` - true if the sort should be decreasing
      `missingValue` - a placeholder to use for documents with no value

  - ### 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