nl.inl.blacklab.search.results

Class DocResults

java.lang.Object

nl.inl.blacklab.search.results.Results<DocResult>

nl.inl.blacklab.search.results.DocResults

All Implemented Interfaces:

Iterable<DocResult>, ResultGroups<Hit>, SearchResult

public class DocResults
extends Results<DocResult>
implements ResultGroups<Hit>

A list of DocResult objects (document-level query results).

Field Summary

Fields inherited from class nl.inl.blacklab.search.results.Results

hitsObjId, NO_LIMIT, results, threadPauser

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	DocResults(QueryInfo queryInfo) Construct an empty DocResults.
protected	DocResults(QueryInfo queryInfo, Hits hits, int maxHitsToStorePerDoc) Construct per-document results objects from a Hits object
protected	DocResults(QueryInfo queryInfo, List<DocResult> results, SampleParameters sampleParameters, WindowStats windowStats) Wraps a list of DocResult objects with the DocResults interface.

Method Summary

Modifier and Type	Method and Description
boolean	docsProcessedAtLeast(int lowerBound) Determines if there are at least a certain number of results This may be used if we don't want to process all results (which may be a lot) but we do need to know something about the size of the result set (such as for paging).
int	docsProcessedSoFar()
protected int	docsProcessedTotal() Get the number of documents in this results set.
boolean	doneProcessingAndCounting() Check if we're done retrieving/counting hits.
static DocResults	empty(QueryInfo queryInfo) Construct an empty DocResults.
protected void	ensureResultsRead(int index) If we still have only partially read our Hits object, read some more of it and add the hits.
DocResults	filter(ResultProperty<DocResult> property, PropertyValue value) Select only the hits where the specified property has the specified value.
static DocResults	fromHits(QueryInfo queryInfo, Hits hits, int maxHitsToStorePerDoc) Construct a DocResults from a Hits instance.
static DocResults	fromList(QueryInfo queryInfo, List<DocResult> results, SampleParameters sampleParameters, WindowStats windowStats) Construct a DocResults from a list of results.
static DocResults	fromQuery(QueryInfo queryInfo, org.apache.lucene.search.Query query) Don't use this, use BlackLabIndex.queryDocuments().
Group<Hit>	get(PropertyValue prop)
Map<PropertyValue,? extends Group<Hit>>	getGroupMap()
DocGroups	group(ResultProperty<DocResult> groupBy, int maxResultsToStorePerGroup) Group these hits by a criterium (or several criteria).
ResultProperty<Hit>	groupCriteria() What were these results grouped on?
int	intSum(ResultProperty<DocResult> numProp) Sum a property for all the documents.
int	largestGroupSize() Return the size of the largest group
int	numberOfResultObjects() How many result objects does this search store? Used for estimating the cache size.
org.apache.lucene.search.Query	query()
DocResults	sample(SampleParameters sampleParameters) Take a sample of hits by wrapping an existing Hits object.
SampleParameters	sampleParameters() If this is a sample, return the sample parameters.
<P extends ResultProperty<DocResult>> DocResults	sort(P sortProp) Return a new Results object with these results sorted by the given property.
CorpusSize	subcorpusSize() Determine the size of the subcorpus defined by this set of documents.
CorpusSize	subcorpusSize(boolean countTokens) Determine the size of the subcorpus defined by this set of documents.
int	sumOfGroupSizes() Get the total number of results that were grouped
long	tokensInMatchingDocs() Deprecated. use subcorpusSize().getTokens()
DocResults	window(int first, int number) Get a window into the doc results
WindowStats	windowStats() If this is a hits window, return the window stats.
DocResults	withFewerStoredResults(int maximumNumberOfResultsPerGroup) Get an instance of this grouping with fewer stored results per group.

Methods inherited from class nl.inl.blacklab.search.results.Results

doFilter, doSample, doSort, doWindow, ensureAllResultsRead, field, get, index, isSample, isWindow, iterator, parallelStream, queryInfo, resultsCountedSoFar, resultsCountedTotal, resultsList, resultsObjId, resultsProcessedAtLeast, resultsProcessedSoFar, resultsProcessedTotal, resultsStats, resultsSubList, size, stream, threadPauser, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface nl.inl.blacklab.search.results.ResultGroups

field, get, index, queryInfo, size

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Constructor Detail

DocResults

protected DocResults(QueryInfo queryInfo)

Construct an empty DocResults.

Parameters:

queryInfo -

DocResults

protected DocResults(QueryInfo queryInfo,
                     Hits hits,
                     int maxHitsToStorePerDoc)

Construct per-document results objects from a Hits object

Parameters:

queryInfo - query info

hits - the hits to view per-document

maxHitsToStorePerDoc - hits to store per document

DocResults

protected DocResults(QueryInfo queryInfo,
                     List<DocResult> results,
                     SampleParameters sampleParameters,
                     WindowStats windowStats)

Wraps a list of DocResult objects with the DocResults interface. NOTE: the list is not copied but referenced! Used by DocGroups constructor.

Parameters:

queryInfo - query info

results - the list of results

windowStats - window stats

Method Detail

empty

public static DocResults empty(QueryInfo queryInfo)

Construct an empty DocResults.

Parameters:

queryInfo - query info

Returns:

document results

fromList

public static DocResults fromList(QueryInfo queryInfo,
                                  List<DocResult> results,
                                  SampleParameters sampleParameters,
                                  WindowStats windowStats)

Construct a DocResults from a list of results.

Parameters:

queryInfo - query info

results - results

sampleParameters - sample parameters (if this is a sample)

windowStats - window stats (if this is a window)

Returns:

document results

fromHits

public static DocResults fromHits(QueryInfo queryInfo,
                                  Hits hits,
                                  int maxHitsToStorePerDoc)

Construct a DocResults from a Hits instance.

Parameters:

queryInfo - query info

hits - hits to get document results from

maxHitsToStorePerDoc - how many hits to store per document, for displaying snippets (-1 for all)

Returns:

document results

fromQuery

public static DocResults fromQuery(QueryInfo queryInfo,
                                   org.apache.lucene.search.Query query)

Don't use this, use BlackLabIndex.queryDocuments().

Parameters:

queryInfo - query info

query - query to execute

Returns:

per-document results

windowStats

public WindowStats windowStats()

Description copied from class: Results

If this is a hits window, return the window stats.

Overrides:

windowStats in class Results<DocResult>

Returns:

window stats, or null if this is not a hits window

sampleParameters

public SampleParameters sampleParameters()

Description copied from class: Results

If this is a sample, return the sample parameters. Also includes the explicitly set or randomly chosen seed.

Overrides:

sampleParameters in class Results<DocResult>

Returns:

sample parameters, or null if this is not a sample

sort

public <P extends ResultProperty<DocResult>> DocResults sort(P sortProp)

Description copied from class: Results

Return a new Results object with these results sorted by the given property. This keeps the existing sort (or lack of one) intact and allows you to cache different sorts of the same resultset. The result objects are reused between the two Results instances, so not too much additional memory is used.

Specified by:

sort in class Results<DocResult>

Parameters:

sortProp - the property to sort on

Returns:

a new Results object with the same results, sorted in the specified way

docsProcessedAtLeast

public boolean docsProcessedAtLeast(int lowerBound)

Determines if there are at least a certain number of results This may be used if we don't want to process all results (which may be a lot) but we do need to know something about the size of the result set (such as for paging).

Parameters:

lowerBound - the number we're testing against

Returns:

true if the size of this set is at least lowerBound, false otherwise.

docsProcessedSoFar

public int docsProcessedSoFar()

docsProcessedTotal

protected int docsProcessedTotal()

Get the number of documents in this results set. Note that this returns the number of document results available; if there were so many hits that not all were retrieved (call maxHitsRetrieved()), you can find the grand total of documents by calling totalSize().

Returns:

the number of documents.

ensureResultsRead

protected void ensureResultsRead(int index)

If we still have only partially read our Hits object, read some more of it and add the hits.

Specified by:

ensureResultsRead in class Results<DocResult>

Parameters:

index - the number of results we want to ensure have been read, or negative for all results

group

public DocGroups group(ResultProperty<DocResult> groupBy,
                       int maxResultsToStorePerGroup)

Description copied from class: Results

Group these hits by a criterium (or several criteria).

Specified by:

group in class Results<DocResult>

Parameters:

groupBy - the hit property to group on

maxResultsToStorePerGroup - maximum number of results to store per group, or -1 for all

Returns:

a HitGroups object representing the grouped hits

window

public DocResults window(int first,
                         int number)

Get a window into the doc results

Specified by:

window in class Results<DocResult>

Parameters:

first - first document result to include

number - maximum number of document results to include

Returns:

the window

intSum

public int intSum(ResultProperty<DocResult> numProp)

Sum a property for all the documents. Can be used to calculate the total number of tokens in a subcorpus, for example. Note that this does retrieve all results, so it may be slow for large sets. In particular, you should try to call this method only for DocResults created with BlackLabIndex.queryDocuments() (and not ones created with Hits.perDocResults()) to avoid the overhead of fetching hits.

Parameters:

numProp - a numeric property to sum

Returns:

the sum

sumOfGroupSizes

public int sumOfGroupSizes()

Description copied from interface: ResultGroups

Get the total number of results that were grouped

Specified by:

sumOfGroupSizes in interface ResultGroups<Hit>

Returns:

the number of results that were grouped

largestGroupSize

public int largestGroupSize()

Description copied from interface: ResultGroups

Return the size of the largest group

Specified by:

largestGroupSize in interface ResultGroups<Hit>

Returns:

size of the largest group

get

public Group<Hit> get(PropertyValue prop)

Specified by:

get in interface ResultGroups<Hit>

groupCriteria

public ResultProperty<Hit> groupCriteria()

Description copied from interface: ResultGroups

What were these results grouped on?

Specified by:

groupCriteria in interface ResultGroups<Hit>

Returns:

group criteria

filter

public DocResults filter(ResultProperty<DocResult> property,
                         PropertyValue value)

Description copied from class: Results

Select only the hits where the specified property has the specified value.

Specified by:

filter in class Results<DocResult>

Parameters:

property - property to select on, e.g. "word left of hit"

value - value to select on, e.g. 'the'

Returns:

filtered hits

withFewerStoredResults

public DocResults withFewerStoredResults(int maximumNumberOfResultsPerGroup)

Description copied from interface: ResultGroups

Get an instance of this grouping with fewer stored results per group. This won't affect the group sizes, just the number of results that are stored per group.

Specified by:

withFewerStoredResults in interface ResultGroups<Hit>

Parameters:

maximumNumberOfResultsPerGroup - maximum number of results to store, or -1 for the same

Returns:

new grouping with fewer stored results

sample

public DocResults sample(SampleParameters sampleParameters)

Take a sample of hits by wrapping an existing Hits object.

Specified by:

sample in class Results<DocResult>

Parameters:

sampleParameters - sample parameters

Returns:

the sample

doneProcessingAndCounting

public boolean doneProcessingAndCounting()

Description copied from class: Results

Check if we're done retrieving/counting hits. If you're retrieving hits in a background thread, call this method from another thread to check if all hits have been processed.

Specified by:

doneProcessingAndCounting in class Results<DocResult>

Returns:

true iff all hits have been retrieved/counted.

getGroupMap

public Map<PropertyValue,? extends Group<Hit>> getGroupMap()

Specified by:

getGroupMap in interface ResultGroups<Hit>

numberOfResultObjects

public int numberOfResultObjects()

Description copied from interface: SearchResult

How many result objects does this search store? Used for estimating the cache size. Hits make up most of the storage of results objects, and they should take 24 bytes of memory, so we can use this number to make a reasonable approximation of memory usage. Note that this number can be misleading, because Hit objects are shared between results objects. But it's the best we have at the moment.

Specified by:

numberOfResultObjects in interface SearchResult

Returns:

how many hits are stored in this result object

tokensInMatchingDocs

@Deprecated
public long tokensInMatchingDocs()

Deprecated. use subcorpusSize().getTokens()

Count total number of tokens in matching documents. This is fast if the query was created from a Query object (and the index contains DocValues), but slower if it was created from Hits or a list of DocResult objects.

Returns:

total number of tokens in matching documents.

subcorpusSize

public CorpusSize subcorpusSize()

Determine the size of the subcorpus defined by this set of documents. Counts number of documents and tokens. This is fast if the query was created from a Query object (and the index contains DocValues), but slower if it was created from Hits or a list of DocResult objects.

Returns:

subcorpus size

subcorpusSize

public CorpusSize subcorpusSize(boolean countTokens)

Determine the size of the subcorpus defined by this set of documents. Counts number of documents and tokens (if countTokens is true). This is fast if the query was created from a Query object (and the index contains DocValues), but slower if it was created from Hits or a list of DocResult objects.

Parameters:

countTokens - whether or not to count tokens (slower)

Returns:

subcorpus size

query

public org.apache.lucene.search.Query query()