Package org.apache.lucene.search
Class LRUQueryCache
java.lang.Object
org.apache.lucene.search.LRUQueryCache
- All Implemented Interfaces:
QueryCache,Accountable
A
QueryCache that evicts queries using a LRU (least-recently-used) eviction policy in
order to remain under a given maximum size and number of bytes used.
This class is thread-safe.
Note that query eviction runs in linear time with the total number of segments that have cache
entries so this cache works best with caching policies that only cache
on "large" segments, and it is advised to not share this cache across too many indices.
A default query cache and policy instance is used in IndexSearcher. If you want to replace those defaults it is typically done like this:
final int maxNumberOfCachedQueries = 256; final long maxRamBytesUsed = 50 * 1024L * 1024L; // 50MB // these cache and policy instances can be shared across several queries and readers // it is fine to eg. store them into static variables final QueryCache queryCache = new LRUQueryCache(maxNumberOfCachedQueries, maxRamBytesUsed); final QueryCachingPolicy defaultCachingPolicy = new UsageTrackingQueryCachingPolicy(); indexSearcher.setQueryCache(queryCache); indexSearcher.setQueryCachingPolicy(defaultCachingPolicy);This cache exposes some global statistics (
hit count, miss count, number of cache entries, total number of DocIdSets that have ever been cached, number of evicted entries). In case you would like to have more fine-grained
statistics, such as per-index or per-query-class statistics, it is possible to override various
callbacks: onHit(java.lang.Object, org.apache.lucene.search.Query), onMiss(java.lang.Object, org.apache.lucene.search.Query), onQueryCache(org.apache.lucene.search.Query, long), onQueryEviction(org.apache.lucene.search.Query, long),
onDocIdSetCache(java.lang.Object, long), onDocIdSetEviction(java.lang.Object, int, long) and onClear(). It is better to not
perform heavy computations in these methods though since they are called synchronously and under
a lock.- See Also:
- WARNING: This API is experimental and might change in incompatible ways in the next release.
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionprotected static classCache of doc ids with a count. -
Field Summary
Fields inherited from interface org.apache.lucene.util.Accountable
NULL_ACCOUNTABLE -
Constructor Summary
ConstructorsConstructorDescriptionLRUQueryCache(int maxSize, long maxRamBytesUsed) Create a new instance that will cache at mostmaxSizequeries with at mostmaxRamBytesUsedbytes of memory.LRUQueryCache(int maxSize, long maxRamBytesUsed, Predicate<LeafReaderContext> leavesToCache, float skipCacheFactor) Expert: Create a new instance that will cache at mostmaxSizequeries with at mostmaxRamBytesUsedbytes of memory, only on leaves that satisfyleavesToCache. -
Method Summary
Modifier and TypeMethodDescriptionprotected LRUQueryCache.CacheAndCountcacheImpl(BulkScorer scorer, int maxDoc) Default cache implementation: usesRoaringDocIdSetfor sets that have a density < 1% and aBitDocIdSetover aFixedBitSetotherwise.voidclear()Clear the content of this cache.voidclearCoreCacheKey(Object coreKey) Remove all cache entries for the given core cache key.voidclearQuery(Query query) Remove all cache entries for the given query.doCache(Weight weight, QueryCachingPolicy policy) Return a wrapper around the providedweightthat will cache matching docs per-segment accordingly to the givenpolicy.final longReturn the total number of cache entries that have been generated and put in the cache.final longReturn the total number ofDocIdSets which are currently stored in the cache.Returns nested resources of this class.final longReturn the number of cache entries that have been removed from the cache either in order to stay under the maximum configured size/ram usage, or because a segment has been closed.final longfinal longOver thetotalnumber of times that a query has been looked up, return how many times this query was not contained in the cache.floatGet the skip cache factorfinal longReturn the total number of times that aQueryhas been looked up in thisQueryCache.protected voidonClear()Expert: callback when the cache is completely cleared.protected voidonDocIdSetCache(Object readerCoreKey, long ramBytesUsed) Expert: callback when aDocIdSetis added to this cache.protected voidonDocIdSetEviction(Object readerCoreKey, int numEntries, long sumRamBytesUsed) Expert: callback when one or moreDocIdSets are removed from this cache.protected voidExpert: callback when there is a cache hit on a given query.protected voidExpert: callback when there is a cache miss on a given query.protected voidonQueryCache(Query query, long ramBytesUsed) Expert: callback when a query is added to this cache.protected voidonQueryEviction(Query query, long ramBytesUsed) Expert: callback when a query is evicted from this cache.longReturn the memory usage of this object in bytes.voidsetSkipCacheFactor(float skipCacheFactor) This setter enables the skipCacheFactor to be updated dynamically.
-
Constructor Details
-
LRUQueryCache
public LRUQueryCache(int maxSize, long maxRamBytesUsed, Predicate<LeafReaderContext> leavesToCache, float skipCacheFactor) Expert: Create a new instance that will cache at mostmaxSizequeries with at mostmaxRamBytesUsedbytes of memory, only on leaves that satisfyleavesToCache.Also, clauses whose cost is
skipCacheFactortimes more than the cost of the top-level query will not be cached in order to not slow down queries too much. -
LRUQueryCache
public LRUQueryCache(int maxSize, long maxRamBytesUsed) Create a new instance that will cache at mostmaxSizequeries with at mostmaxRamBytesUsedbytes of memory. Queries will only be cached on leaves that have more than 10k documents and have more than half of the average documents per leave of the index. This should guarantee that all leaves from the uppertierwill be cached. Only clauses whose cost is at most 100x the cost of the top-level query will be cached in order to not hurt latency too much because of caching.
-
-
Method Details
-
getSkipCacheFactor
public float getSkipCacheFactor()Get the skip cache factor- Returns:
- #setSkipCacheFactor
-
setSkipCacheFactor
public void setSkipCacheFactor(float skipCacheFactor) This setter enables the skipCacheFactor to be updated dynamically.- Parameters:
skipCacheFactor- clauses whose cost isskipCacheFactortimes more than the cost of the top-level query will not be cached in order to not slow down queries too much.
-
onHit
Expert: callback when there is a cache hit on a given query. Implementing this method is typically useful in order to compute more fine-grained statistics about the query cache.- See Also:
- WARNING: This API is experimental and might change in incompatible ways in the next release.
-
onMiss
Expert: callback when there is a cache miss on a given query.- See Also:
- WARNING: This API is experimental and might change in incompatible ways in the next release.
-
onQueryCache
Expert: callback when a query is added to this cache. Implementing this method is typically useful in order to compute more fine-grained statistics about the query cache.- See Also:
- WARNING: This API is experimental and might change in incompatible ways in the next release.
-
onQueryEviction
Expert: callback when a query is evicted from this cache.- See Also:
- WARNING: This API is experimental and might change in incompatible ways in the next release.
-
onDocIdSetCache
Expert: callback when aDocIdSetis added to this cache. Implementing this method is typically useful in order to compute more fine-grained statistics about the query cache.- See Also:
- WARNING: This API is experimental and might change in incompatible ways in the next release.
-
onDocIdSetEviction
Expert: callback when one or moreDocIdSets are removed from this cache.- See Also:
- WARNING: This API is experimental and might change in incompatible ways in the next release.
-
onClear
protected void onClear()Expert: callback when the cache is completely cleared.- WARNING: This API is experimental and might change in incompatible ways in the next release.
-
clearCoreCacheKey
Remove all cache entries for the given core cache key. -
clearQuery
Remove all cache entries for the given query. -
clear
public void clear()Clear the content of this cache. -
doCache
Description copied from interface:QueryCacheReturn a wrapper around the providedweightthat will cache matching docs per-segment accordingly to the givenpolicy. NOTE: The returned weight will only be equivalent if scores are not needed.- Specified by:
doCachein interfaceQueryCache- See Also:
-
ramBytesUsed
public long ramBytesUsed()Description copied from interface:AccountableReturn the memory usage of this object in bytes. Negative values are illegal.- Specified by:
ramBytesUsedin interfaceAccountable
-
getChildResources
Description copied from interface:AccountableReturns nested resources of this class. The result should be a point-in-time snapshot (to avoid race conditions).- Specified by:
getChildResourcesin interfaceAccountable- See Also:
-
cacheImpl
Default cache implementation: usesRoaringDocIdSetfor sets that have a density < 1% and aBitDocIdSetover aFixedBitSetotherwise.- Throws:
IOException
-
getTotalCount
public final long getTotalCount()Return the total number of times that aQueryhas been looked up in thisQueryCache. Note that this number is incremented once per segment so running a cached query only once will increment this counter by the number of segments that are wrapped by the searcher. Note that by definition,getTotalCount()is the sum ofgetHitCount()andgetMissCount().- See Also:
-
getHitCount
public final long getHitCount()Over thetotalnumber of times that a query has been looked up, return how many times a cachedDocIdSethas been found and returned.- See Also:
-
getMissCount
public final long getMissCount()Over thetotalnumber of times that a query has been looked up, return how many times this query was not contained in the cache.- See Also:
-
getCacheSize
public final long getCacheSize()Return the total number ofDocIdSets which are currently stored in the cache.- See Also:
-
getCacheCount
public final long getCacheCount()Return the total number of cache entries that have been generated and put in the cache. It is highly desirable to have ahit countthat is much higher than thecache countas the opposite would indicate that the query cache makes efforts in order to cache queries but then they do not get reused.- See Also:
-
getEvictionCount
public final long getEvictionCount()Return the number of cache entries that have been removed from the cache either in order to stay under the maximum configured size/ram usage, or because a segment has been closed. High numbers of evictions might mean that queries are not reused or that thecaching policycaches too aggressively on NRT segments which get merged early.- See Also:
-