Package 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

Modifier and Type	Method	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
static IntervalsSource	containing(IntervalsSource big, IntervalsSource small)	Create a containing IntervalsSource
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
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(CompiledAutomaton ca, int maxExpansions, String pattern)	Expert: Return an IntervalsSource over the disjunction of all terms that are accepted by the given automaton
static IntervalsSource	multiterm(CompiledAutomaton ca, String pattern)	Expert: Return an IntervalsSource over the disjunction of all terms that are accepted by the given automaton
static IntervalsSource	nonOverlapping(IntervalsSource minuend, IntervalsSource subtrahend)	Create a non-overlapping IntervalsSource
static IntervalsSource	notContainedBy(IntervalsSource small, IntervalsSource big)	Create a not-contained-by IntervalsSource
static IntervalsSource	notContaining(IntervalsSource minuend, IntervalsSource subtrahend)	Create a not-containing IntervalsSource
static IntervalsSource	notWithin(IntervalsSource minuend, int positions, IntervalsSource subtrahend)	Create a not-within IntervalsSource
static IntervalsSource	or(boolean rewrite, List<IntervalsSource> subSources)	Return an IntervalsSource over the disjunction of a set of sub-sources
static IntervalsSource	or(boolean rewrite, IntervalsSource... subSources)	Return an IntervalsSource over the disjunction of a set of sub-sources
static IntervalsSource	or(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
static IntervalsSource	ordered(IntervalsSource... subSources)	Create an ordered IntervalsSource
static IntervalsSource	overlapping(IntervalsSource source, IntervalsSource reference)	Returns intervals from a source that overlap with intervals from another source
static IntervalsSource	phrase(String... terms)	Return an IntervalsSource exposing intervals for a phrase consisting of a list of terms
static IntervalsSource	phrase(IntervalsSource... subSources)	Return an IntervalsSource exposing intervals for a phrase consisting of a list of IntervalsSources
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
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	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	unordered(IntervalsSource... subSources)	Create an unordered IntervalsSource
static IntervalsSource	unorderedNoOverlaps(IntervalsSource a, IntervalsSource b)	Create an unordered IntervalsSource allowing no overlaps between subsources
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
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

public static IntervalsSource multiterm(CompiledAutomaton ca,
                                        String pattern)

Expert: Return an IntervalsSource over the disjunction of all terms that are 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 are 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 IntervalsSources

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