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 DoubleValuesSource` | `SCORES` | A DoubleValuesSource that exposes a document's score

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `DoubleValuesSource()` |

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
    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
    `LongValuesSource` | `toLongValuesSource()` | Convert to a LongValuesSource by casting the double values to longs
    `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 Detail

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

    - #### DoubleValuesSource

          public DoubleValuesSource()

  - ### Method Detail

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

    - #### 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 it with `ScoreCachingWrappingScorer.wrap(Scorable)` 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