org.apache.lucene.queries.intervals

## Class Intervals

- java.lang.Object
- - org.apache.lucene.queries.intervals.Intervals

-     public final class Intervals
      extends Object

  Constructor functions for `IntervalsSource` types These sources implement minimum-interval algorithms taken from the paper Efficient Optimally Lazy Algorithms for Minimal-Interval Semantics By default, sources that are sensitive to internal gaps (e.g. PHRASE and MAXGAPS) will rewrite their sub-sources so that disjunctions of different lengths are pulled up to the top of the interval tree. For example, PHRASE(or(PHRASE("a", "b", "c"), "b"), "c") will automatically rewrite itself to OR(PHRASE("a", "b", "c", "c"), PHRASE("b", "c")) to ensure that documents containing "b c" are matched. This can lead to less efficient queries, as more terms need to be loaded (for example, the "c" iterator above is loaded twice), so if you care more about speed than about accuracy you can use the `or(boolean, IntervalsSource...)` factory method to prevent rewriting.

- - ### Method Summary

    All Methods Static Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `static IntervalsSource` | `after(IntervalsSource source, IntervalsSource reference)` Returns intervals from the source that appear after intervals from the reference
    `static IntervalsSource` | `atLeast(int minShouldMatch, IntervalsSource... sources)` Return intervals that span combinations of intervals from `minShouldMatch` of the sources
    `static IntervalsSource` | `before(IntervalsSource source, IntervalsSource reference)` Returns intervals from the source that appear before intervals from the reference
    `static IntervalsSource` | `containedBy(IntervalsSource small, IntervalsSource big)` Create a contained-by `IntervalsSource` Returns intervals from the small query that appear within intervals of the big query
    `static IntervalsSource` | `containing(IntervalsSource big, IntervalsSource small)` Create a containing `IntervalsSource` Returns intervals from the big source that contain one or more intervals from the small source
    `static IntervalsSource` | `extend(IntervalsSource source, int before, int after)` Create an `IntervalsSource` that wraps another source, extending its intervals by a number of positions before and after.
    `static IntervalsSource` | `fixField(String field, IntervalsSource source)` Create an `IntervalsSource` that always returns intervals from a specific field This is useful for comparing intervals across multiple fields, for example fields that have been analyzed differently, allowing you to search for stemmed terms near unstemmed terms, etc.
    `static IntervalsSource` | `maxgaps(int gaps, IntervalsSource subSource)` Create an `IntervalsSource` that filters a sub-source by its gaps
    `static IntervalsSource` | `maxwidth(int width, IntervalsSource subSource)` Create an `IntervalsSource` that filters a sub-source by the width of its intervals
    `static IntervalsSource` | `multiterm(Automaton automaton, int maxExpansions, String pattern)` Deprecated. use `multiterm(CompiledAutomaton, int, String)`
    `static IntervalsSource` | `multiterm(Automaton automaton, String pattern)` Deprecated. use `multiterm(CompiledAutomaton, String)`
    `static IntervalsSource` | `multiterm(CompiledAutomaton ca, int maxExpansions, String pattern)` Expert: Return an `IntervalsSource` over the disjunction of all terms that's accepted by the given automaton WARNING: Setting `maxExpansions` to higher than the default value of 128 can be both slow and memory-intensive
    `static IntervalsSource` | `multiterm(CompiledAutomaton ca, String pattern)` Expert: Return an `IntervalsSource` over the disjunction of all terms that's accepted by the given automaton
    `static IntervalsSource` | `nonOverlapping(IntervalsSource minuend, IntervalsSource subtrahend)` Create a non-overlapping IntervalsSource Returns intervals of the minuend that do not overlap with intervals from the subtrahend
    `static IntervalsSource` | `notContainedBy(IntervalsSource small, IntervalsSource big)` Create a not-contained-by `IntervalsSource` Returns intervals from the small `IntervalsSource` that do not appear within intervals from the big `IntervalsSource`.
    `static IntervalsSource` | `notContaining(IntervalsSource minuend, IntervalsSource subtrahend)` Create a not-containing `IntervalsSource` Returns intervals from the minuend that do not contain intervals of the subtrahend
    `static IntervalsSource` | `notWithin(IntervalsSource minuend, int positions, IntervalsSource subtrahend)` Create a not-within `IntervalsSource` Returns intervals of the minuend that do not appear within a set number of positions of intervals from the subtrahend query
    `static IntervalsSource` | `or(boolean rewrite, IntervalsSource... subSources)` Return an `IntervalsSource` over the disjunction of a set of sub-sources
    `static IntervalsSource` | `or(boolean rewrite, List<IntervalsSource> subSources)` Return an `IntervalsSource` over the disjunction of a set of sub-sources
    `static IntervalsSource` | `or(IntervalsSource... subSources)` Return an `IntervalsSource` over the disjunction of a set of sub-sources Automatically rewrites if wrapped by an interval source that is sensitive to internal gaps
    `static IntervalsSource` | `or(List<IntervalsSource> subSources)` Return an `IntervalsSource` over the disjunction of a set of sub-sources
    `static IntervalsSource` | `ordered(IntervalsSource... subSources)` Create an ordered `IntervalsSource` Returns intervals in which the subsources all appear in the given order
    `static IntervalsSource` | `overlapping(IntervalsSource source, IntervalsSource reference)` Returns intervals from a source that overlap with intervals from another source
    `static IntervalsSource` | `phrase(IntervalsSource... subSources)` Return an `IntervalsSource` exposing intervals for a phrase consisting of a list of IntervalsSources
    `static IntervalsSource` | `phrase(String... terms)` Return an `IntervalsSource` exposing intervals for a phrase consisting of a list of terms
    `static IntervalsSource` | `prefix(BytesRef prefix)` Return an `IntervalsSource` over the disjunction of all terms that begin with a prefix
    `static IntervalsSource` | `prefix(BytesRef prefix, int maxExpansions)` Expert: Return an `IntervalsSource` over the disjunction of all terms that begin with a prefix WARNING: Setting `maxExpansions` to higher than the default value of 128 can be both slow and memory-intensive
    `static IntervalsSource` | `term(BytesRef term)` Return an `IntervalsSource` exposing intervals for a term
    `static IntervalsSource` | `term(BytesRef term, Predicate<BytesRef> payloadFilter)` Return an `IntervalsSource` exposing intervals for a term, filtered by the value of the term's payload at each position
    `static IntervalsSource` | `term(String term)` Return an `IntervalsSource` exposing intervals for a term
    `static IntervalsSource` | `term(String term, Predicate<BytesRef> payloadFilter)` Return an `IntervalsSource` exposing intervals for a term, filtered by the value of the term's payload at each position
    `static IntervalsSource` | `unordered(IntervalsSource... subSources)` Create an unordered `IntervalsSource` Returns intervals in which all the subsources appear.
    `static IntervalsSource` | `unorderedNoOverlaps(IntervalsSource a, IntervalsSource b)` Create an unordered `IntervalsSource` allowing no overlaps between subsources Returns intervals in which both the subsources appear and do not overlap.
    `static IntervalsSource` | `wildcard(BytesRef wildcard)` Return an `IntervalsSource` over the disjunction of all terms that match a wildcard glob
    `static IntervalsSource` | `wildcard(BytesRef wildcard, int maxExpansions)` Expert: Return an `IntervalsSource` over the disjunction of all terms that match a wildcard glob WARNING: Setting `maxExpansions` to higher than the default value of 128 can be both slow and memory-intensive
    `static IntervalsSource` | `within(IntervalsSource source, int positions, IntervalsSource reference)` Returns intervals of the source that appear within a set number of positions of intervals from the reference

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

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

- - ### Method Detail

    - #### term

          public static IntervalsSource term(BytesRef term)

      Return an `IntervalsSource` exposing intervals for a term

    - #### term

          public static IntervalsSource term(String term)

      Return an `IntervalsSource` exposing intervals for a term

    - #### term

          public static IntervalsSource term(String term,
                                             Predicate<BytesRef> payloadFilter)

      Return an `IntervalsSource` exposing intervals for a term, filtered by the value of the term's payload at each position

    - #### term

          public static IntervalsSource term(BytesRef term,
                                             Predicate<BytesRef> payloadFilter)

      Return an `IntervalsSource` exposing intervals for a term, filtered by the value of the term's payload at each position

    - #### phrase

          public static IntervalsSource phrase(String... terms)

      Return an `IntervalsSource` exposing intervals for a phrase consisting of a list of terms

    - #### phrase

          public static IntervalsSource phrase(IntervalsSource... subSources)

      Return an `IntervalsSource` exposing intervals for a phrase consisting of a list of IntervalsSources

    - #### or

          public static IntervalsSource or(IntervalsSource... subSources)

      Return an `IntervalsSource` over the disjunction of a set of sub-sources Automatically rewrites if wrapped by an interval source that is sensitive to internal gaps

    - #### or

          public static IntervalsSource or(boolean rewrite,
                                           IntervalsSource... subSources)

      Return an `IntervalsSource` over the disjunction of a set of sub-sources
      Parameters:
        `rewrite` - if `false`, do not rewrite intervals that are sensitive to internal gaps; this may run more efficiently, but can miss valid hits due to minimization
        `subSources` - the sources to combine

    - #### or

          public static IntervalsSource or(List<IntervalsSource> subSources)

      Return an `IntervalsSource` over the disjunction of a set of sub-sources

    - #### or

          public static IntervalsSource or(boolean rewrite,
                                           List<IntervalsSource> subSources)

      Return an `IntervalsSource` over the disjunction of a set of sub-sources
      Parameters:
        `rewrite` - if `false`, do not rewrite intervals that are sensitive to internal gaps; this may run more efficiently, but can miss valid hits due to minimization
        `subSources` - the sources to combine

    - #### prefix

          public static IntervalsSource prefix(BytesRef prefix)

      Return an `IntervalsSource` over the disjunction of all terms that begin with a prefix
      Throws:
        `IllegalStateException` - if the prefix expands to more than 128 terms

    - #### prefix

          public static IntervalsSource prefix(BytesRef prefix,
                                               int maxExpansions)

      Expert: Return an `IntervalsSource` over the disjunction of all terms that begin with a prefix WARNING: Setting `maxExpansions` to higher than the default value of 128 can be both slow and memory-intensive
      Parameters:
        `prefix` - the prefix to expand
        `maxExpansions` - the maximum number of terms to expand to
      Throws:
        `IllegalStateException` - if the prefix expands to more than `maxExpansions` terms

    - #### wildcard

          public static IntervalsSource wildcard(BytesRef wildcard)

      Return an `IntervalsSource` over the disjunction of all terms that match a wildcard glob
      Throws:
        `IllegalStateException` - if the wildcard glob expands to more than 128 terms
      See Also:
        `for glob format`

    - #### wildcard

          public static IntervalsSource wildcard(BytesRef wildcard,
                                                 int maxExpansions)

      Expert: Return an `IntervalsSource` over the disjunction of all terms that match a wildcard glob WARNING: Setting `maxExpansions` to higher than the default value of 128 can be both slow and memory-intensive
      Parameters:
        `wildcard` - the glob to expand
        `maxExpansions` - the maximum number of terms to expand to
      Throws:
        `IllegalStateException` - if the wildcard glob expands to more than `maxExpansions` terms
      See Also:
        `for glob format`

    - #### multiterm

          @Deprecated
          public static IntervalsSource multiterm(Automaton automaton,
                                                              String pattern)

      Deprecated. use `multiterm(CompiledAutomaton, String)`
      Expert: Return an `IntervalsSource` over the disjunction of all terms that's accepted by the given automaton
      Parameters:
        `automaton` - accepts terms for to expand to
        `pattern` - string representation of the given automaton, mostly used in exception messages
      Throws:
        `IllegalStateException` - if the automaton accepts more than 128 terms

    - #### multiterm

          @Deprecated
          public static IntervalsSource multiterm(Automaton automaton,
                                                              int maxExpansions,
                                                              String pattern)

      Deprecated. use `multiterm(CompiledAutomaton, int, String)`
      Expert: Return an `IntervalsSource` over the disjunction of all terms that's accepted by the given automaton WARNING: Setting `maxExpansions` to higher than the default value of 128 can be both slow and memory-intensive
      Parameters:
        `automaton` - accepts terms for to expand to
        `maxExpansions` - the maximum number of terms to expand to
        `pattern` - string representation of the given automaton, mostly used in exception messages
      Throws:
        `IllegalStateException` - if the automaton accepts more than `maxExpansions` terms

    - #### multiterm

          public static IntervalsSource multiterm(CompiledAutomaton ca,
                                                  String pattern)

      Expert: Return an `IntervalsSource` over the disjunction of all terms that's accepted by the given automaton
      Parameters:
        `ca` - an automaton accepting matching terms
        `pattern` - string representation of the given automaton, mostly used in exception messages
      Throws:
        `IllegalStateException` - if the automaton accepts more than 128 terms

    - #### multiterm

          public static IntervalsSource multiterm(CompiledAutomaton ca,
                                                  int maxExpansions,
                                                  String pattern)

      Expert: Return an `IntervalsSource` over the disjunction of all terms that's accepted by the given automaton WARNING: Setting `maxExpansions` to higher than the default value of 128 can be both slow and memory-intensive
      Parameters:
        `ca` - an automaton accepting matching terms
        `maxExpansions` - the maximum number of terms to expand to
        `pattern` - string representation of the given automaton, mostly used in exception messages
      Throws:
        `IllegalStateException` - if the automaton accepts more than `maxExpansions` terms

    - #### maxwidth

          public static IntervalsSource maxwidth(int width,
                                                 IntervalsSource subSource)

      Create an `IntervalsSource` that filters a sub-source by the width of its intervals
      Parameters:
        `width` - the maximum width of intervals in the sub-source to filter
        `subSource` - the sub-source to filter

    - #### maxgaps

          public static IntervalsSource maxgaps(int gaps,
                                                IntervalsSource subSource)

      Create an `IntervalsSource` that filters a sub-source by its gaps
      Parameters:
        `gaps` - the maximum number of gaps in the sub-source to filter
        `subSource` - the sub-source to filter

    - #### extend

          public static IntervalsSource extend(IntervalsSource source,
                                               int before,
                                               int after)

      Create an `IntervalsSource` that wraps another source, extending its intervals by a number of positions before and after. This can be useful for adding defined gaps in a block query; for example, to find 'a b [2 arbitrary terms] c', you can call:

             Intervals.phrase(Intervals.term("a"), Intervals.extend(Intervals.term("b"), 0, 2), Intervals.term("c"));

      Note that calling `IntervalIterator.gaps()` on iterators returned by this source delegates directly to the wrapped iterator, and does not include the extensions.
      Parameters:
        `source` - the source to extend
        `before` - how many positions to extend before the delegated interval
        `after` - how many positions to extend after the delegated interval

    - #### ordered

          public static IntervalsSource ordered(IntervalsSource... subSources)

      Create an ordered `IntervalsSource` Returns intervals in which the subsources all appear in the given order
      Parameters:
        `subSources` - an ordered set of `IntervalsSource` objects

    - #### unordered

          public static IntervalsSource unordered(IntervalsSource... subSources)

      Create an unordered `IntervalsSource` Returns intervals in which all the subsources appear. The subsources may overlap
      Parameters:
        `subSources` - an unordered set of `IntervalsSource`s

    - #### unorderedNoOverlaps

          public static IntervalsSource unorderedNoOverlaps(IntervalsSource a,
                                                            IntervalsSource b)

      Create an unordered `IntervalsSource` allowing no overlaps between subsources Returns intervals in which both the subsources appear and do not overlap.

    - #### fixField

          public static IntervalsSource fixField(String field,
                                                 IntervalsSource source)

      Create an `IntervalsSource` that always returns intervals from a specific field This is useful for comparing intervals across multiple fields, for example fields that have been analyzed differently, allowing you to search for stemmed terms near unstemmed terms, etc.

    - #### nonOverlapping

          public static IntervalsSource nonOverlapping(IntervalsSource minuend,
                                                       IntervalsSource subtrahend)

      Create a non-overlapping IntervalsSource Returns intervals of the minuend that do not overlap with intervals from the subtrahend
      Parameters:
        `minuend` - the `IntervalsSource` to filter
        `subtrahend` - the `IntervalsSource` to filter by

    - #### overlapping

          public static IntervalsSource overlapping(IntervalsSource source,
                                                    IntervalsSource reference)

      Returns intervals from a source that overlap with intervals from another source
      Parameters:
        `source` - the source to filter
        `reference` - the source to filter by

    - #### notWithin

          public static IntervalsSource notWithin(IntervalsSource minuend,
                                                  int positions,
                                                  IntervalsSource subtrahend)

      Create a not-within `IntervalsSource` Returns intervals of the minuend that do not appear within a set number of positions of intervals from the subtrahend query
      Parameters:
        `minuend` - the `IntervalsSource` to filter
        `positions` - the minimum distance that intervals from the minuend may occur from intervals of the subtrahend
        `subtrahend` - the `IntervalsSource` to filter by

    - #### within

          public static IntervalsSource within(IntervalsSource source,
                                               int positions,
                                               IntervalsSource reference)

      Returns intervals of the source that appear within a set number of positions of intervals from the reference
      Parameters:
        `source` - the `IntervalsSource` to filter
        `positions` - the maximum distance that intervals of the source may occur from intervals of the reference
        `reference` - the `IntervalsSource` to filter by

    - #### notContaining

          public static IntervalsSource notContaining(IntervalsSource minuend,
                                                      IntervalsSource subtrahend)

      Create a not-containing `IntervalsSource` Returns intervals from the minuend that do not contain intervals of the subtrahend
      Parameters:
        `minuend` - the `IntervalsSource` to filter
        `subtrahend` - the `IntervalsSource` to filter by

    - #### containing

          public static IntervalsSource containing(IntervalsSource big,
                                                   IntervalsSource small)

      Create a containing `IntervalsSource` Returns intervals from the big source that contain one or more intervals from the small source
      Parameters:
        `big` - the `IntervalsSource` to filter
        `small` - the `IntervalsSource` to filter by

    - #### notContainedBy

          public static IntervalsSource notContainedBy(IntervalsSource small,
                                                       IntervalsSource big)

      Create a not-contained-by `IntervalsSource` Returns intervals from the small `IntervalsSource` that do not appear within intervals from the big `IntervalsSource`.
      Parameters:
        `small` - the `IntervalsSource` to filter
        `big` - the `IntervalsSource` to filter by

    - #### containedBy

          public static IntervalsSource containedBy(IntervalsSource small,
                                                    IntervalsSource big)

      Create a contained-by `IntervalsSource` Returns intervals from the small query that appear within intervals of the big query
      Parameters:
        `small` - the `IntervalsSource` to filter
        `big` - the `IntervalsSource` to filter by

    - #### atLeast

          public static IntervalsSource atLeast(int minShouldMatch,
                                                IntervalsSource... sources)

      Return intervals that span combinations of intervals from `minShouldMatch` of the sources

    - #### before

          public static IntervalsSource before(IntervalsSource source,
                                               IntervalsSource reference)

      Returns intervals from the source that appear before intervals from the reference

    - #### after

          public static IntervalsSource after(IntervalsSource source,
                                              IntervalsSource reference)

      Returns intervals from the source that appear after intervals from the reference

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