UsageTrackingQueryCachingPolicy (Lucene 10.5.0 core API)
Description: declaration: package: org.apache.lucene.search, class: UsageTrackingQueryCachingPolicy

Package 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
  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

  Modifier and Type
  Method
  Description
  `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 Details

  - ### 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 Details

  - ### 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`