Package org.apache.lucene.search

## Class PhraseQuery

- java.lang.Object
- - org.apache.lucene.search.Query
  - - org.apache.lucene.search.PhraseQuery

-     public class PhraseQuery
      extends Query

  A Query that matches documents containing a particular sequence of terms. A PhraseQuery is built by QueryParser for input like `"new york"`.

  This query may be combined with other terms or queries with a `BooleanQuery`.

  NOTE: All terms in the phrase must match, even those at the same position. If you have terms at the same position, perhaps synonyms, you probably want `MultiPhraseQuery` instead which only requires one term at a position to match.
  Also, Leading holes don't have any particular meaning for this query and will be ignored. For instance this query:

       PhraseQuery.Builder builder = new PhraseQuery.Builder();
       builder.add(new Term("body", "one"), 4);
       builder.add(new Term("body", "two"), 5);
       PhraseQuery pq = builder.build();

  is equivalent to the below query:

       PhraseQuery.Builder builder = new PhraseQuery.Builder();
       builder.add(new Term("body", "one"), 0);
       builder.add(new Term("body", "two"), 1);
       PhraseQuery pq = builder.build();

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `static class` | `PhraseQuery.Builder` | A builder for phrase queries.
    `static class` | `PhraseQuery.PostingsAndFreq` | Term postings and position information for phrase matching

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `PhraseQuery​(int slop, String field, String... terms)` | Create a phrase query which will match documents that contain the given list of terms at consecutive positions in `field`, and at a maximum edit distance of `slop`.
    `PhraseQuery​(int slop, String field, BytesRef... terms)` | Create a phrase query which will match documents that contain the given list of terms at consecutive positions in `field`, and at a maximum edit distance of `slop`.
    `PhraseQuery​(String field, String... terms)` | Create a phrase query which will match documents that contain the given list of terms at consecutive positions in `field`.
    `PhraseQuery​(String field, BytesRef... terms)` | Create a phrase query which will match documents that contain the given list of terms at consecutive positions in `field`.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    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)` | Returns true iff `o` is equal to this.
    `String` | `getField()` | Returns the field this query applies to
    `int[]` | `getPositions()` | Returns the relative positions of terms in this phrase.
    `int` | `getSlop()` | Return the slop for this `PhraseQuery`.
    `Term[]` | `getTerms()` | Returns the list of terms in this phrase.
    `int` | `hashCode()` | Returns a hash code value for this object.
    `Query` | `rewrite​(IndexReader reader)` | Expert: called to re-write queries into primitive queries.
    `static float` | `termPositionsCost​(TermsEnum termsEnum)` | Returns an expected cost in simple operations of processing the occurrences of a term in a document that contains the term.
    `String` | `toString​(String f)` | Prints a user-readable version of this query.
    `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`

- - ### Constructor Detail

    - #### PhraseQuery

          public PhraseQuery​(int slop,
                             String field,
                             String... terms)

      Create a phrase query which will match documents that contain the given list of terms at consecutive positions in `field`, and at a maximum edit distance of `slop`. For more complicated use-cases, use `PhraseQuery.Builder`.
      See Also:
        `getSlop()`

    - #### PhraseQuery

          public PhraseQuery​(String field,
                             String... terms)

      Create a phrase query which will match documents that contain the given list of terms at consecutive positions in `field`.

    - #### PhraseQuery

          public PhraseQuery​(int slop,
                             String field,
                             BytesRef... terms)

      Create a phrase query which will match documents that contain the given list of terms at consecutive positions in `field`, and at a maximum edit distance of `slop`. For more complicated use-cases, use `PhraseQuery.Builder`.
      See Also:
        `getSlop()`

    - #### PhraseQuery

          public PhraseQuery​(String field,
                             BytesRef... terms)

      Create a phrase query which will match documents that contain the given list of terms at consecutive positions in `field`.

  - ### Method Detail

    - #### getSlop

          public int getSlop()

      Return the slop for this `PhraseQuery`.

      The slop is an edit distance between respective positions of terms as defined in this `PhraseQuery` and the positions of terms in a document.

      For instance, when searching for `"quick fox"`, it is expected that the difference between the positions of `fox` and `quick` is 1. So `"a quick brown fox"` would be at an edit distance of 1 since the difference of the positions of `fox` and `quick` is 2. Similarly, `"the fox is quick"` would be at an edit distance of 3 since the difference of the positions of `fox` and `quick` is -2. The slop defines the maximum edit distance for a document to match.

      More exact matches are scored higher than sloppier matches, thus search results are sorted by exactness.

    - #### getField

          public String getField()

      Returns the field this query applies to

    - #### getTerms

          public Term[] getTerms()

      Returns the list of terms in this phrase.

    - #### getPositions

          public int[] getPositions()

      Returns the relative positions of terms in this phrase.

    - #### rewrite

          public Query rewrite​(IndexReader reader)
                        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.

      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

    - #### termPositionsCost

          public static float termPositionsCost​(TermsEnum termsEnum)
                                         throws IOException

      Returns an expected cost in simple operations of processing the occurrences of a term in a document that contains the term. This is for use by `TwoPhaseIterator.matchCost()` implementations.
      Parameters:
        `termsEnum` - The term is the term at which this TermsEnum is positioned.
      Throws:
        `IOException`

    - #### 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`
        `scoreMode` - How the produced scorers will be consumed.
        `boost` - The boost that is propagated by the parent queries.
      Throws:
        `IOException`

    - #### toString

          public String toString​(String f)

      Prints a user-readable version of this query.
      Specified by:
        `toString` in class `Query`

    - #### equals

          public boolean equals​(Object other)

      Returns true iff `o` is equal to this.
      Specified by:
        `equals` in class `Query`
      See Also:
        `Query.sameClassAs(Object)`, `Query.classHash()`

    - #### hashCode

          public int hashCode()

      Returns a hash code value for this object.
      Specified by:
        `hashCode` in class `Query`
      See Also:
        `Query.equals(Object)`