org.apache.lucene.queries.intervals (Lucene 10.5.1 queries API)
Description: declaration: package: org.apache.lucene.queries.intervals

# Package org.apache.lucene.queries.intervals

package org.apache.lucene.queries.intervals
Intervals queries

This package contains experimental classes to search over intervals within fields

## IntervalsSource

The `IntervalsSource` class can be used to construct proximity relationships between terms and intervals. They can be built using static methods in the `Intervals` class.

### Basic intervals

- `Intervals.term(String)` — Represents a single term.
- `Intervals.phrase(java.lang.String...)` — Represents a phrase.
- `Intervals.analyzedText(java.lang.String, org.apache.lucene.analysis.Analyzer, java.lang.String, int, boolean)` — Represents a phrase (or an unordered sequence) of tokens resulting from an analysis of a given text.
- `Intervals.ordered(IntervalsSource...)` — Represents an interval over an ordered set of terms or intervals.
- `Intervals.unordered(IntervalsSource...)` — Represents an interval over an unordered set of terms or intervals.
- `Intervals.or(IntervalsSource...)` — Represents the disjunction of a set of terms or intervals.
- `Intervals.wildcard(org.apache.lucene.util.BytesRef)` — Represents an suffix wildcard (any prefix-matching term from the index).

### Filters

- `Intervals.maxwidth(int, IntervalsSource)` — Filters out intervals that are larger than a set width.
- `Intervals.maxgaps(int, IntervalsSource)` — Filters out intervals that have more than a set number of gaps between their constituent sub-intervals.
- `Intervals.containedBy(IntervalsSource, IntervalsSource)` — Returns intervals that are contained by another interval.
- `Intervals.notContainedBy(IntervalsSource, IntervalsSource)` — Returns intervals that are *not* contained by another interval.
- `Intervals.containing(IntervalsSource, IntervalsSource)` — Returns intervals that contain another interval.
- `Intervals.notContaining(IntervalsSource, IntervalsSource)` — Returns intervals that do not contain another interval.
- `Intervals.nonOverlapping(IntervalsSource, IntervalsSource)` — Returns intervals that do not overlap with another interval.
- `Intervals.notWithin(IntervalsSource, int, IntervalsSource)` — Returns intervals that do not appear within a set number of positions of another interval.

The `Intervals` class contains more advanced filters, please refer to the documentation of that class.

## IntervalQuery

An `IntervalQuery` takes a field name and an `IntervalsSource`, and matches all documents that contain intervals defined by the source in that field.

## Interval query support in query parsers

Lucene's `StandardQueryParser` (from the `queryparser` module) supports interval function expressions.

- Related Packages
  Package
  Description
  org.apache.lucene.queries
  Filters and Queries that add to core Lucene.
  org.apache.lucene.queries.function
  Queries that compute score based upon a function.
  org.apache.lucene.queries.mlt
  Document similarity query generators.
  org.apache.lucene.queries.payloads
  The payloads package provides Query mechanisms for finding and using payloads.
  org.apache.lucene.queries.spans
  The calculus of spans.
- Class
  Description
  FilteredIntervalsSource
  An IntervalsSource that filters the intervals from another IntervalsSource
  IntervalFilter
  Wraps an `IntervalIterator` and passes through those intervals that match the `IntervalFilter.accept()` function
  IntervalIterator
  A `DocIdSetIterator` that also allows iteration over matching intervals in a document.
  IntervalMatchesIterator
  An extension of MatchesIterator that allows it to be treated as an IntervalIterator
  IntervalQuery
  A query that retrieves documents containing intervals returned from an `IntervalsSource`
  Intervals
  Factory functions for creating `interval sources`.
  IntervalsSource
  A helper class for `IntervalQuery` that provides an `IntervalIterator` for a given field and segment