Hits (BlackLab 2.0.0 API)

java.lang.Object
- nl.inl.blacklab.search.results.Results<Hit>
- - nl.inl.blacklab.search.results.Hits

All Implemented Interfaces:

Iterable<Hit>, SearchResult

Direct Known Subclasses:

HitsFiltered, HitsFromQuery, HitsFromQueryParallel, HitsList
```
public abstract class Hits
extends Results<Hit>
```

Field Summary

Fields
Modifier and Type	Field and Description
`protected CapturedGroupsImpl`	`capturedGroups` Our captured groups, or null if we have none.
`protected int`	`docsCounted` The number of separate documents we've counted so far (includes non-retrieved hits).
`protected int`	`docsRetrieved` The number of separate documents we've seen in the hits retrieved.
`protected static int`	`FETCH_HITS_MIN` Minimum number of hits to fetch in an ensureHitsRead() block.
`protected int`	`hitsCounted` The number of hits we've seen and counted so far.
`protected static org.apache.logging.log4j.Logger`	`logger`

Fields inherited from class nl.inl.blacklab.search.results.Results
hitsObjId, NO_LIMIT, results, threadPauser

Constructor Summary

Constructors
Constructor and Description

Hits(QueryInfo queryInfo)

Constructors
Constructor and Description
`Hits(QueryInfo queryInfo)`

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`CapturedGroupsImpl`	`capturedGroups()`
`TermFrequencyList`	`collocations(Annotation annotation, ContextSize contextSize)` Count occurrences of context words around hit.
`TermFrequencyList`	`collocations(Annotation annotation, ContextSize contextSize, MatchSensitivity sensitivity)` Count occurrences of context words around hit.
`TermFrequencyList`	`collocations(Annotation annotation, ContextSize contextSize, MatchSensitivity sensitivity, boolean sort)` Count occurrences of context words around hit.
`Concordances`	`concordances(ContextSize contextSize)` Create concordances from the forward index.
`Concordances`	`concordances(ContextSize contextSize, ConcordanceType type)`
`protected int`	`docsCountedSoFar()`
`protected int`	`docsCountedTotal()`
`protected int`	`docsProcessedSoFar()`
`protected int`	`docsProcessedTotal()`
`ResultsStats`	`docsStats()`
`static Hits`	`emptyList(QueryInfo queryInfo)` Construct an empty Hits object.
`Hits`	`filter(ResultProperty<Hit> property, PropertyValue value)` Select only the hits where the specified property has the specified value.
`static Hits`	`fromArrays(QueryInfo queryInfo, int[] doc, int[] start, int[] end)` Make a wrapper Hits object for a list of Hit objects.
`static Hits`	`fromList(QueryInfo queryInfo, List<Hit> hits)` Make a wrapper Hits object for a list of Hit objects.
`static Hits`	`fromList(QueryInfo queryInfo, List<Hit> hits, CapturedGroups capturedGroups)` Make a wrapper Hits object for a list of Hit objects.
`static Hits`	`fromList(QueryInfo queryInfo, List<Hit> results, WindowStats windowStats, SampleParameters sampleParameters, int hitsCounted, int docsRetrieved, int docsCounted, CapturedGroupsImpl capturedGroups)`
`static Hits`	`fromSpanQuery(QueryInfo queryInfo, BLSpanQuery query, SearchSettings searchSettings)` Construct a Hits object from a SpanQuery.
`Hits`	`getHitsInDoc(int docid)`
`HitGroups`	`group(ResultProperty<Hit> criteria, int maxResultsToStorePerGroup)` Group these hits by a criterium (or several criteria).
`boolean`	`hasCapturedGroups()`
`protected int`	`hitsCountedSoFar()`
`protected int`	`hitsCountedTotal()`
`protected boolean`	`hitsProcessedAtLeast(int lowerBound)`
`protected int`	`hitsProcessedSoFar()`
`protected int`	`hitsProcessedTotal()`
`ResultsStats`	`hitsStats()`
`Kwics`	`kwics(ContextSize contextSize)`
`abstract MaxStats`	`maxStats()` Did we exceed the maximum number of hits to process/count? NOTE: this is only valid for the original Hits instance (that executes the query), and not for any derived Hits instance (window, sorted, filtered, ...).
`int`	`numberOfResultObjects()` How many result objects does this search store? Used for estimating the cache size.
`DocResults`	`perDocResults(int maxHits)` Return a per-document view of these hits.
`protected int`	`resultsCountedSoFar()`
`protected int`	`resultsCountedTotal()`
`Hits`	`sample(SampleParameters sampleParameters)` Take a sample of hits by wrapping an existing Hits object.
`int`	`size()` This is an alias of resultsProcessedTotal().
`<P extends ResultProperty<Hit>> Hits`	`sort(P sortProp)` Return a new Hits object with these hits sorted by the given property.
`Hits`	`window(Hit hit)`
`Hits`	`window(int first, int windowSize)` Get a window into this list of hits.

Methods inherited from class nl.inl.blacklab.search.results.Results
doFilter, doneProcessingAndCounting, doSample, doSort, doWindow, ensureAllResultsRead, ensureResultsRead, field, get, index, isSample, isWindow, iterator, parallelStream, queryInfo, resultsList, resultsObjId, resultsProcessedAtLeast, resultsProcessedSoFar, resultsProcessedTotal, resultsStats, resultsSubList, sampleParameters, stream, threadPauser, toString, windowStats

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.lang.Iterable
forEach, spliterator

- Field Detail
  - logger
```
protected static final org.apache.logging.log4j.Logger logger
```
  - FETCH_HITS_MIN
```
protected static final int FETCH_HITS_MIN
```
    Minimum number of hits to fetch in an ensureHitsRead() block. This prevents locking again and again for a single hit when iterating. See HitsFromQuery and HitsFiltered.
    
    See Also:
    
    Constant Field Values
  - capturedGroups
```
protected CapturedGroupsImpl capturedGroups
```
    Our captured groups, or null if we have none.
  - hitsCounted
```
protected int hitsCounted
```
    The number of hits we've seen and counted so far. May be more than the number of hits we've retrieved if that exceeds maxHitsToRetrieve.
  - docsRetrieved
```
protected int docsRetrieved
```
    The number of separate documents we've seen in the hits retrieved.
  - docsCounted
```
protected int docsCounted
```
    The number of separate documents we've counted so far (includes non-retrieved hits).
- Constructor Detail
  - Hits
```
public Hits(QueryInfo queryInfo)
```
- Method Detail
  - fromSpanQuery
```
public static Hits fromSpanQuery(QueryInfo queryInfo,
                                 BLSpanQuery query,
                                 SearchSettings searchSettings)
                          throws WildcardTermTooBroad
```
    Construct a Hits object from a SpanQuery.
    
    Parameters:
    
    queryInfo - information about the original query
    
    query - the query to execute to get the hits
    
    searchSettings - settings such as max. hits to process/count
    
    Returns:
    
    hits found
    
    Throws:
    
    WildcardTermTooBroad - if a wildcard term matches too many terms in the index
  - fromList
```
public static Hits fromList(QueryInfo queryInfo,
                            List<Hit> hits)
```
    Make a wrapper Hits object for a list of Hit objects. Does not copy the list, but reuses it.
    
    Parameters:
    
    queryInfo - information about the original query
    
    hits - the list of hits to wrap, or null for empty Hits object
    
    Returns:
    
    hits found
  - fromList
```
public static Hits fromList(QueryInfo queryInfo,
                            List<Hit> hits,
                            CapturedGroups capturedGroups)
```
    Make a wrapper Hits object for a list of Hit objects. Does not copy the list, but reuses it.
    
    Parameters:
    
    queryInfo - information about the original query
    
    hits - the list of hits to wrap, or null for empty Hits object
    
    capturedGroups - the list of hits to wrap, or null for no captured groups
    
    Returns:
    
    hits found
  - fromArrays
```
public static Hits fromArrays(QueryInfo queryInfo,
                              int[] doc,
                              int[] start,
                              int[] end)
```
    Make a wrapper Hits object for a list of Hit objects. Will create Hit objects from the arrays. Mainly useful for testing.
    
    Parameters:
    
    queryInfo - information about the original query
    
    doc - doc ids
    
    start - hit starts
    
    end - hit ends
    
    Returns:
    
    hits found
  - fromList
```
public static Hits fromList(QueryInfo queryInfo,
                            List<Hit> results,
                            WindowStats windowStats,
                            SampleParameters sampleParameters,
                            int hitsCounted,
                            int docsRetrieved,
                            int docsCounted,
                            CapturedGroupsImpl capturedGroups)
```
  - emptyList
```
public static Hits emptyList(QueryInfo queryInfo)
```
    Construct an empty Hits object.
    
    Parameters:
    
    queryInfo - query info
    
    Returns:
    
    hits found
  - sample
```
public Hits sample(SampleParameters sampleParameters)
```
    Take a sample of hits by wrapping an existing Hits object.
    
    Specified by:
    
    sample in class Results<Hit>
    
    Parameters:
    
    sampleParameters - sample parameters
    
    Returns:
    
    the sample
  - window
```
public Hits window(int first,
                   int windowSize)
```
    Get a window into this list of hits. Use this if you're displaying part of the resultset, like in a paging interface. It makes sure BlackLab only works with the hits you want to display and doesn't do any unnecessary processing on the other hits. HitsWindow includes methods to assist with paging, like figuring out if there hits before or after the window.
    
    Specified by:
    
    window in class Results<Hit>
    
    Parameters:
    
    first - first hit in the window (0-based)
    
    windowSize - size of the window
    
    Returns:
    
    the window
  - collocations
```
public TermFrequencyList collocations(Annotation annotation,
                                      ContextSize contextSize,
                                      MatchSensitivity sensitivity,
                                      boolean sort)
```
    Count occurrences of context words around hit.
    
    Parameters:
    
    annotation - what annotation to get collocations for
    
    contextSize - how many words around the hits to use
    
    sensitivity - what sensitivity to use
    
    sort - sort the resulting collocations by descending frequency?
    
    Returns:
    
    the frequency of each occurring token
  - collocations
```
public TermFrequencyList collocations(Annotation annotation,
                                      ContextSize contextSize,
                                      MatchSensitivity sensitivity)
```
    Count occurrences of context words around hit. Sorts the results from most to least frequent.
    
    Parameters:
    
    annotation - what annotation to get collocations for
    
    contextSize - how many words around the hits to use
    
    sensitivity - what sensitivity to use
    
    Returns:
    
    the frequency of each occurring token
  - collocations
```
public TermFrequencyList collocations(Annotation annotation,
                                      ContextSize contextSize)
```
    Count occurrences of context words around hit. Matches case- and diacritics-sensitively, and sorts the results from most to least frequent.
    
    Parameters:
    
    annotation - what annotation to get collocations for
    
    contextSize - how many words around the hits to use
    
    Returns:
    
    the frequency of each occurring token
  - perDocResults
```
public DocResults perDocResults(int maxHits)
```
    Return a per-document view of these hits.
    
    Parameters:
    
    maxHits -
    
    Returns:
    
    the per-document view.
  - group
```
public HitGroups group(ResultProperty<Hit> criteria,
                       int maxResultsToStorePerGroup)
```
    Description copied from class: Results
    
    Group these hits by a criterium (or several criteria).
    
    Specified by:
    
    group in class Results<Hit>
    
    Parameters:
    
    criteria - 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
  - filter
```
public Hits filter(ResultProperty<Hit> property,
                   PropertyValue value)
```
    Select only the hits where the specified property has the specified value.
    
    Specified by:
    
    filter in class Results<Hit>
    
    Parameters:
    
    property - property to select on, e.g. "word left of hit"
    
    value - value to select on, e.g. 'the'
    
    Returns:
    
    filtered hits
  - concordances
```
public Concordances concordances(ContextSize contextSize)
```
    Create concordances from the forward index.
    
    Parameters:
    
    contextSize - desired context size
    
    Returns:
    
    concordances
  - size
```
public int size()
```
    Description copied from class: Results
    
    This is an alias of resultsProcessedTotal().
    
    Overrides:
    
    size in class Results<Hit>
    
    Returns:
    
    number of hits processed total
  - getHitsInDoc
```
public Hits getHitsInDoc(int docid)
```
  - hitsStats
```
public ResultsStats hitsStats()
```
  - hitsProcessedAtLeast
```
protected boolean hitsProcessedAtLeast(int lowerBound)
```
  - hitsProcessedTotal
```
protected int hitsProcessedTotal()
```
  - hitsProcessedSoFar
```
protected int hitsProcessedSoFar()
```
  - hitsCountedTotal
```
protected int hitsCountedTotal()
```
  - docsStats
```
public ResultsStats docsStats()
```
  - docsProcessedTotal
```
protected int docsProcessedTotal()
```
  - docsCountedTotal
```
protected int docsCountedTotal()
```
  - hitsCountedSoFar
```
protected int hitsCountedSoFar()
```
  - docsCountedSoFar
```
protected int docsCountedSoFar()
```
  - docsProcessedSoFar
```
protected int docsProcessedSoFar()
```
  - resultsCountedTotal
```
protected int resultsCountedTotal()
```
    Overrides:
    
    resultsCountedTotal in class Results<Hit>
  - resultsCountedSoFar
```
protected int resultsCountedSoFar()
```
    Overrides:
    
    resultsCountedSoFar in class Results<Hit>
  - window
```
public Hits window(Hit hit)
```
  - sort
```
public <P extends ResultProperty<Hit>> Hits sort(P sortProp)
```
    Return a new Hits object with these hits 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 hits themselves are reused between the two Hits instances, so not too much additional memory is used.
    
    Specified by:
    
    sort in class Results<Hit>
    
    Parameters:
    
    sortProp - the hit property to sort on
    
    Returns:
    
    a new Hits object with the same hits, sorted in the specified way
  - capturedGroups
```
public CapturedGroupsImpl capturedGroups()
```
  - hasCapturedGroups
```
public boolean hasCapturedGroups()
```
  - concordances
```
public Concordances concordances(ContextSize contextSize,
                                 ConcordanceType type)
```
  - kwics
```
public Kwics kwics(ContextSize contextSize)
```
  - maxStats
```
public abstract MaxStats maxStats()
```
    Did we exceed the maximum number of hits to process/count? NOTE: this is only valid for the original Hits instance (that executes the query), and not for any derived Hits instance (window, sorted, filtered, ...). The reason that this is not part of QueryInfo is that this creates a brittle link between derived Hits instances and the original Hits instances, which by now may have been aborted, leaving the max stats in a frozen, incorrect state.
    
    Returns:
    
    our max stats, or MaxStats.NOT_EXCEEDED if not available for this instance
  - 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.
    
    Returns:
    
    how many hits are stored in this result object

Class Hits

Field Summary

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

Constructor Summary

Method Summary

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

Methods inherited from class java.lang.Object

Methods inherited from interface java.lang.Iterable

Field Detail

logger

FETCH_HITS_MIN

capturedGroups

hitsCounted

docsRetrieved

docsCounted

Constructor Detail

Hits

Method Detail

fromSpanQuery

fromList

fromList

fromArrays

fromList

emptyList

sample

window

collocations

collocations

collocations

perDocResults

group

filter

concordances

size

getHitsInDoc

hitsStats

hitsProcessedAtLeast

hitsProcessedTotal

hitsProcessedSoFar

hitsCountedTotal

docsStats

docsProcessedTotal

docsCountedTotal

hitsCountedSoFar

docsCountedSoFar

docsProcessedSoFar

resultsCountedTotal

resultsCountedSoFar

window

sort

capturedGroups

hasCapturedGroups

concordances

kwics

maxStats

numberOfResultObjects