Package org.apache.lucene.search

Class LogOddsFusionQuery

java.lang.Object
org.apache.lucene.search.Query
org.apache.lucene.search.LogOddsFusionQuery
All Implemented Interfaces:
Iterable<Query>
public final class LogOddsFusionQuery extends Query implements Iterable<Query>
A query that combines sub-query probability scores via log-odds fusion. Sub-queries are expected to produce scores in (0, 1) representing probabilities (e.g., from BayesianScoreQuery wrapping a BM25 query, or KNN cosine similarity).

The combination formula resolves the shrinkage problem of naive probabilistic AND by:

  1. Converting each sub-score to log-odds: logit(p) = log(p / (1 - p))
  2. Computing the mean log-odds across all clauses (non-matching contribute 0 = neutral)
  3. Applying multiplicative confidence scaling: meanLogit * n^alpha
  4. Converting back to probability via sigmoid

The alpha parameter controls the confidence scaling exponent. The default alpha=0.5 implements the sqrt(n) scaling law from "From Bayesian Inference to Neural Computation".

Optional per-signal weights enable weighted Log-OP (Logarithmic Opinion Pooling) where each signal's log-odds contribution is scaled by its reliability weight. Weights must be non-negative and sum to 1. When weights are provided, the scoring formula becomes: sigmoid(n^alpha * sum(w_i * softplus(logit(p_i)))) instead of the uniform mean.

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

  • Constructor Details

    • LogOddsFusionQuery

      public LogOddsFusionQuery(Collection<? extends Query> clauses, float alpha, float[] weights, float[] logitMin, float[] logitMax)
      Creates a new LogOddsFusionQuery with per-signal weights and optional logit normalization.
      Parameters:
      clauses - the sub-queries to combine
      alpha - confidence scaling exponent (0.5 = sqrt(n) law)
      weights - per-signal weights (must be non-negative, finite, and sum to 1.0), or null for uniform weighting
      logitMin - per-signal logit lower bounds for normalization, or null to use softplus gating
      logitMax - per-signal logit upper bounds for normalization, or null to use softplus gating
      Throws:
      IllegalArgumentException - if alpha is not in [0, 1], or weights/bounds are invalid

    • LogOddsFusionQuery

      public LogOddsFusionQuery(Collection<? extends Query> clauses, float alpha, float[] weights)
      Creates a new LogOddsFusionQuery with per-signal weights (softplus gating, no normalization).
      Parameters:
      clauses - the sub-queries to combine
      alpha - confidence scaling exponent (0.5 = sqrt(n) law)
      weights - per-signal weights, or null for uniform weighting
      Throws:
      IllegalArgumentException - if alpha is not in [0, 1], or weights are invalid

    • LogOddsFusionQuery

      public LogOddsFusionQuery(Collection<? extends Query> clauses, float alpha)
      Creates a new LogOddsFusionQuery with uniform weighting and softplus gating.
      Parameters:
      clauses - the sub-queries to combine
      alpha - confidence scaling exponent (0.5 = sqrt(n) law)
      Throws:
      IllegalArgumentException - if alpha is not in [0, 1]

    • LogOddsFusionQuery

      public LogOddsFusionQuery(Collection<? extends Query> clauses)
      Creates a new LogOddsFusionQuery with default alpha=0.5, uniform weighting, and softplus gating.
      Parameters:
      clauses - the sub-queries to combine

  • Method Details

    • iterator

      public Iterator<Query> iterator()
      Specified by:
      iterator in interface Iterable<Query>

    • getClauses

      public Collection<Query> getClauses()
      Returns the clauses.

    • getAlpha

      public float getAlpha()
      Returns the alpha (confidence scaling exponent).

    • getWeights

      public float[] getWeights()
      Returns a copy of the per-signal weights, or null if uniform weighting is used.

      When non-null, the i-th element is the weight for the i-th clause in the order returned by getClauses().

    • createWeight

      public Weight createWeight(IndexSearcher searcher, ScoreMode scoreMode, float boost) throws IOException
      Description copied from class: Query
      Expert: Constructs an appropriate Weight implementation for this query.

      Only implemented by primitive queries, which re-write to themselves.

      Overrides:
      createWeight in class Query
      Parameters:
      scoreMode - How the produced scorers will be consumed.
      boost - The boost that is propagated by the parent queries.
      Throws:
      IOException

    • rewrite

      public Query rewrite(IndexSearcher indexSearcher) throws IOException
      Description copied from class: Query
      Expert: called to re-write queries into primitive queries. For example, a PrefixQuery will be rewritten into a BooleanQuery that consists of TermQuerys.

      Callers are expected to call rewrite multiple times if necessary, until the rewritten query is the same as the original query.

      The rewrite process may be able to make use of IndexSearcher's executor and be executed in parallel if the executor is provided.

      Overrides:
      rewrite in class Query
      Throws:
      IOException
      See Also:

    • visit

      public void visit(QueryVisitor visitor)
      Description copied from class: Query
      Recurse through the query tree, visiting any child queries.
      Specified by:
      visit in class Query
      Parameters:
      visitor - a QueryVisitor to be called by each query in the tree

    • toString

      public String toString(String field)
      Description copied from class: Query
      Prints a query to a string, with field assumed to be the default field and omitted.
      Specified by:
      toString in class Query

    • equals

      public boolean equals(Object other)
      Description copied from class: Query
      Override and implement query instance equivalence properly in a subclass. This is required so that QueryCache works properly.

      Typically a query will be equal to another only if it's an instance of the same class and its document-filtering properties are identical to those of the other instance. Utility methods are provided for certain repetitive code.

      Specified by:
      equals in class Query
      See Also:

    • hashCode

      public int hashCode()
      Description copied from class: Query
      Override and implement query hash code properly in a subclass. This is required so that QueryCache works properly.
      Specified by:
      hashCode in class Query
      See Also: