nl.inl.blacklab.search.lucene

Class BLSpanQuery

java.lang.Object

org.apache.lucene.search.Query

org.apache.lucene.search.spans.SpanQuery

nl.inl.blacklab.search.lucene.BLSpanQuery

All Implemented Interfaces:

Cloneable

Direct Known Subclasses:

BLSpanMultiTermQueryWrapper, BLSpanOrQuery, BLSpanTermQuery, MockSpanQuery, SpanFuzzyQuery, SpanQueryAndNot, SpanQueryAnyToken, SpanQueryCaptureGroup, SpanQueryConstrained, SpanQueryEdge, SpanQueryExpansion, SpanQueryFiltered, SpanQueryFilterNGrams, SpanQueryFiSeq, SpanQueryNoHits, SpanQueryNot, SpanQueryPositionFilter, SpanQueryRepetition, SpanQuerySequence, SpanQueryTags

public abstract class BLSpanQuery
extends org.apache.lucene.search.spans.SpanQuery

A required interface for a BlackLab SpanQuery. All our queries must be derived from this so we know they will produce BLSpans (which contains extra methods for optimization).

Field Summary

Fields

Modifier and Type	Field and Description
static int	MAX_UNLIMITED

Constructor Summary

Constructors

Constructor and Description
BLSpanQuery()

Method Summary

Modifier and Type	Method and Description
static int	addMaxValues(int a, int b) Add two values for maximum number of repetitions, taking "infinite" into account.
boolean	canInternalizeNeighbour(BLSpanQuery clause, boolean onTheRight) Can this query "internalize" the given neighbouring clause? Internalizing means adding the clause to its children, which is often more efficient because we create longer sequences that match fewer hits and may themselves be further optimized.
boolean	canMakeNfa()
abstract BLSpanWeight	createWeight(org.apache.lucene.search.IndexSearcher searcher, boolean needsScores)
static BLSpanQuery	ensureSorted(BLSpanQuery spanQuery)
static BLSpanQuery	ensureSortedUnique(BLSpanQuery spanQuery)
abstract boolean	equals(Object obj)
abstract int	forwardMatchingCost() Return an (very rough) indication of how expensive finding a match for this query using an NFA would be.
String	getField()
Nfa	getNfa(ForwardIndexAccessor fiAccessor, int direction)
NfaTwoWay	getNfaTwoWay(ForwardIndexAccessor fiAccessor, int nativeDirection)
abstract String	getRealField()
abstract int	hashCode()
abstract boolean	hitsAllSameLength() Do our hits have constant length?
abstract boolean	hitsAreUnique() Is it guaranteed that no two hits have the same start and end position?
abstract boolean	hitsEndPointSorted() When hit B follows hit A, is it guaranteed that B.end >= A.end? Also, if A.end == B.end, is B.start > A.start?
abstract boolean	hitsHaveUniqueEnd() Is it guaranteed that no two hits have the same end position?
abstract boolean	hitsHaveUniqueStart() Is it guaranteed that no two hits have the same start position?
abstract int	hitsLengthMax() How long could our longest hit be?
abstract int	hitsLengthMin() How long could our shortest hit be?
abstract boolean	hitsStartPointSorted() When hit B follows hit A, is it guaranteed that B.start >= A.start? Also, if A.start == B.start, is B.end > A.end?
static String	inf(int max)
BLSpanQuery	internalizeNeighbour(BLSpanQuery clause, boolean onTheRight) Internalize the given clause.
BLSpanQuery	inverted() Return an inverted version of this query.
boolean	isSingleTokenNot() Is this query only a negative clause, producing all tokens that don't satisfy certain conditions? Used for optimization decisions, i.e.
void	log(LogLevel level, String msg)
boolean	matchesEmptySequence() Does this query match the empty sequence? For example, the query [word="cow"]* matches the empty sequence.
BLSpanQuery	optimize(org.apache.lucene.index.IndexReader reader) Called before rewrite() to optimize certain parts of the query before they are rewritten (e.g.
boolean	producesSingleTokens() Are all our hits single tokens?
abstract long	reverseMatchingCost(org.apache.lucene.index.IndexReader reader) Return an (very rough) indication of how many hits this clause might return.
abstract BLSpanQuery	rewrite(org.apache.lucene.index.IndexReader reader)
void	setQueryInfo(QueryInfo queryInfo)
abstract String	toString(String field)
static BLSpanQuery	wrap(org.apache.lucene.search.spans.SpanQuery spanQuery) Rewrite a SpanQuery after rewrite() to a BLSpanQuery equivalent.

Methods inherited from class org.apache.lucene.search.spans.SpanQuery

getTermContexts, getTermContexts

Methods inherited from class org.apache.lucene.search.Query

clone, getBoost, setBoost, toString

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

MAX_UNLIMITED

public static final int MAX_UNLIMITED

See Also:

Constant Field Values

Constructor Detail

BLSpanQuery

public BLSpanQuery()

Method Detail

wrap

public static BLSpanQuery wrap(org.apache.lucene.search.spans.SpanQuery spanQuery)

Rewrite a SpanQuery after rewrite() to a BLSpanQuery equivalent. This is used for BLSpanOrQuery and BLSpanMultiTermQueryWrapper: we let Lucene rewrite these for us, but the result needs to be BL-ified so we know we'll get BLSpans (which contain extra methods for optimization).

Parameters:

spanQuery - the SpanQuery to BL-ify (if it isn't a BLSpanQuery already)

Returns:

resulting BLSpanQuery, or the input query if it was one already

addMaxValues

public static int addMaxValues(int a,
                               int b)

Add two values for maximum number of repetitions, taking "infinite" into account. -1 or Integer.MAX_VALUE means infinite. Adding infinite to any other value produces infinite again (-1 if either value is -1; otherwise, Integer.MAX_VALUE if either value is Integer.MAX_VALUE).

Parameters:

a - first max. repetitions value

b - first max. repetitions value

Returns:

sum of the max. repetitions values

ensureSortedUnique

public static BLSpanQuery ensureSortedUnique(BLSpanQuery spanQuery)

ensureSorted

public static BLSpanQuery ensureSorted(BLSpanQuery spanQuery)

inf

public static String inf(int max)

toString

public abstract String toString(String field)

Specified by:

toString in class org.apache.lucene.search.Query

hashCode

public abstract int hashCode()

Overrides:

hashCode in class org.apache.lucene.search.Query

equals

public abstract boolean equals(Object obj)

Overrides:

equals in class org.apache.lucene.search.Query

optimize

public BLSpanQuery optimize(org.apache.lucene.index.IndexReader reader)
                     throws IOException

Called before rewrite() to optimize certain parts of the query before they are rewritten (e.g. match regex terms using NFA instead of OR). For now, only SpanQuerySequence overrides this to make sure certain clause combinations are performed before rewrite().

Parameters:

reader - index reader

Returns:

optimized query

Throws:

IOException - on error

rewrite

public abstract BLSpanQuery rewrite(org.apache.lucene.index.IndexReader reader)
                             throws IOException

Overrides:

rewrite in class org.apache.lucene.search.spans.SpanQuery

Throws:

IOException

createWeight

public abstract BLSpanWeight createWeight(org.apache.lucene.search.IndexSearcher searcher,
                                          boolean needsScores)
                                   throws IOException

Overrides:

createWeight in class org.apache.lucene.search.spans.SpanQuery

Throws:

IOException

matchesEmptySequence

public boolean matchesEmptySequence()

Does this query match the empty sequence? For example, the query [word="cow"]* matches the empty sequence. We need to know this so we can rewrite to the appropriate queries. A query of the form "AB*" would be translated into "A|AB+", so each component of the query actually generates non-empty matches. We default to no because most queries don't match the empty sequence.

Returns:

true if this query matches the empty sequence, false otherwise

inverted

public BLSpanQuery inverted()

Return an inverted version of this query.

Returns:

the inverted query

isSingleTokenNot

public boolean isSingleTokenNot()

Is this query only a negative clause, producing all tokens that don't satisfy certain conditions? Used for optimization decisions, i.e. in BLSpanOrQuery.rewrite().

Returns:

true if it's negative-only, false if not

producesSingleTokens

public boolean producesSingleTokens()

Are all our hits single tokens?

Returns:

true if they are, false if not

hitsAllSameLength

public abstract boolean hitsAllSameLength()

Do our hits have constant length?

Returns:

true if they do, false if not

hitsLengthMin

public abstract int hitsLengthMin()

How long could our shortest hit be?

Returns:

length of the shortest hit possible

hitsLengthMax

public abstract int hitsLengthMax()

How long could our longest hit be?

Returns:

length of the longest hit possible, or Integer.MAX_VALUE if unlimited

hitsEndPointSorted

public abstract boolean hitsEndPointSorted()

When hit B follows hit A, is it guaranteed that B.end >= A.end? Also, if A.end == B.end, is B.start > A.start?

Returns:

true if this is guaranteed, false if not

hitsStartPointSorted

public abstract boolean hitsStartPointSorted()

When hit B follows hit A, is it guaranteed that B.start >= A.start? Also, if A.start == B.start, is B.end > A.end?

Returns:

true if this is guaranteed, false if not

hitsHaveUniqueStart

public abstract boolean hitsHaveUniqueStart()

Is it guaranteed that no two hits have the same start position?

Returns:

true if this is guaranteed, false if not

hitsHaveUniqueEnd

public abstract boolean hitsHaveUniqueEnd()

Is it guaranteed that no two hits have the same end position?

Returns:

true if this is guaranteed, false if not

hitsAreUnique

public abstract boolean hitsAreUnique()

Is it guaranteed that no two hits have the same start and end position?

Returns:

true if this is guaranteed, false if not

canInternalizeNeighbour

public boolean canInternalizeNeighbour(BLSpanQuery clause,
                                       boolean onTheRight)

Can this query "internalize" the given neighbouring clause? Internalizing means adding the clause to its children, which is often more efficient because we create longer sequences that match fewer hits and may themselves be further optimized. An example is SpanQueryPosFilter, which can be combined with fixed-length neighbouring clauses (updating the SpanQueryPosFilters' left or right adjustment setting to match) to reduce the number of hits that have to be filter.

Parameters:

clause - clause we want to internalize

onTheRight - if true, clause is a right neighbour of this query; if false, a left neighbour

Returns:

true iff clause can be internalized

internalizeNeighbour

public BLSpanQuery internalizeNeighbour(BLSpanQuery clause,
                                        boolean onTheRight)

Internalize the given clause. See canInternalizeNeighbour() for more information.

Parameters:

clause - clause we want to internalize

onTheRight - if true, clause is a right neighbour of this query; if false, a left neighbour

Returns:

new query with clause internalized

getNfa

public Nfa getNfa(ForwardIndexAccessor fiAccessor,
                  int direction)

canMakeNfa

public boolean canMakeNfa()

getNfaTwoWay

public NfaTwoWay getNfaTwoWay(ForwardIndexAccessor fiAccessor,
                              int nativeDirection)

reverseMatchingCost

public abstract long reverseMatchingCost(org.apache.lucene.index.IndexReader reader)

Return an (very rough) indication of how many hits this clause might return. Used to decide what parts of the query to match using the forward index. Based on term frequency, which are combined using simple rules of thumb. Another way to think of this is an indication of how much computation this clause will require when matching using the reverse index.

Parameters:

reader - the index reader

Returns:

rough estimation of the number of hits

forwardMatchingCost

public abstract int forwardMatchingCost()

Return an (very rough) indication of how expensive finding a match for this query using an NFA would be. Used to decide what parts of the query to match using the forward index.

Returns:

rough estimation of the NFA complexity

getField

public String getField()

Specified by:

getField in class org.apache.lucene.search.spans.SpanQuery

getRealField

public abstract String getRealField()

setQueryInfo

public void setQueryInfo(QueryInfo queryInfo)

log

public void log(LogLevel level,
                String msg)