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

Package org.apache.lucene.search

# Class AutomatonQuery

java.lang.Object
org.apache.lucene.search.Query
org.apache.lucene.search.MultiTermQuery
org.apache.lucene.search.AutomatonQuery

All Implemented Interfaces:
  `Accountable`

Direct Known Subclasses:
  `PrefixQuery`, `RegexpQuery`, `TermRangeQuery`, `WildcardQuery`

public class AutomatonQuery extends MultiTermQuery implements Accountable
A `Query` that will match terms against a finite-state machine.

This query will match documents that contain terms accepted by a given finite-state machine. The automaton can be constructed with the `org.apache.lucene.util.automaton` API. Alternatively, it can be created from a regular expression with `RegexpQuery` or from the standard Lucene wildcard syntax with `WildcardQuery`.

When the query is executed, it will enumerate the term dictionary in an intelligent way to reduce the number of comparisons. For example: the regular expression of `[dl]og?` will make approximately four comparisons: do, dog, lo, and log.

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.MultiTermQuery

  `MultiTermQuery.RewriteMethod, MultiTermQuery.TopTermsBlendedFreqScoringRewrite, MultiTermQuery.TopTermsBoostOnlyBooleanQueryRewrite, MultiTermQuery.TopTermsScoringBooleanQueryRewrite`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected final Automaton`
  `automaton`
  the automaton to match index terms against
  `protected final boolean`
  `automatonIsBinary`
  `protected final CompiledAutomaton`
  `compiled`
  `protected final Term`
  `term`
  term containing the field, and possibly some pattern structure

  ### Fields inherited from class org.apache.lucene.search.MultiTermQuery

  `CONSTANT_SCORE_BLENDED_REWRITE, CONSTANT_SCORE_BOOLEAN_REWRITE, CONSTANT_SCORE_REWRITE, DOC_VALUES_REWRITE, field, rewriteMethod, SCORING_BOOLEAN_REWRITE`

  ### Fields inherited from interface org.apache.lucene.util.Accountable

  `NULL_ACCOUNTABLE`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `AutomatonQuery(Term term, Automaton automaton)`
  Create a new AutomatonQuery from an `Automaton`.
  `AutomatonQuery(Term term, Automaton automaton, boolean isBinary)`
  Create a new AutomatonQuery from an `Automaton`.
  `AutomatonQuery(Term term, Automaton automaton, boolean isBinary, MultiTermQuery.RewriteMethod rewriteMethod)`
  Create a new AutomatonQuery from an `Automaton`.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `boolean`
  `equals(Object obj)`
  Override and implement query instance equivalence properly in a subclass.
  `Automaton`
  `getAutomaton()`
  Returns the automaton used to create this query
  `CompiledAutomaton`
  `getCompiled()`
  `protected TermsEnum`
  `getTermsEnum(Terms terms, AttributeSource atts)`
  Construct the enumeration to be used, expanding the pattern term.
  `int`
  `hashCode()`
  Override and implement query hash code properly in a subclass.
  `boolean`
  `isAutomatonBinary()`
  Is this a binary (byte) oriented automaton.
  `long`
  `ramBytesUsed()`
  Returns an estimate of the JVM heap memory used by this object in bytes.
  `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.MultiTermQuery

  `getField, getRewriteMethod, getTermsCount, getTermsEnum, rewrite`

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

  `classHash, createWeight, sameClassAs, toString`

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

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

  ### Methods inherited from interface org.apache.lucene.util.Accountable

  `getChildResources`

- ## Field Details

  - ### automaton

    protected final Automaton automaton
    the automaton to match index terms against

  - ### compiled

    protected final CompiledAutomaton compiled

  - ### term

    protected final Term term
    term containing the field, and possibly some pattern structure

  - ### automatonIsBinary

    protected final boolean automatonIsBinary

- ## Constructor Details

  - ### AutomatonQuery

    public AutomatonQuery(Term term, Automaton automaton)
    Create a new AutomatonQuery from an `Automaton`.
    Parameters:
      `term` - Term containing field and possibly some pattern structure. The term text is ignored.
      `automaton` - Automaton to run, terms that are accepted are considered a match.

  - ### AutomatonQuery

    public AutomatonQuery(Term term, Automaton automaton, boolean isBinary)
    Create a new AutomatonQuery from an `Automaton`.
    Parameters:
      `term` - Term containing field and possibly some pattern structure. The term text is ignored.
      `automaton` - Automaton to run, terms that are accepted are considered a match.
      `isBinary` - if true, this automaton is already binary and will not go through the UTF32ToUTF8 conversion

  - ### AutomatonQuery

    public AutomatonQuery(Term term, Automaton automaton, boolean isBinary, MultiTermQuery.RewriteMethod rewriteMethod)
    Create a new AutomatonQuery from an `Automaton`.
    Parameters:
      `term` - Term containing field and possibly some pattern structure. The term text is ignored.
      `automaton` - Automaton to run, terms that are accepted are considered a match.
      `isBinary` - if true, this automaton is already binary and will not go through the UTF32ToUTF8 conversion
      `rewriteMethod` - the rewriteMethod to use to build the final query from the automaton

- ## Method Details

  - ### getTermsEnum

    protected TermsEnum getTermsEnum(Terms terms, AttributeSource atts) throws IOException
    Description copied from class: `MultiTermQuery`
    Construct the enumeration to be used, expanding the pattern term. This method should only be called if the field exists (ie, implementations can assume the field does exist). This method should not return null (should instead return `TermsEnum.EMPTY` if no terms match). The TermsEnum must already be positioned to the first matching term. The given `AttributeSource` is passed by the `MultiTermQuery.RewriteMethod` to share information between segments, for example `TopTermsRewrite` uses it to share maximum competitive boosts
    Specified by:
      `getTermsEnum` in class `MultiTermQuery`
    Throws:
      `IOException`

  - ### 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.
    Overrides:
      `hashCode` in class `MultiTermQuery`
    See Also:
      - `Query.equals(Object)`

  - ### equals

    public boolean equals(Object obj)
    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.

    Overrides:
      `equals` in class `MultiTermQuery`
    See Also:
      - `Query.sameClassAs(Object)`
      - `Query.classHash()`

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

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

  - ### getAutomaton

    public Automaton getAutomaton()
    Returns the automaton used to create this query

  - ### getCompiled

    public CompiledAutomaton getCompiled()

  - ### isAutomatonBinary

    public boolean isAutomatonBinary()
    Is this a binary (byte) oriented automaton. See the constructor.

  - ### ramBytesUsed

    public long ramBytesUsed()
    Description copied from interface: `Accountable`
    Returns an estimate of the JVM heap memory used by this object in bytes. The method name uses "ram" for historical reasons; only JVM heap memory should be reported. Off-heap resources such as memory-mapped files or native direct buffers should not be included. Negative values are illegal.
    Specified by:
      `ramBytesUsed` in interface `Accountable`