org.apache.lucene.search.similarities

## Class SimilarityBase

- java.lang.Object
- - org.apache.lucene.search.similarities.Similarity
  - - org.apache.lucene.search.similarities.SimilarityBase

- Direct Known Subclasses:
    DFRSimilarity, IBSimilarity, LMSimilarity

      public abstract class SimilarityBase
      extends Similarity

  A subclass of `Similarity` that provides a simplified API for its descendants. Subclasses are only required to implement the `score(org.apache.lucene.search.similarities.BasicStats, float, float)` and `toString()` methods. Implementing `explain(Explanation, BasicStats, int, float, float)` is optional, inasmuch as SimilarityBase already provides a basic explanation of the score and the term frequency. However, implementers of a subclass are encouraged to include as much detail about the scoring method as possible.

  Note: multi-word queries such as phrase queries are scored in a different way than Lucene's default ranking algorithm: whereas it "fakes" an IDF value for the phrase as a whole (since it does not know it), this class instead scores phrases as a summation of the individual term scores.

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

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from class org.apache.lucene.search.similarities.Similarity

      `Similarity.ExactSimScorer, Similarity.SimWeight, Similarity.SloppySimScorer`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected boolean` | `discountOverlaps` True if overlap tokens (tokens with a position of increment of zero) are discounted from the document's length.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `SimilarityBase()` Sole constructor.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `long` | `computeNorm(FieldInvertState state)` Encodes the document length in the same way as `TFIDFSimilarity`.
    `Similarity.SimWeight` | `computeWeight(float queryBoost, CollectionStatistics collectionStats, TermStatistics... termStats)` Compute any collection-level weight (e.g.
    `protected float` | `decodeNormValue(byte norm)` Decodes a normalization factor (document length) stored in an index.
    `protected byte` | `encodeNormValue(float boost, float length)` Encodes the length to a byte via SmallFloat.
    `Similarity.ExactSimScorer` | `exactSimScorer(Similarity.SimWeight stats, AtomicReaderContext context)` Creates a new `Similarity.ExactSimScorer` to score matching documents from a segment of the inverted index.
    `protected Explanation` | `explain(BasicStats stats, int doc, Explanation freq, float docLen)` Explains the score.
    `protected void` | `explain(Explanation expl, BasicStats stats, int doc, float freq, float docLen)` Subclasses should implement this method to explain the score.
    `protected void` | `fillBasicStats(BasicStats stats, CollectionStatistics collectionStats, TermStatistics termStats)` Fills all member fields defined in `BasicStats` in `stats`.
    `boolean` | `getDiscountOverlaps()` Returns true if overlap tokens are discounted from the document's length.
    `static double` | `log2(double x)` Returns the base two logarithm of `x`.
    `protected BasicStats` | `newStats(String field, float queryBoost)` Factory method to return a custom stats object
    `protected abstract float` | `score(BasicStats stats, float freq, float docLen)` Scores the document `doc`.
    `void` | `setDiscountOverlaps(boolean v)` Determines whether overlap tokens (Tokens with 0 position increment) are ignored when computing norm.
    `Similarity.SloppySimScorer` | `sloppySimScorer(Similarity.SimWeight stats, AtomicReaderContext context)` Creates a new `Similarity.SloppySimScorer` to score matching documents from a segment of the inverted index.
    `abstract String` | `toString()` Subclasses must override this method to return the name of the Similarity and preferably the values of parameters (if any) as well.

    - ### Methods inherited from class org.apache.lucene.search.similarities.Similarity

      `coord, queryNorm`

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

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

- - ### Field Detail

    - #### discountOverlaps

          protected boolean discountOverlaps

      True if overlap tokens (tokens with a position of increment of zero) are discounted from the document's length.

  - ### Constructor Detail

    - #### SimilarityBase

          public SimilarityBase()

      Sole constructor. (For invocation by subclass constructors, typically implicit.)

  - ### Method Detail

    - #### setDiscountOverlaps

          public void setDiscountOverlaps(boolean v)

      Determines whether overlap tokens (Tokens with 0 position increment) are ignored when computing norm. By default this is true, meaning overlap tokens do not count when computing norms.
      See Also:
        `computeNorm(org.apache.lucene.index.FieldInvertState)`
      WARNING: This API is experimental and might change in incompatible ways in the next release.

    - #### getDiscountOverlaps

          public boolean getDiscountOverlaps()

      Returns true if overlap tokens are discounted from the document's length.
      See Also:
        `setDiscountOverlaps(boolean)`

    - #### computeWeight

          public final Similarity.SimWeight computeWeight(float queryBoost,
                                           CollectionStatistics collectionStats,
                                           TermStatistics... termStats)

      Description copied from class: `Similarity`
      Compute any collection-level weight (e.g. IDF, average document length, etc) needed for scoring a query.
      Specified by:
        `computeWeight` in class `Similarity`
      Parameters:
        `queryBoost` - the query-time boost.
        `collectionStats` - collection-level statistics, such as the number of tokens in the collection.
        `termStats` - term-level statistics, such as the document frequency of a term across the collection.
      Returns:
        SimWeight object with the information this Similarity needs to score a query.

    - #### newStats

          protected BasicStats newStats(String field,
                            float queryBoost)

      Factory method to return a custom stats object

    - #### fillBasicStats

          protected void fillBasicStats(BasicStats stats,
                            CollectionStatistics collectionStats,
                            TermStatistics termStats)

      Fills all member fields defined in `BasicStats` in `stats`. Subclasses can override this method to fill additional stats.

    - #### score

          protected abstract float score(BasicStats stats,
                    float freq,
                    float docLen)

      Scores the document `doc`.

      Subclasses must apply their scoring formula in this class.

      Parameters:
        `stats` - the corpus level statistics.
        `freq` - the term frequency.
        `docLen` - the document length.
      Returns:
        the score.

    - #### explain

          protected void explain(Explanation expl,
                     BasicStats stats,
                     int doc,
                     float freq,
                     float docLen)

      Subclasses should implement this method to explain the score. `expl` already contains the score, the name of the class and the doc id, as well as the term frequency and its explanation; subclasses can add additional clauses to explain details of their scoring formulae.

      The default implementation does nothing.

      Parameters:
        `expl` - the explanation to extend with details.
        `stats` - the corpus level statistics.
        `doc` - the document id.
        `freq` - the term frequency.
        `docLen` - the document length.

    - #### explain

          protected Explanation explain(BasicStats stats,
                            int doc,
                            Explanation freq,
                            float docLen)

      Explains the score. The implementation here provides a basic explanation in the format score(name-of-similarity, doc=doc-id, freq=term-frequency), computed from:, and attaches the score (computed via the `score(BasicStats, float, float)` method) and the explanation for the term frequency. Subclasses content with this format may add additional details in `explain(Explanation, BasicStats, int, float, float)`.
      Parameters:
        `stats` - the corpus level statistics.
        `doc` - the document id.
        `freq` - the term frequency and its explanation.
        `docLen` - the document length.
      Returns:
        the explanation.

    - #### exactSimScorer

          public Similarity.ExactSimScorer exactSimScorer(Similarity.SimWeight stats,
                                                 AtomicReaderContext context)
                                                   throws IOException

      Description copied from class: `Similarity`
      Creates a new `Similarity.ExactSimScorer` to score matching documents from a segment of the inverted index.
      Specified by:
        `exactSimScorer` in class `Similarity`
      Parameters:
        `stats` - collection information from `Similarity.computeWeight(float, CollectionStatistics, TermStatistics...)`
        `context` - segment of the inverted index to be scored.
      Returns:
        ExactSimScorer for scoring documents across `context`
      Throws:
        `IOException` - if there is a low-level I/O error

    - #### sloppySimScorer

          public Similarity.SloppySimScorer sloppySimScorer(Similarity.SimWeight stats,
                                                   AtomicReaderContext context)
                                                     throws IOException

      Description copied from class: `Similarity`
      Creates a new `Similarity.SloppySimScorer` to score matching documents from a segment of the inverted index.
      Specified by:
        `sloppySimScorer` in class `Similarity`
      Parameters:
        `stats` - collection information from `Similarity.computeWeight(float, CollectionStatistics, TermStatistics...)`
        `context` - segment of the inverted index to be scored.
      Returns:
        SloppySimScorer for scoring documents across `context`
      Throws:
        `IOException` - if there is a low-level I/O error

    - #### toString

          public abstract String toString()

      Subclasses must override this method to return the name of the Similarity and preferably the values of parameters (if any) as well.
      Overrides:
        `toString` in class `Object`

    - #### computeNorm

          public long computeNorm(FieldInvertState state)

      Encodes the document length in the same way as `TFIDFSimilarity`.
      Specified by:
        `computeNorm` in class `Similarity`
      Parameters:
        `state` - current processing state for this field
      Returns:
        computed norm value

    - #### decodeNormValue

          protected float decodeNormValue(byte norm)

      Decodes a normalization factor (document length) stored in an index.
      See Also:
        `encodeNormValue(float,float)`

    - #### encodeNormValue

          protected byte encodeNormValue(float boost,
                             float length)

      Encodes the length to a byte via SmallFloat.

    - #### log2

          public static double log2(double x)

      Returns the base two logarithm of `x`.

Copyright © 2000-2013 Apache Software Foundation. All Rights Reserved.