How does Solr's filterCache store an entry, and why can an fq clause using NOW make it useless?

## What an entry actually is The `filterCache` is configured in `solrconfig.xml`: ```xml <filterCache class="solr.CaffeineCache" size="512" initialSize="512" autowarmCount="128"/> ``` The key is the filter query itself; the value is a `DocSet`, an unordered set of internal Lucene document ids matching that filter across the entire index. It carries no scores and no ordering, because a filter contributes nothing to ranking — that is the whole point of putting a clause in `fq` rather than `q`. Solr picks a representation by density. A dense set becomes a `BitDocSet` backed by a fixed bitset of `maxDoc` bits — one bit per document in the index whether it matches or not, so about `maxDoc / 8` bytes. A sparse set becomes a `SortedIntDocSet`, roughly four bytes per matching document. The practical consequence: on a 50-million-document core, a cached dense filter costs about 6 MB, and `size=512` is a promise of up to roughly 3 GB of heap if the entries are dense. Sizing this cache without doing that multiplication is a classic way to OOM a Solr node. ## Searcher lifetime and autowarming Internal doc ids are only meaningful for a specific index view. When a commit opens a new searcher, the old cache is thrown away wholesale. `autowarmCount` tells Solr to re-execute that many of the most recently used filter queries against the new searcher before it serves traffic, so the first users after a commit do not all pay a cold miss. This trades directly against commit frequency. Aggressive autowarming plus frequent hard commits means the machine spends much of its time re-running filters, and if warming takes longer than the interval between commits you can end up with overlapping warming searchers — hence `maxWarmingSearchers` and the familiar error when it is exceeded. Near-real-time deployments usually keep `autowarmCount` low and lean on soft commits. ## The NOW trap Solr resolves `NOW` to the request's current time in milliseconds. So `fq=ts:[NOW-1HOUR TO NOW]` produces a distinct query string, and therefore a distinct cache key, on essentially every request. The hit ratio for that filter is zero, the expensive range set is recomputed each time, and each new entry evicts something that would have been reused. The fix is date-math rounding: ``` fq=ts:[NOW-1HOUR/MINUTE TO NOW/MINUTE] ``` Now the key changes once a minute instead of once a millisecond, and the filter caches usefully. Round as coarsely as the product tolerates — `NOW/DAY` for a "last 30 days" filter is free. The same reasoning applies to any filter containing a per-request unique value: a user id, a session token, a generated geo point. Those belong behind `{!cache=false}`. ## cache=false and post filtering Two local params control participation: ``` fq={!cache=false}some_expensive_filter fq={!frange l=0 cache=false cost=200}sum(rating,votes) ``` `cache=false` skips the cache entirely — right for filters that are cheap to recompute, or unique per request, or so large that caching them evicts everything useful. Adding `cost` on a filter whose parser supports post filtering (such as `{!frange}` or `{!collapse}`) with a cost of 100 or more, together with `cache=false`, promotes it to a **post filter**: instead of building a full DocSet up front, it is evaluated only on documents that already passed the query and the cheaper filters. For an expensive function or an access-control check that matches most documents, that is dramatically cheaper. For cheaper filters, `cost` simply orders their evaluation. ## Sizing and monitoring The numbers to watch, exposed in the admin UI's plugins and stats page and via the metrics endpoints, are the cumulative hit ratio, the eviction count, and the warmup time. A modest hit ratio with high evictions means the working set of distinct filters exceeds `size` — either raise it (after computing the heap cost per entry) or stop caching the unique ones. A hit ratio near zero on a specific filter almost always means a per-request value in the key. High warmup time means `autowarmCount` is fighting your commit rate. ## What else uses it The filterCache is not only for `fq`. Classic faceting with `facet.method=enum` intersects one cached filter per term, which is why that method is only sensible for very low-cardinality fields; `useFilterForSortedQuery` lets the main query use it too. So a change in facet configuration can quietly change filterCache pressure. ## The design rule Put in `fq` what is reusable across users and requests — status flags, tenant ids, coarse date buckets, category constraints — and keep per-request uniqueness out of the key. That single discipline determines whether the filterCache is your best performance feature or dead weight consuming gigabytes of heap.