Package org.apache.solr.search.stats

Class StatsCache

java.lang.Object
org.apache.solr.search.stats.StatsCache
All Implemented Interfaces:
AutoCloseable, SolrInfoBean, SolrMetricProducer, PluginInfoInitialized
Direct Known Subclasses:
ExactStatsCache, LocalStatsCache
public abstract class StatsCache extends Object implements PluginInfoInitialized, SolrInfoBean
This class represents a cache of global document frequency information for selected terms. This information is periodically updated from all shards, either through scheduled events of some kind, or on every request when there is no global stats available for terms involved in the query (or if this information is stale due to changes in the shards).

There are instances of this class at the aggregator node (where the partial data from shards is aggregated), and on each core involved in a shard request (where this data is maintained and updated from the aggregator's cache).

  • Field Details

  • Constructor Details

    • StatsCache

      public StatsCache()

  • Method Details

    • getCacheMetrics

      public StatsCache.StatsCacheMetrics getCacheMetrics()

    • init

      public void init(PluginInfo info)
      Specified by:
      init in interface PluginInfoInitialized

    • retrieveStatsRequest

      public ShardRequest retrieveStatsRequest(ResponseBuilder rb)
      Creates a ShardRequest to retrieve per-shard stats related to the current query and the current state of the requester's StatsCache.

      This method updates the cache metrics and calls doRetrieveStatsRequest(ResponseBuilder).

      Parameters:
      rb - contains current request
      Returns:
      shard request to retrieve stats for terms in the current request, or null if no additional request is needed (e.g. if the information in global cache is already sufficient to satisfy this request).

    • doRetrieveStatsRequest

      protected abstract ShardRequest doRetrieveStatsRequest(ResponseBuilder rb)

    • returnLocalStats

      public void returnLocalStats(ResponseBuilder rb, SolrIndexSearcher searcher)
      Prepare a local (from the local shard) response to a "retrieve stats" shard request.

      This method updates the cache metrics and calls doReturnLocalStats(ResponseBuilder, SolrIndexSearcher).

      Parameters:
      rb - response builder
      searcher - current local searcher

    • doReturnLocalStats

      protected abstract void doReturnLocalStats(ResponseBuilder rb, SolrIndexSearcher searcher)

    • mergeToGlobalStats

      public void mergeToGlobalStats(SolrQueryRequest req, List<ShardResponse> responses)
      Process shard responses that contain partial local stats. Usually this entails combining per-shard stats for each term.

      This method updates the cache metrics and calls doMergeToGlobalStats(SolrQueryRequest, List).

      Parameters:
      req - query request
      responses - responses from shards containing local stats for each shard

    • doMergeToGlobalStats

      protected abstract void doMergeToGlobalStats(SolrQueryRequest req, List<ShardResponse> responses)

    • receiveGlobalStats

      public void receiveGlobalStats(SolrQueryRequest req)
      Receive global stats data from the leader and update a local cache of global stats with this global data. This event occurs either as a separate request, or together with the regular query request, in which case this method is called first, before preparing a QueryCommand to be submitted to the local SolrIndexSearcher.

      This method updates the cache metrics and calls doReceiveGlobalStats(SolrQueryRequest).

      Parameters:
      req - query request with global stats data

    • doReceiveGlobalStats

      protected abstract void doReceiveGlobalStats(SolrQueryRequest req)

    • sendGlobalStats

      public void sendGlobalStats(ResponseBuilder rb, ShardRequest outgoing)
      Prepare global stats data to be sent out to shards in this request.

      This method updates the cache metrics and calls doSendGlobalStats(ResponseBuilder, ShardRequest).

      Parameters:
      rb - response builder
      outgoing - shard request to be sent

    • doSendGlobalStats

      protected abstract void doSendGlobalStats(ResponseBuilder rb, ShardRequest outgoing)

    • get

      public StatsSource get(SolrQueryRequest req)
      Prepare a StatsSource that provides stats information to perform local scoring (to be precise, to build a local Weight from the query).

      This method updates the cache metrics and calls doGet(SolrQueryRequest).

      Parameters:
      req - query request
      Returns:
      an instance of StatsSource to use in creating a query Weight

    • doGet

      protected abstract StatsSource doGet(SolrQueryRequest req)

    • clear

      public void clear()
      Clear cached statistics.

    • approxCheckMissingStats

      public int approxCheckMissingStats(ResponseBuilder rb, StatsSource statsSource, Consumer<org.apache.lucene.index.Term> missingTermStats, Consumer<String> missingFieldStats) throws IOException
      Check if the statsSource is missing some term or field statistics info, which then needs to be retrieved.

      NOTE: this uses the local IndexReader for query rewriting, which may expand to less (or different) terms as rewriting the same query on other shards' readers. This in turn may falsely fail to inform the consumers about possibly missing stats, which may lead consumers to skip the fetching of full stats. Consequently this would lead to incorrect global IDF data for the missing terms (because for these terms only local stats would be used).

      Parameters:
      rb - request to evaluate against the statsSource
      statsSource - stats source to check
      missingTermStats - consumer of missing term stats
      missingFieldStats - consumer of missing field stats
      Returns:
      approximate number of missing term stats and field stats combined
      Throws:
      IOException

    • getName

      public String getName()
      Description copied from interface: SolrInfoBean
      Simple common usage name, e.g. BasicQueryHandler, or fully qualified class name.
      Specified by:
      getName in interface SolrInfoBean

    • getDescription

      public String getDescription()
      Description copied from interface: SolrInfoBean
      Simple one or two line description
      Specified by:
      getDescription in interface SolrInfoBean

    • getCategory

      public SolrInfoBean.Category getCategory()
      Description copied from interface: SolrInfoBean
      Category of this component
      Specified by:
      getCategory in interface SolrInfoBean

    • getSolrMetricsContext

      public SolrMetricsContext getSolrMetricsContext()
      Description copied from interface: SolrMetricProducer
      Implementations should return the context used in SolrMetricProducer.initializeMetrics(SolrMetricsContext, Attributes) to ensure proper cleanup of metrics at the end of the life-cycle of this component. This should be the child context if one was created, or null if the parent context was used.
      Specified by:
      getSolrMetricsContext in interface SolrMetricProducer

    • initializeMetrics

      public void initializeMetrics(SolrMetricsContext solrMetricsContext, io.opentelemetry.api.common.Attributes attributes)
      Description copied from interface: SolrMetricProducer
      Implementation should initialize all metrics to a SolrMetricsContext Registry/MeterProvider with Attributes as the common set of attributes that will be attached to every metric that is initialized for that class/component
      Specified by:
      initializeMetrics in interface SolrMetricProducer
      Parameters:
      solrMetricsContext - The registry that the component will initialize metrics to
      attributes - Base set of attributes that will be bound to all metrics for that component

    • close

      public void close() throws IOException
      Description copied from interface: SolrMetricProducer
      Implementations should always call SolrMetricProducer.super.close() to ensure that metrics with the same life-cycle as this component are properly unregistered. This prevents obscure memory leaks.

      from: https://docs.oracle.com/javase/8/docs/api/java/lang/AutoCloseable.html While this interface method is declared to throw Exception, implementers are strongly encouraged to declare concrete implementations of the close method to throw more specific exceptions, or to throw no exception at all if the close operation cannot fail.

      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface SolrMetricProducer
      Throws:
      IOException