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

Copyright © 2000-2024 Apache Software Foundation. All Rights Reserved.