nl.inl.blacklab.search

Interface BlackLabIndex

All Superinterfaces:

AutoCloseable, Closeable

All Known Subinterfaces:

BlackLabIndexWriter

All Known Implementing Classes:

BlackLabIndexImpl, MockBlackLabIndex

public interface BlackLabIndex
extends Closeable

Method Summary

Modifier and Type	Method and Description
org.apache.lucene.analysis.Analyzer	analyzer() Get the analyzer for indexing and searching.
default AnnotatedField	annotatedField(String fieldName)
default AnnotatedFields	annotatedFields()
AnnotationForwardIndex	annotationForwardIndex(Annotation annotation) Tries to get the ForwardIndex object for the specified fieldname.
BlackLabEngine	blackLab() Get the BlackLab instance that created us.
SearchCache	cache()
void	close() Finalize the index object.
Collator	collator() Get the collator being used for sorting.
ContentAccessor	contentAccessor(Field field) Get the content accessor for a field.
BLSpanQuery	createSpanQuery(QueryInfo queryInfo, TextPattern pattern, org.apache.lucene.search.Query filter)
ContextSize	defaultContextSize() Get the default context size.
QueryExecutionContext	defaultExecutionContext(AnnotatedField field) Get the default initial query execution context.
MatchSensitivity	defaultMatchSensitivity()
XmlHighlighter.UnbalancedTagsStrategy	defaultUnbalancedTagsStrategy() How do we fix well-formedness for snippets of XML?
Doc	doc(int docId) Get a BlackLab document.
boolean	docExists(int docId) Is the document id in range, and not a deleted document?
boolean	equals(Object obj)
default QueryExplanation	explain(BLSpanQuery query) Explain how a SpanQuery is rewritten to an optimized version to be executed by Lucene.
QueryExplanation	explain(BLSpanQuery query, SearchLogger searchLogger) Explain how a SpanQuery is rewritten to an optimized version to be executed by Lucene.
default QueryExplanation	explain(QueryInfo queryInfo, TextPattern pattern, org.apache.lucene.search.Query filter) Explain how a TextPattern is converted to a SpanQuery and rewritten to an optimized version to be executed by Lucene.
default Field	field(String fieldName) Get a field (either an annotated or a metadata field).
default Hits	find(BLSpanQuery query, SearchSettings settings) Find hits for a pattern in a field.
Hits	find(BLSpanQuery query, SearchSettings settings, SearchLogger searchLogger) Find hits for a pattern in a field.
default Hits	find(QueryInfo queryInfo, TextPattern pattern, org.apache.lucene.search.Query filter, SearchSettings settings) Find hits for a pattern in a field.
default Hits	find(TextPattern pattern, AnnotatedField field, org.apache.lucene.search.Query filter) Deprecated. use version that takes a QueryInfo
default Hits	find(TextPattern pattern, org.apache.lucene.search.Query filter) Deprecated. use version that takes a QueryInfo
void	forEachDocument(DocTask task) Perform a task on each (non-deleted) Lucene Document.
ForwardIndex	forwardIndex(AnnotatedField field) Get forward index for the specified annotated field.
int	hashCode()
File	indexDirectory() Get the index directory.
boolean	indexMode() Are we running in index mode?
boolean	isEmpty() Is this a newly created, empty index?
static boolean	isIndex(File indexDir) Does the specified directory contain a BlackLab index?
default AnnotatedField	mainAnnotatedField()
IndexMetadata	metadata() Get information about the structure of the BlackLab index.
default MetadataField	metadataField(String fieldName)
default MetadataFields	metadataFields()
String	name() Get the index name.
static BlackLabIndex	open(BlackLabEngine blackLab, File indexDir) Open an index for reading ("search mode").
static BlackLabIndex	open(File indexDir) Deprecated. use BlackLab.open()
default DocResults	queryDocuments(org.apache.lucene.search.Query documentFilterQuery) Perform a document query only (no hits)
DocResults	queryDocuments(org.apache.lucene.search.Query documentFilterQuery, SearchLogger searchLogger) Perform a document query only (no hits)
org.apache.lucene.index.IndexReader	reader() Get the Lucene index reader we're using.
default SearchEmpty	search() Start building a Search.
default SearchEmpty	search(AnnotatedField field) Start building a Search.
default SearchEmpty	search(AnnotatedField field, boolean useCache) Start building a Search.
SearchEmpty	search(AnnotatedField field, boolean useCache, SearchLogger searchLogger) Start building a Search.
org.apache.lucene.search.IndexSearcher	searcher()
SearchSettings	searchSettings() The default settings for all new Hits objects.
void	setCache(SearchCache cache) Set the object BlackLab should use as cache.
void	setCollator(Collator collator) Set the collator used for sorting.
void	setDefaultContextSize(ContextSize size) Set the default context size.
void	setDefaultMatchSensitivity(MatchSensitivity m) Set the default sensitivity for queries.
void	setDefaultUnbalancedTagsStrategy(XmlHighlighter.UnbalancedTagsStrategy strategy) Set how to fix well-formedness for snippets of XML.
void	setSearchSettings(SearchSettings settings) Set the maximum number of hits to process/count.
TermFrequencyList	termFrequencies(AnnotationSensitivity annotSensitivity, org.apache.lucene.search.Query filterQuery, Set<String> terms) Determine the term frequencies for an annotation sensitivity.

Method Detail

isIndex

static boolean isIndex(File indexDir)

Does the specified directory contain a BlackLab index?

Parameters:

indexDir - the directory

Returns:

true if it's a BlackLab index, false if not.

open

static BlackLabIndex open(BlackLabEngine blackLab,
                          File indexDir)
                   throws ErrorOpeningIndex

Open an index for reading ("search mode").

Parameters:

blackLab - our BlackLab instance

indexDir - the index directory

settings - default search settings

Returns:

index object

Throws:

ErrorOpeningIndex - on any error

open

@Deprecated
static BlackLabIndex open(File indexDir)
                               throws ErrorOpeningIndex

Deprecated. use BlackLab.open()

Open an index for reading ("search mode").

Parameters:

indexDir - the index directory

Returns:

index object

Throws:

ErrorOpeningIndex - on any error

equals

boolean equals(Object obj)

Overrides:

equals in class Object

hashCode

int hashCode()

Overrides:

hashCode in class Object

close

void close()

Finalize the index object. This closes the IndexSearcher and (depending on the constructor used) may also close the index reader.

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable

isEmpty

boolean isEmpty()

Is this a newly created, empty index?

Returns:

true if it is, false if not

docExists

boolean docExists(int docId)

Is the document id in range, and not a deleted document?

Parameters:

docId - document id to check

Returns:

true if it is an existing document

doc

Doc doc(int docId)

Get a BlackLab document.

Parameters:

docId - document id

Returns:

document

forEachDocument

void forEachDocument(DocTask task)

Perform a task on each (non-deleted) Lucene Document.

Parameters:

task - task to perform

createSpanQuery

BLSpanQuery createSpanQuery(QueryInfo queryInfo,
                            TextPattern pattern,
                            org.apache.lucene.search.Query filter)
                     throws InvalidQuery

Throws:

InvalidQuery

find

default Hits find(BLSpanQuery query,
                  SearchSettings settings)
           throws WildcardTermTooBroad

Find hits for a pattern in a field.

Parameters:

query - the pattern to find

settings - search settings, or null for default

Returns:

the hits found

Throws:

WildcardTermTooBroad - if a wildcard or regular expression term is overly broad

find

Hits find(BLSpanQuery query,
          SearchSettings settings,
          SearchLogger searchLogger)
   throws WildcardTermTooBroad

Find hits for a pattern in a field.

Parameters:

query - the pattern to find

settings - search settings, or null for default

searchLogger - where to log details about query execution

Returns:

the hits found

Throws:

WildcardTermTooBroad - if a wildcard or regular expression term is overly broad

find

default Hits find(QueryInfo queryInfo,
                  TextPattern pattern,
                  org.apache.lucene.search.Query filter,
                  SearchSettings settings)
           throws InvalidQuery

Find hits for a pattern in a field.

Parameters:

queryInfo - information about the query: field, logger

pattern - the pattern to find

filter - determines which documents to search

settings - search settings, or null for default

Returns:

the hits found

Throws:

WildcardTermTooBroad - if a wildcard or regular expression term is overly broad

InvalidQuery

find

@Deprecated
default Hits find(TextPattern pattern,
                              AnnotatedField field,
                              org.apache.lucene.search.Query filter)
                       throws InvalidQuery

Deprecated. use version that takes a QueryInfo

Find hits for a pattern in a field.

Parameters:

pattern - the pattern to find

field - field to find pattern in

filter - determines which documents to search

settings - search settings, or null for default

Returns:

the hits found

Throws:

WildcardTermTooBroad - if a wildcard or regular expression term is overly broad

InvalidQuery

find

@Deprecated
default Hits find(TextPattern pattern,
                              org.apache.lucene.search.Query filter)
                       throws InvalidQuery

Deprecated. use version that takes a QueryInfo

Find hits for a pattern in a field.

Parameters:

pattern - the pattern to find

field - field to find pattern in

filter - determines which documents to search

settings - search settings, or null for default

Returns:

the hits found

Throws:

WildcardTermTooBroad - if a wildcard or regular expression term is overly broad

InvalidQuery

queryDocuments

default DocResults queryDocuments(org.apache.lucene.search.Query documentFilterQuery)

Perform a document query only (no hits)

Parameters:

documentFilterQuery - the document-level query

Returns:

the matching documents

queryDocuments

DocResults queryDocuments(org.apache.lucene.search.Query documentFilterQuery,
                          SearchLogger searchLogger)

Perform a document query only (no hits)

Parameters:

documentFilterQuery - the document-level query

searchLogger - where to log details about query execution

Returns:

the matching documents

termFrequencies

TermFrequencyList termFrequencies(AnnotationSensitivity annotSensitivity,
                                  org.apache.lucene.search.Query filterQuery,
                                  Set<String> terms)

Determine the term frequencies for an annotation sensitivity.

Parameters:

annotSensitivity - the annation + sensitivity indexing we want the term frequency for

filterQuery - document filter, or null for all documents

terms - a list of terms to retrieve frequencies for, or null/empty to retrieve frequencies for all terms

Returns:

term frequencies

explain

default QueryExplanation explain(QueryInfo queryInfo,
                                 TextPattern pattern,
                                 org.apache.lucene.search.Query filter)
                          throws InvalidQuery

Explain how a TextPattern is converted to a SpanQuery and rewritten to an optimized version to be executed by Lucene.

Parameters:

queryInfo - query info, such as the field to search

pattern - the pattern to explain

filter - filter query, or null for none

field - which field to find the pattern in

Returns:

the explanation

Throws:

WildcardTermTooBroad - if a wildcard or regular expression term is overly broad

InvalidQuery

explain

default QueryExplanation explain(BLSpanQuery query)
                          throws WildcardTermTooBroad

Explain how a SpanQuery is rewritten to an optimized version to be executed by Lucene.

Parameters:

query - the query to explain

Returns:

the explanation

Throws:

WildcardTermTooBroad - if a wildcard or regular expression term is overly broad

explain

QueryExplanation explain(BLSpanQuery query,
                         SearchLogger searchLogger)
                  throws WildcardTermTooBroad

Explain how a SpanQuery is rewritten to an optimized version to be executed by Lucene.

Parameters:

query - the query to explain

searchLogger - where to log details about query optimization

Returns:

the explanation

Throws:

WildcardTermTooBroad - if a wildcard or regular expression term is overly broad

search

SearchEmpty search(AnnotatedField field,
                   boolean useCache,
                   SearchLogger searchLogger)

Start building a Search.

Parameters:

field - field to search

useCache - whether to use the cache or bypass it

searchLogger - where to log details about how the search was executed, or null to skip this logging

Returns:

empty search object

search

default SearchEmpty search(AnnotatedField field,
                           boolean useCache)

Start building a Search.

Parameters:

field - field to search

useCache - whether to use the cache or bypass it

Returns:

empty search object

search

default SearchEmpty search(AnnotatedField field)

Start building a Search.

Parameters:

field - field to search

Returns:

empty search object

search

default SearchEmpty search()

Start building a Search.

Parameters:

field - field to search

Returns:

empty search object

reader

org.apache.lucene.index.IndexReader reader()

Get the Lucene index reader we're using.

Returns:

the Lucene index reader

searcher

org.apache.lucene.search.IndexSearcher searcher()

contentAccessor

ContentAccessor contentAccessor(Field field)

Get the content accessor for a field.

Parameters:

field - the field

Returns:

the content accessor, or null if there is no content accessor for this field

annotationForwardIndex

AnnotationForwardIndex annotationForwardIndex(Annotation annotation)

Tries to get the ForwardIndex object for the specified fieldname. Looks for an already-opened forward index first. If none is found, and if we're in "create index" mode, may create a new forward index. Otherwise, looks for an existing forward index and opens that.

Parameters:

annotation - the annotation for which we want the forward index

Returns:

the ForwardIndex if found/created

Throws:

BlackLabRuntimeException - if the annotation has no forward index

forwardIndex

ForwardIndex forwardIndex(AnnotatedField field)

Get forward index for the specified annotated field.

Parameters:

field - field to get forward index for

Returns:

forward index

name

String name()

Get the index name. Usually the name of the directory the index is in.

Returns:

index name

indexDirectory

File indexDirectory()

Get the index directory.

Returns:

index directory

metadata

IndexMetadata metadata()

Get information about the structure of the BlackLab index.

Returns:

the structure object

field

default Field field(String fieldName)

Get a field (either an annotated or a metadata field).

Parameters:

fieldName - name of the field

Returns:

the field

annotatedFields

default AnnotatedFields annotatedFields()

annotatedField

default AnnotatedField annotatedField(String fieldName)

mainAnnotatedField

default AnnotatedField mainAnnotatedField()

metadataFields

default MetadataFields metadataFields()

metadataField

default MetadataField metadataField(String fieldName)

searchSettings

SearchSettings searchSettings()

The default settings for all new Hits objects. You may change these settings; this will affect all new Hits objects.

Returns:

settings object

defaultUnbalancedTagsStrategy

XmlHighlighter.UnbalancedTagsStrategy defaultUnbalancedTagsStrategy()

How do we fix well-formedness for snippets of XML?

Returns:

the setting: either adding or removing unbalanced tags

defaultMatchSensitivity

MatchSensitivity defaultMatchSensitivity()

defaultExecutionContext

QueryExecutionContext defaultExecutionContext(AnnotatedField field)

Get the default initial query execution context.

Parameters:

field - field to search

Returns:

query execution context

collator

Collator collator()

Get the collator being used for sorting.

Returns:

the collator

analyzer

org.apache.lucene.analysis.Analyzer analyzer()

Get the analyzer for indexing and searching.

Returns:

the analyzer

defaultContextSize

ContextSize defaultContextSize()

Get the default context size.

Returns:

default context size

indexMode

boolean indexMode()

Are we running in index mode?

Returns:

true if we are, false if not

setDefaultUnbalancedTagsStrategy

void setDefaultUnbalancedTagsStrategy(XmlHighlighter.UnbalancedTagsStrategy strategy)

Set how to fix well-formedness for snippets of XML.

Parameters:

strategy - the setting: either adding or removing unbalanced tags

setCollator

void setCollator(Collator collator)

Set the collator used for sorting. The default collator is for English.

Parameters:

collator - the collator

setDefaultMatchSensitivity

void setDefaultMatchSensitivity(MatchSensitivity m)

Set the default sensitivity for queries.

Parameters:

m - default match sensitivity

setSearchSettings

void setSearchSettings(SearchSettings settings)

Set the maximum number of hits to process/count.

Parameters:

settings - desired settings

setDefaultContextSize

void setDefaultContextSize(ContextSize size)

Set the default context size.

Parameters:

size - default context size

setCache

void setCache(SearchCache cache)

Set the object BlackLab should use as cache. BlackLab will notify the cache of search results and will ask the cache for results before executing a search. It is up to the application to implement an effective cache, deciding whether to cache a result and ensuring the cache doesn't grow too large.

Parameters:

cache - cache object to use

cache

SearchCache cache()

blackLab

BlackLabEngine blackLab()

Get the BlackLab instance that created us.

Returns:

BlackLab instance