Explain the internal working of the SpanQuery family?

Most Lucene queries (TermQuery, BooleanQuery) care only about whether and how often terms match - not precisely where relative to each other. SpanQueries are the exception: they operate directly on term positions, matching contiguous or constrained ranges within a document.

Key building blocks include:

• SpanTermQuery - the base case, matching a single term but exposing its position span.
• SpanNearQuery - matches when sub-spans occur within a specified distance of each other, optionally requiring in-order sequence.
• SpanOrQuery - matches if any of several span clauses match.
• SpanNotQuery - excludes matches where one span overlaps another, useful for "match A but not when B is nearby".

Internally, span queries return a Spans iterator per matching document that yields each individual position span rather than just a match/no-match signal, which is what lets them support precise use cases like proximity-aware highlighting or legal/patent search, where exact positional relationships between terms carry real meaning beyond simple term co-occurrence.