[CONF] Apache Solr Reference Guide > Query Settings in SolrConfig

["Cassandra Targett (Confluence)" <co...@apache.org>]

Space: Apache Solr Reference Guide (https://cwiki.apache.org/confluence/display/solr)
Page: Query Settings in SolrConfig (https://cwiki.apache.org/confluence/display/solr/Query+Settings+in+SolrConfig)

Change Comment:
---------------------------------------------------------------------
solr-5182

Edited by Cassandra Targett:
---------------------------------------------------------------------
{section}
{column:width=75%}
The settings in this section affect the way that Solr will process and respond to queries. These settings are all configured in child elements of the {{<query>}} element in {{solrconfig.xml}}.

{code:xml|borderStyle=solid|borderColor=#666666}
<query>
    ...
</query>
{code}
{column}
{column:width=25%}
{panel}
Topics covered in this section:
{toc:maxLevel=2}
{panel}
{column}
{section}

h2. Caches

Solr caches are associated with a specific instance of an Index Searcher, a specific view of an index that doesn't change during the lifetime of that searcher. As long as that Index Searcher is being used, any items in its cache will be valid and available for reuse. Caching in Solr differs from caching in many other applications in that cached Solr objects do not expire after a time interval; instead, they remain valid for the lifetime of the Index Searcher.

When a new searcher is opened, the current searcher continues servicing requests while the new one auto-warms its cache. The new searcher uses the current searcher's cache to pre-populate its own. When the new searcher is ready, it is registered as the current searcher and begins handling all new search requests. The old searcher will be closed once it has finished servicing all its requests.

In Solr, there are three cache implementations: {{solr.search.LRUCache}}, {{solr.search.FastLRUCache,}} and {{solr.search.LFUCache}} .

The acronym LRU stands for Least Recently Used. When an LRU cache fills up, the entry with the oldest last-accessed timestamp is evicted to make room for the new entry. The net effect is that entries that are accessed frequently tend to stay in the cache, while those that are not accessed frequently tend to drop out and will be re-fetched from the index if needed again.

The {{FastLRUCache}}, which was introduced in Solr 1.4, is designed to be lock-free, so it is well suited for caches which are hit several times in a request.

Both {{LRUCache}} and {{FastLRUCache}} use an auto-warm count that supports both integers and percentages which get evaluated relative to the current size of the cache when warming happens.

The {{LFUCache}} refers to the Least Frequently Used cache. This works in a way similar to the LRU cache, except that when the cache fills up, the entry that has been used the least is evicted.

The Statistics page in the Solr Admin UI will display information about the performance of all the active caches. This information can help you fine-tune the sizes of the various caches appropriately for your particular application. When a Searcher terminates, a summary of its cache usage is also written to the log.

Each cache has settings to define it's initial size ({{initialSize}}), maximum size ({{size}}) and number of items to use for during warming ({{autowarmCount}}). The LRU and FastLRU cache implementations can take a percentage instead of an absolute value for {{autowarmCount}}.

Details of each cache are described below.

h3. {{filterCache}}

This cache is used by {{SolrIndexSearcher}} for filters (DocSets) for unordered sets of all documents that match a query. The numeric attributes control the number of entries in the cache.

Solr uses the {{filterCache}} to cache results of queries that use the {{fq}} search parameter. Subsequent queries using the same parameter setting result in cache hits and rapid returns of results. See [Searching] for a detailed discussion of the {{fq}} parameter.

Solr also makes this cache for faceting when the configuration parameter {{facet.method}} is set to {{fc}}. For a discussion of faceting, see [Searching].

{code:xml|borderStyle=solid|borderColor=#666666}
<filterCache class="solr.LRUCache"
             size="512"
             initialSize="512"
             autowarmCount="128"/>
{code}

h3. {{queryResultCache}}

This cache holds the results of previous searches: ordered lists of document IDs (DocList) based on a query, a sort, and the range of documents requested.

{code:xml|borderStyle=solid|borderColor=#666666}
<queryResultCache class="solr.LRUCache"
                  size="512"
                  initialSize="512"
                  autowarmCount="128"/>
{code}

h3. {{documentCache}}

This cache holds Lucene Document objects (the stored fields for each document). Since Lucene internal document IDs are transient, this cache is not auto-warmed. The size for the {{documentCache}} should always be greater than {{max_results}} times the {{max_concurrent_queries}}, to ensure that Solr does not need to refetch a document during a request. The more fields you store in your documents, the higher the memory usage of this cache will be. 

{code:xml|borderStyle=solid|borderColor=#666666}
<documentCache class="solr.LRUCache"
               size="512"
               initialSize="512"
               autowarmCount="0"/>
{code}

h3. User Defined Caches

You can also define named caches for your own application code to use. You can locate and use your cache object by name by calling the {{SolrIndexSearcher}} methods {{getCache()}}, {{cacheLookup()}} and {{cacheInsert()}}. 

{code:xml|borderStyle=solid|borderColor=#666666}
<cache name="myUserCache" class="solr.LRUCache"
                          size="4096"
                          initialSize="1024"
                          autowarmCount="1024"
                          regenerator="org.mycompany.mypackage.MyRegenerator" />
{code}

If you want auto-warming of your cache, include a {{regenerator}} attribute with the fully qualified name of a class that implements {{solr.search.CacheRegenerator}}. In Solr 4.5, you can also use the {{NoOpRegenerator}}, which simply repopulates the cache with old items. Define it with the {{regenerator}} parameter as {{"regenerator=solr.NoOpRegenerator"}}.

h2. Query Sizing and Warming

h3. {{maxBooleanClauses}}

This sets the maximum number of clauses allowed in a boolean query. This can affect range or prefix queries that expand to a query with a large number of boolean terms. If this limit is exceeded, an exception is thrown.

{code:xml|borderStyle=solid|borderColor=#666666}
<maxBooleanClauses>1024</maxBooleanClauses>
{code}

{warning}
This option modifies a global property that effects all Solr cores. If multiple {{solrconfig.xml}} files disagree on this property, the value at any point in time will be based on the last Solr core that was initialized.
{warning}

h3. {{enableLazyFieldLoading}}

If this parameter is set to true, then fields that are not directly requested will be loaded lazily as needed. This can boost performance if the most common queries only need a small subset of fields, especially if infrequently accessed fields are large in size.

{code:xml|borderStyle=solid|borderColor=#666666}
<enableLazyFieldLoading>true</enableLazyFieldLoading>
{code}

h3. {{useFilterForSortedQuery}}

This parameter configures Solr to use a filter to satisfy a search. If the requested sort does not include "score", the {{filterCache}} will be checked for a filter matching the query. For most situations, this is only useful if the same search is requested often with different sort options and none of them ever use "score".

{code:xml|borderStyle=solid|borderColor=#666666}
<useFilterForSortedQuery>true</useFilterForSortedQuery>
{code}

h3. {{queryResultWindowSize}}

Used with the {{queryResultCache}}, this will cache a superset of the requested number of document IDs. For example, if the a search in response to a particular query requests documents 10 through 19, and {{queryWindowSize}} is 50, documents 0 through 49 will be cached. 

{code:xml|borderStyle=solid|borderColor=#666666}
<queryResultWindowSize>20</queryResultWindowSize>
{code}

h3. {{queryResultMaxDocsCached}}

This parameter sets the maximum number of documents to cache for any entry in the {{queryResultCache}}.

{code:xml|borderStyle=solid|borderColor=#666666}
<queryResultMaxDocsCached>200</queryResultMaxDocsCached>
{code}

h3. {{useColdSearcher}}

This setting controls whether search requests for which there is not a currently registered searcher should wait for a new searcher to warm up (false) or proceed immediately (true). When set to "false", requests will block until the searcher has warmed its caches.

{code:xml|borderStyle=solid|borderColor=#666666}
<useColdSearcher>false</useColdSearcher>
{code}

h3. {{maxWarmingSearchers}}

This parameter sets the maximum number of searchers that may be warming up in the background at any given time. Exceeding this limit will raise an error. For read-only slaves, a value of two is reasonable. Masters should probably be set a little higher.

{code:xml|borderStyle=solid|borderColor=#666666}
<maxWarmingSearchers>2</maxWarmingSearchers>
{code}

h2. Query-Related Listeners

As described in the section on [#Caches], new Index Searchers are cached. It's possible to use the triggers for listeners to perform query-related tasks. The most common use of this is to define queries to further "warm" the Index Searchers while they are starting. One benefit of this approach is that field caches are pre-populated for faster sorting.

Good query selection is key with this type of listener. It's best to choose your most common and/or heaviest queries and include not just the keywords used, but any other parameters such as sorting or filtering requests.

There are two types of events that can trigger a listener. A {{firstSearcher}} event occurs when a new searcher is being prepared but there is no current registered searcher to handle requests or to gain auto-warming data from (i.e., on Solr startup). A {{newSearcher}} event is fired whenever a new searcher is being prepared and there is a current searcher handling requests. 

The listener is always instantiated with the class {{solr.QuerySenderListener}}, and followed a {{NamedList}} array. These examples are included with {{solrconfig.xml}}:

{code:xml|borderStyle=solid|borderColor=#666666}
<listener event="newSearcher" class="solr.QuerySenderListener">
    <arr name="queries">
    <!--
        <lst><str name="q">solr</str><str name="sort">price asc</str></lst>
        <lst><str name="q">rocks</str><str name="sort">weight asc</str></lst>
     -->
    </arr>
</listener>

<listener event="firstSearcher" class="solr.QuerySenderListener">
    <arr name="queries">
        <lst><str name="q">static firstSearcher warming in solrconfig.xml</str></lst>
    </arr>
</listener>
{code}

{note}
The above code sample is the default in {{solrconfig.xml}}, and a key best practice is to modify these defaults before taking your application to production. While the sample queries are commented out in the section for the "newSearcher", the example is not commented out for the "firstSearcher" event. There is no point in auto-warming your Index Searcher with the query string "static firstSearcher warming in solrconfig.xml" if that is not relevant to your search application.
{note}

{scrollbar}


Stop watching space: https://cwiki.apache.org/confluence/users/removespacenotification.action?spaceKey=solr
Change email notification preferences: https://cwiki.apache.org/confluence/users/editmyemailsettings.action