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

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.

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `protected class`
  `LogOddsFusionQuery.LogOddsFusionWeight`
  Weight for LogOddsFusionQuery.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `LogOddsFusionQuery(Collection<? extends Query> clauses)`
  Creates a new LogOddsFusionQuery with default alpha=0.5, uniform weighting, and softplus gating.
  `LogOddsFusionQuery(Collection<? extends Query> clauses, float alpha)`
  Creates a new LogOddsFusionQuery with uniform weighting and softplus gating.
  `LogOddsFusionQuery(Collection<? extends Query> clauses, float alpha, float[] weights)`
  Creates a new LogOddsFusionQuery with per-signal weights (softplus gating, no normalization).
  `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.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Weight`
  `createWeight(IndexSearcher searcher, ScoreMode scoreMode, float boost)`
  Expert: Constructs an appropriate Weight implementation for this query.
  `boolean`
  `equals(Object other)`
  Override and implement query instance equivalence properly in a subclass.
  `float`
  `getAlpha()`
  Returns the alpha (confidence scaling exponent).
  `Collection<Query>`
  `getClauses()`
  Returns the clauses.
  `float[]`
  `getWeights()`
  Returns a copy of the per-signal weights, or null if uniform weighting is used.
  `int`
  `hashCode()`
  Override and implement query hash code properly in a subclass.
  `Iterator<Query>`
  `iterator()`
  `Query`
  `rewrite(IndexSearcher indexSearcher)`
  Expert: called to re-write queries into primitive queries.
  `String`
  `toString(String field)`
  Prints a query to a string, with `field` assumed to be the default field and omitted.
  `void`
  `visit(QueryVisitor visitor)`
  Recurse through the query tree, visiting any child queries.

  ### Methods inherited from class org.apache.lucene.search.Query

  `classHash, sameClassAs, toString`

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

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

  ### Methods inherited from interface java.lang.Iterable

  `forEach, spliterator`

- ## 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:
      - `IndexSearcher.rewrite(Query)`

  - ### 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:
      - `Query.sameClassAs(Object)`
      - `Query.classHash()`

  - ### 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:
      - `Query.equals(Object)`