The problem

When documentCache is present in solrconfig.xml after the first time a field is retrieved from Lucene Solr will cache its value along with the document and store it in the documentCache. This can be very expensive, especially for large stored fields – image a situation when you have the documents OCRed from a book and you show the content of the pages. If you don’t reuse such data, so basically a lot hit ration in the documentCache, will result in more garbage produced by Solr itself and thus JVM garbage collector having harder time to clean that up. That can lead to higher CPU usage and worse performance of Solr in general. Let’s look at what we can do with such large, stored fields.

Marking the field as large

Starting with Solr 6.5 we got the ability to add additional property to the field definition, one called large which takes a value of true or false by default being false. Field that we want to mark as large should be set as stored=”true” and multiValued=”false”. In such cases, setting the large=”true” property on the field definition will make the field value not cached inside the documentCache.

Noticing the difference

Because this is a quick look type of post, I don’t want to get into too much specifics, but I would like to compare two collections with the same data. Each collection have the same set of fields:

• id – identifier of the document,
• name – name of the document,
• body – text of the document, which can be very, very large.

One collection will have the large=”true” for the body field and the other won’t have that property set. We will also index a few large documents and see how documentCache behaves.

So here are the commands to setup those two collections using Solr.pl Github account (https://github.com/solrpl/). First setup one collection and gather statistics and then remove all the files, restart Solr, create the second collection and gather statistics. The commands are as follows:

$ mkdir /tmp/solr
$ mkdir /tmp/solr/collection_with_large
$ mkdir /tmp/solr/collection_without_large
$ wget https://github.com/solrpl/blog/tree/master/posts/large_field/data.xml /tmp/solr/data.xml
$ wget https://github.com/solrpl/blog/tree/master/posts/large_field/collection_with_large/managed-schema /tmp/solr/collection_with_large/managed-schema
$ wget https://github.com/solrpl/blog/tree/master/posts/large_field/collection_with_large/solrconfig.xml /tmp/solr/collection_with_large/solrconfig.xml
$ wget https://github.com/solrpl/blog/tree/master/posts/large_field/collection_without_large/managed-schema /tmp/solr/collection_without_large/managed-schema
$ wget https://github.com/solrpl/blog/tree/master/posts/large_field/collection_without_large/solrconfig.xml /tmp/solr/collection_without_large/solrconfig.xml
$ bin/solr zk upconfig -z localhost:9983 -n config_with_large -d /tmp/collection_with_large
$ bin/solr create_collection -c collection_with_large -n config_with_large -shards 1 -replicationFactor 1
$ curl -XPOST 'localhost:8983/solr/collection_with_large/update?commit=true' -H 'Content-Type:application/xml' --data-binary @/tmp/solr/data.xml
$ curl 'localhost:8983/solr/collection_with_large/select?q=*:*'

And now let’s create the second collection using the downloaded data:

$ bin/solr zk upconfig -z localhost:9983 -n config_without_large -d /tmp/collection_without_large
$ bin/solr create_collection -c collection_without_large -n config_without_large -shards 1 -replicationFactor 1
$ curl -XPOST 'localhost:8983/solr/collection_without_large/update?commit=true' -H 'Content-Type:application/xml' --data-binary @/tmp/solr/data.xml
$ curl 'localhost:8983/solr/collection_without_large/select?q=*:*'

And now, let’s check the usage of the documentCache that we’ve gathered. So we have this for the collection with the body field marked as large=”true”:

And we have this for the collection with the body field without the large=”true” property:

As you can see, the field marked with large=”true” was not put into the documentCache directly, but only as a lazy loaded large field, which is what we were aiming for. This means, that we can still use the documentCache and not worry about Solr putting the large, stored fields there, which was the case in the second example.

Parameter cache=false

Setting the cache parameter to false we tell Solr not to cache current query results. This parameter can also be used as a filter query (fq) attribute, which tell Solr not to cache filter query results. What do we get from such behavior ? Let’s imagine the following filter as a part of the query:

fq={!frange l=10 u=100}log(sum(sqrt(popularity),100))

If we know that the queries with filter like the above one are rare, we can decide not to cache them and not change cache state for irrelevant data. To do that we add the cache=false attribute in the following way:

fq={!frange l=10 u=100 cache=false}log(sum(sqrt(popularity),100))

As I told, adding this additional attribute will result in the filter results not being cached.

Parameter cost

The additional feature of Solr 3.4 is the possibility to set filter cost in case of those filters that we don’t want to cache. Filter queries with specified cost are executed as last ones after all the cached filters. The cost attribute is specified as the integer value. Let’s look at the following example filters:

fq=cat:video&fq={!cache=false cost=50}productGroup:12&fq={!frange l=10 u=100 cache=false cost=150}log(sum(sqrt(popularity),100))

The first filter to execute will be the fq=cat:video one because it is cached. The next one to evaluate will be the one with lesser cost value, so the fq={!cache=false cost=50}. The last filter to evaluate will be the most expensive filter. In addition the last filter will operate only on documents that match the main query and all previous filters (because its cost attribute is higher than 100).

You should remember that cost attribute work only when the filter query is not cached.

To sum up

With cache and cost attributes we can control what we place in Solr cache, which is very good in most situation, when we know what queries are sent to Solr instances. Whats more, using those attributes we can improve query performance, for those queries that have filters with cost higher than 100. I think it’s worth to take a while, look at Your queries and think about if You need to cache all of those

What it contains ?

So let’s start with information about the information that documentCache holds. So documentCache contain Lucene documents that were fetched from the index. So little and so much.

What it is used for ?

Every object (Lucene document) stored in documentCache contains a list of references to the fields, that are stored with the document. Thanks to this, when a document is fetched and put into the cache it doesn’t have to be fetched again while processing another query. And this is why the number of I/O operations is reduces when rendering the query results list.

What to remember when using documentCache ?

When using documentCache you have to remember about to important things:

1. documentCache can’t be autowarmed because it operates on identifiers that change after every commit operation.
2. If you use lazy field loading (enableLazyFieldLoading=true) documentCache functionality is somehow limited. This means that the document stored in the documentCache will contain only those fields that were passed to the fl parameter. If the next query will try to get additional fields for the document stored in the cache, those additional fields will be fetched from the index.

Definition

The standard documentCache definition looks like this:

<documentCache
      class="solr.FastLRUCache"
      size="16384"
      initialSize="16384"/>

Let’s recall those parameters:

• class – class implementing the cache,
• size – the maximum cache size,
• initialSize – initial size of the cache.

How to configure ?

The usual question about cache – what size should I set ? According to the information from Solr wiki (http://wiki.apache.org/solr/SolrCaching#documentCache), the maximum size shouldn’t be less than the product of concurrent queries and the maximum number of documents fetched by the query. A simple relation that should ensure that Solr won’t have to fetch documents from the index during query processing.

Last few words

In the case of documentCache we don’t have to worry about how we construct our queries to properly use this cache. But please remember that documentCache requires memory, the more memory, the more field you stored in the index.

What it is used for ?

Let’s start from the inside. FilterCache stores unordered collection of identifiers of documents. Of course, these are not the IDs defined in the schema.xml file as a unique key – Solr stores the internal IDs of the documents used by Lucene and Solr – it is worth remembering.

What it is used for ?

The main task of the filterCache is to keep results related to the use of filters. Although it is not his only use. In addition, the cache can serve as an aid for faceting mechanism (if using the TermEnum method), and for sorting when <useFilterForSortedQuery/> option is set to true in the solrconfig.xml file.

Definition

FilterCache standard definition is as follows:

<filterCache
      class="solr.FastLRUCache"
      size="16384"
      initialSize="4096"
      autowarmCount="4096" />

You have the following configuration options:

• class – class is responsible for implementation. For filterCache recommend using solr.FastLRUCache, which is characterized by greater efficiency in a larger number of operations GET, PUT than that.
• size – the maximum number of entries that can be found in the cache.
• initialSize – initial size of the cache.
• autowarmCount – the number of entries that will be transcribed during the warm-up from the old to the new cache.
• minSize – value specifying to which the number of entries Solr will try to reduce the cache in case of full restoration.
• acceptableSize – if Solr will not be able to bring the number of entries to the specified by parameter minSize, the value acceptableSize will be the one to which it will seek a new one.
• cleanupThread – the default value is false. If set to true to clean the cache will be used a separate topic.

In most cases, the use of size , and initialSize and autowarmCount parameters is quite sufficient.

How to configure ?

The size of the cache should be determined on the basis of queries that are sent to Solr. The maximum size filterCache should be at least as large as the number of filters (with values) that we use. This means that if your application is, in a given period of time, using 2000 for example (fq parameters with values), the size parameter should be set to a minimum value of 2000.

Efficient use

However, the configuration of the cache is not sufficient – we need to make the query to be able to use it. Take the following query for example:

q=name:solr+AND+category:ksiazka+AND+section:ksiazki

At first glance, the query is the correct. However, there is a problem – it does not use filterCache. The entire request will be handled by queryResultCache and will create a single entry in it. Let’s modify it a bit and send the following query.

q=name:solr&fq=category:ksiazka&fq=section:ksiazki

What happens now? As in the previous case, an entry will be created in queryResultCache. Additionaly there will be two entries in filterCache created. Now let’s look at the next query:

q=name:lucene&fq=category:ksiazka&fq=section:ksiazki

This query would create another entry in the queryResultCache and would use two already existing entries in the filterCache. Thus the execution time of the query would be reduced and the query would be less demanding for the I/O.

However, let’s look at the query in the following form:

q=name:lucene+AND+category:ksiazka+AND+section:ksiazki

Solr would not be able to use any information from the cache and would have to collect all the information for the results of the Lucene index.

Last few words

As you can see, the correct way to configure cache is not what guarantee that Solr will be able to use it. The efficiency of the target implementation depends on how the queries are send to Solr. It is worth remembering when planning implementation.

The begining

To start talking about this configuration parameter, we must first say how Solr fetches results from the index. When passing the rows parameter to Solr, with the value of 20 for example, we tell Solr that we want the result list to contain the maximum of 20 documents. However, the number of results, which was taken from the index varies and is determined precisely by the queryResultWindowSize parameter. This parameter, defined in the solrconfig.xml file, determines how many results will be retrieved from the index and stored in queryResultCache.

But what can I use queryResultWindowSize for ?

The queryResultWindowSize parameter specifies the size of so called results window, which is simply the number of documents that will be fetched from the index when retrieving search results.  For example, setting queryResultWinwdowSize to 100 and send the following query:

q=car&rows=30&start=10

will result in a maximum of 30 documents in the search result list, however Solr will fetch 100 documents from the index (starting at index 0 and ending at index 100) and then try Solr will place them in queryResultCache. The next query, which will differ only in the parameters start and rows can be retrieved from queryResultCache.

Configuration

To set the queryResultWindowSize to the value of 100, you must add the following entry to the solrconfig.xml file:

<queryResultWindowSize>100</queryResultWindowSize>

What to remember ?

Of course, setting only the queryResultsWindowSize is not everything. You should still provide adequate space in queryResultCache for Solr to be able to store the necessary information. However queryResultCache configuration is a topic for another article.

But why use it ?

The answer to that question is quite simple – if your application and your users often use the paging it is reasonable to consider changing the default value of the queryResultWindowSize. In most cases, where the implementation was based on paging, changing the value of this parameter caused a severe increase in performance when switching between query pages of the results.