org.apache.lucene.search

## Class UsageTrackingQueryCachingPolicy

- java.lang.Object
- - org.apache.lucene.search.UsageTrackingQueryCachingPolicy

All Implemented Interfaces:
  QueryCachingPolicy

    public class UsageTrackingQueryCachingPolicy
    extends Object
    implements QueryCachingPolicy

A `QueryCachingPolicy` that tracks usage statistics of recently-used filters in order to decide on which filters are worth caching.

WARNING: This API is experimental and might change in incompatible ways in the next release.

### Constructor Summary

Constructors
Constructor and Description
`UsageTrackingQueryCachingPolicy()` Create a new instance with an history size of 256.
`UsageTrackingQueryCachingPolicy(int historySize)` Expert: Create a new instance with a configurable history size.

### Method Summary

All Methods Instance Methods Concrete Methods
`protected int` `minFrequencyToCache(Query query)` For a given filter, return how many times it should appear in the history before being cached.
`void` `onUse(Query query)` Callback that is called every time that a cached filter is used.
`boolean` `shouldCache(Query query)` Whether the given `Query` is worth caching.

### Methods inherited from class java.lang.Object

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

### Constructor Detail

#### UsageTrackingQueryCachingPolicy

    public UsageTrackingQueryCachingPolicy(int historySize)

Expert: Create a new instance with a configurable history size. Beware of passing too large values for the size of the history, either `minFrequencyToCache(org.apache.lucene.search.Query)` returns low values and this means some filters that are rarely used will be cached, which would hurt performance. Or `minFrequencyToCache(org.apache.lucene.search.Query)` returns high values that are function of the size of the history but then filters will be slow to make it to the cache.

Parameters:
  `historySize` - the number of recently used filters to track

#### UsageTrackingQueryCachingPolicy

    public UsageTrackingQueryCachingPolicy()

Create a new instance with an history size of 256. This should be a good default for most cases.

### Method Detail

#### minFrequencyToCache

    protected int minFrequencyToCache(Query query)

For a given filter, return how many times it should appear in the history before being cached. The default implementation returns 2 for filters that need to evaluate against the entire index to build a `DocIdSetIterator`, like `MultiTermQuery`, point-based queries or `TermInSetQuery`, and 5 for other filters.

#### onUse

    public void onUse(Query query)

Description copied from interface: `QueryCachingPolicy`
Callback that is called every time that a cached filter is used. This is typically useful if the policy wants to track usage statistics in order to make decisions.

Specified by:
  `onUse` in interface `QueryCachingPolicy`

#### shouldCache

    public boolean shouldCache(Query query)
                        throws IOException

Description copied from interface: `QueryCachingPolicy`
Whether the given `Query` is worth caching. This method will be called by the `QueryCache` to know whether to cache. It will first attempt to load a `DocIdSet` from the cache. If it is not cached yet and this method returns `true` then a cache entry will be generated. Otherwise an uncached scorer will be returned.

Specified by:
  `shouldCache` in interface `QueryCachingPolicy`
Throws:
  `IOException`