Test data

For the purpose of our tests I’ll use the data provided with the default Solr distribution. To run Solr and index the data I use the following command:

bin/solr start -e techproducts

Starting Solr using this command will result in both starting Solr and indexing the data to a new collection called techproducts.

The first example

Let’s start with a very simple example of using the new faceting module – let’s try running a query that will result in Solr returning a list of categories and manufactures of our products with counts. The query we are used to would look as follows:

curl 'localhost:8983/solr/techproducts/select?q=*:*&rows=0&indent=true&facet=true&facet.field=manu_id_s&facet.field=cat'

The query that will use the new faceting API looks as follows:

curl http://localhost:8983/solr/techproducts/query -d 'q=*:*&rows=0&
 json.facet={
  categories : {
   terms : {
    field: cat
   }
  },
  producers : {
   terms : {
    field: manu_id_s
   }
  }
 }'

The result returned by Solr is as follows:

{
  "responseHeader":{
    "status":0,
    "QTime":2,
    "params":{
      "q":"*:*",
      "json.facet":"{\n  categories : {\n   terms : {\n    field: cat\n   } \n  },\n  manu : {\n   terms : {\n    field: manu_id_s\n   }\n  }\n}",
      "rows":"0"}},
  "response":{"numFound":32,"start":0,"docs":[]
  },
  "facets":{
    "count":32,
    "categories":{
      "buckets":[{
          "val":"electronics",
          "count":12},
        {
          "val":"currency",
          "count":4},
        {
          "val":"memory",
          "count":3},
        {
          "val":"connector",
          "count":2},
        {
          "val":"graphics card",
          "count":2},
        {
          "val":"hard drive",
          "count":2},
        {
          "val":"search",
          "count":2},
        {
          "val":"software",
          "count":2},
        {
          "val":"camera",
          "count":1},
        {
          "val":"copier",
          "count":1}]},
    "manu":{
      "buckets":[{
          "val":"corsair",
          "count":3},
        {
          "val":"belkin",
          "count":2},
        {
          "val":"canon",
          "count":2},
        {
          "val":"apple",
          "count":1},
        {
          "val":"asus",
          "count":1},
        {
          "val":"ati",
          "count":1},
        {
          "val":"boa",
          "count":1},
        {
          "val":"dell",
          "count":1},
        {
          "val":"eu",
          "count":1},
        {
          "val":"maxtor",
          "count":1}]}}}

As we can see – both the query and the results is not somthing we are used to, let’s discuss both briefly.

Zapytanie

The second query has been sent do the query handler, but that is not that important. What we are interested in is the query itself. All the parameters of the query were not send as the HTTP request parameters, but instead we’ve included them in the request body, although still in a form that we are used to. In addition to that, we’ve included a new thing – the facet.json parameter, which will holds our faceting definition.

In Solr 5.1, each faceting definition we want to use should be defined as follows:

NAME: {
 TYPE: {
  PARAMETER: PARAMETER_VALUE
  ...
  PARAMETER: PARAMETER_VALUE
 }
}

In Solr 5.2 this format will be slightly changed, but we will get back to it once Solr 5.2 will be released. In our example we’ve used the terms faceting type, which works similar to the facet.field we are used to. The other possible types are for example query or range. Each of those type have a certain properties that can be used with them – we advise to visit offical Solr documentation to get information on what the parameters are.

The results

If we would look at the results returned by Solr we will see something called buckets. Those are key – value pairs that describe the returned faceting results. Something new, but we’ve already seen that with the standard faceting, just named differently. However, when using the new faceting API we can expect two types of responses – one is the buckets and the other is a single value. We will get back to it and describe why it is important when Solr 5.2 will be released.

Faceting and functions

Let’s try one more example – finding the average price for our products and the 99 percentile. With the new faceting API it is quick and easy – we can use functions in faceting. For example, the query that will fullfil our requirement looks as follows:

curl http://localhost:8983/solr/techproducts/query -d 'q=*:*&rows=0&
 json.facet={
  average:"avg(price)",
  percentile:"percentile(price,99)"
 }'

The response generated by Solr looks as follows:

{
  "responseHeader":{
    "status":0,
    "QTime":2,
    "params":{
      "q":"*:*",
      "json.facet":"{\n  average:\"avg(price)\",\n  percentile:\"percentile(price,99)\"\n }",
      "rows":"0"}},
  "response":{"numFound":32,"start":0,"docs":[]
  },
  "facets":{
    "count":32,
    "average":164.10218846797943,
    "percentile":1966.6484985351556}}

Solr returned the results we wanted in the form of single value for each faceting.

What’s next?

Of course the features we’ve looked at today is not all that Solr offers and will offer in the near future. First of all the number of functions that we can use in faceting will be extended – for example we will be able to calculate unique values. In addition to that, in Solr 5.2, we will get the ability to nest facets inside other facets and do calculations like – getting minimum price for each of the categories that we calculated using terms faceting.

Before we start

Because this post is more or less a continuation of what we’ve wrote earlier about autocomplete on multi-valued fields we recommend to read the “Autocomplete on multivalued field using highlighting” before reading the rest of this entry. We would also like to note, that the method shown in this entry is very similar to the one shown in the “Solr and autocomplete (part 1)” post, but we wanted to refresh that topic and show the example using multi-valued fields.

Configuration

Similar to the previous post we will start with Solr configuration.

Index structure

The structure of our index is exactly the same as the one previously shown, but let’s recall it. One thing – please remember that we want to have auto complete working on multi-valued field. This field is called features and the whole index fields configuration looks like this:

<fields>
 <field name="id" type="string" indexed="true" stored="true" required="true" multiValued="false" />
 <field name="features" type="string" indexed="true" stored="true" multiValued="true"/>
 <field name="features_autocomplete" type="text_autocomplete" indexed="true" stored="true" multiValued="true"/>

 <field name="_version_" type="long" indexed="true" stored="true"/>
</fields>

For getting values for auto complete we will use the features_autocomplete field.

Copy field

Of course we don’t want to change our indexer and we want Solr to automatically copy the data from features field to the features_autocomplete one. Because of that we will add the copyField definition to the schema.xml file, so it looks like this:

<copyField source="features" dest="features_autocomplete"/>

Our text_autocomplete field type

And we’ve come to the first difference – the text_autocomplete field type. This time it looks like this:

<fieldType name="text_autocomplete" class="solr.TextField" positionIncrementGap="100">
 <analyzer>
  <tokenizer class="solr.KeywordTokenizerFactory"/>
  <filter class="solr.LowerCaseFilterFactory"/>
 </analyzer>
</fieldType>

Because of the fact that we will use faceting we use the solr.KeywordTokenizerFactory with the solr.LowerCaseFilterFactory to have the data in our field as a single, lowercased token.

Example data

Our example data is identical to what we had before, but even though let’s recall them for things to be clear:

<add>
 <doc>
  <field name="id">1</field>
  <field name="features">Multiple windows</field>
  <field name="features">Single door</field>
 </doc>
 <doc>
  <field name="id">2</field>
  <field name="features">Single window</field>
  <field name="features">Single door</field>
 </doc>
 <doc>
  <field name="id">3</field>
  <field name="features">Multiple windows</field>
  <field name="features">Multiple doors</field>
 </doc>
</add>

Query with faceting

Let’s look how our query will look like when we will use faceting instead of highlighting.

Full query

When using faceting our query should look more or less like the following one:

q=*:*&rows=0&facet=true&facet.field=features_autocomplete&facet.prefix=sing

A few words about the parameters:

• rows=0 – we tell Solr that we don’t want the documents that matched the query in the results,
• facet=true – we inform Solr that we want to use faceting,
• facet.field=features_autocomplete – we say which field will be used to calculate faceting,
• facet.prefix=sing – with the use of this parameter we provide the value of a query for auto complete.

Query results

Query results returned by Solr for the above query are as follows:

<?xml version="1.0" encoding="UTF-8"?>
<response>
<lst name="responseHeader">
  <int name="status">0</int>
  <int name="QTime">0</int>
  <lst name="params">
    <str name="facet">true</str>
    <str name="q">*:*</str>
    <str name="facet.prefix">sing</str>
    <str name="facet.field">features_autocomplete</str>
    <str name="rows">0</str>
  </lst>
</lst>
<result name="response" numFound="3" start="0">
</result>
<lst name="facet_counts">
  <lst name="facet_queries"/>
  <lst name="facet_fields">
    <lst name="features_autocomplete">
      <int name="single door">2</int>
      <int name="single window">1</int>
    </lst>
  </lst>
  <lst name="facet_dates"/>
  <lst name="facet_ranges"/>
</lst>
</response>

As you can see in the field faceting section we got the phrases we were interested in along with the number of documents they appear in.

What to remember about

The crucial thing to remember is that the value provided to the facet.prefix parameter is not analyzed. Because of that if we would provide the Sing value instead of the singwe wouldn’t get the results. You should remember that.

A short summary

The above entry shown the second method used to develop auto complete functionality on multi-valued fields. Of couse we didn’t say all about the topic and we will get back to it someday, but for now that is all. We hope that someone will find it useful

The begining

LocalParams lets you tag part of the query, for example:

q=*:*&fq={!tag=city}city:warszawa

After sending the above query to Solr it will remember (in the context of the same query) that tag named city covers the filter with a value of city: warszawa. Now suppose that we want to send a query to get all documents that have the warszawa value in the city field (lets suppose that the city field is multi valued). In addition, we want to Solr to show us the number of documents in all cities. Nothing could be simpler with the use of LocalParams – just use the parameter {!ex} in the faceting. This could possibly be done by sending the following query to Solr:

q=*:*&fq={!tag=miasto}city:warszawa&facet=true&facet.field={!ex=miasto}city

The above query will return documents that have the warszawa value in the city field and faceting calculated on the city field which is not narowed by the filter query, because we excluded that filter.

Query parser type

Of course, the use of LocalParams is not limited to faceting. One of the interesting examples is a type handler definition. If we use standard query parser, we can change its type for a particular query with this structure:

q={!type=dismax qf=city}warszawa

The above query will use the dismax query parser and pass the qf=city parameter to it along with the warszawa value in the q parameter.

Logical operator

Changing the default logical operator using LocalParams is also very simple:

q={!q.op=AND}warszawa praga

The above query uses the AND logical operator for terms contained in the parameter q, which are warszawa and praga.

Parameter dereferencing

Additionally, by using LocalParams we can achieve an interesting feature – the parameters dereferencing. For example, if we want to use your own parameter names in queries, we can do it this way:

q={!type=dismax qf=city v=$pmiasto}&pmiasto=warszawa

Solr does not support default parameter named pmiasto, but with the key v (meaning value) and use of the reference operator $ it was possible to transfer the value of such a named parameter to the query.

I recommend that everyone who wants to use this feature in your application to play with LocalParams and find out if they fit your needs.

More information

Actual information about LocalParams and Solr can be found at Apache Solr wiki at the following address: http://wiki.apache.org/solr/LocalParams.

Indeks

Suppose you want to show some hints to the user in the on-line store, for example you want to show products name. Suppose that our index is composed of the following fields:

<field name="id" type="string" indexed="true" stored="true" multiValued="false" required="true"/>
<field name="name" type="text" indexed="true" stored="true" multiValued="false" />
<field name="description" type="text" indexed="true" stored="true" multiValued="false" />

A text type is defined as follows:

<fieldType name="text" class="solr.TextField" positionIncrementGap="100">
 <analyzer>
  <tokenizer class="solr.WhitespaceTokenizerFactory"/>
  <filter class="solr.WordDelimiterFilterFactory" generateWordParts="1" generateNumberParts="1" catenateWords="1" catenateNumbers="1" catenateAll="0" splitOnCaseChange="1"/>
  <filter class="solr.LowerCaseFilterFactory"/>
 </analyzer>
</fieldType>

Configuration

To start, consider what you want to achieve – do we want to suggest only individual words that make up a name, or maybe full names that begin with the letters specified by the user. Depending on our choices we have to prepare the appropriate field on which we will build hints.

Prompting individual words that make up the name

In the case of single words, we should use a field that is tokenized. In our case, the field named name will be sufficient. However, note that if you want to use for example stemming you should define another type, which do not use stemming because of how this analysis operates on the contents of the field.

Prompting full name

For full names of the products suggestions we need a different field configuration – the best for this will be a untokenized field. But we can not use string based field for that. For this purpose, we define the field as follows:

<field name="name_auto" type="text_auto" indexed="true" stored="true" multiValued="false" />

This type is defined as follows:

<fieldType name="text_auto" class="solr.TextField">
 <analyzer>
  <tokenizer class="solr.KeywordTokenizerFactory"/>
  <filter class="solr.LowerCaseFilterFactory"/>
 </analyzer>
</fieldType>

To not modify the format of the data we also add the appropriate definition of the copy information:

<copyField source="name" dest="name_auto" />

How do we use it ?

To use the data we prepared we use a fairly simple query:

q=*:*&facet=true&facet.field=FIELD&facet.mincount=1&facet.prefix=USER_QUERY

Where:

• FIELD – field on the basis of which we intend to make suggestions. In our case the field named name_auto.
• USER_QUERY – letters entered by the user.

It is worth noting rows=0 parameter is added here to only show the faceting result without the query results. Of course, this is not a necessity.

An example query would look like that:

fl=id,name&rows=0&q=*:*&facet=true&facet.field=name_auto&facet.mincount=1&facet.prefix=har

The result of this query might look like this::

<response>
 <lst name="responseHeader">
  <int name="status">0</int>
  <int name="QTime">0</int>
 </lst>
 <result name="response" numFound="4" start="0"/>
 <lst name="facet_counts">
  <lst name="facet_queries"/>
  <lst name="facet_fields">
   <lst name="name_auto">
    <int name="hard disk">1</int>
    <int name="hard disk samsung">1</int>
    <int name="hard disk seagate">1</int>
    <int name="hard disk toshiba">1</int>
   </lst>
  </lst>
  <lst name="facet_dates"/></lst>
</response>

Additional features

It is worth to mention the additional opportunities which are inherent to this method.

The first possibility is to show the user additional information such as number of results that you get when you select an appropriate hint. If you want to show such information it will certainly be an interesting option.

The next thing is sorting with the use of facet.sort parameter. Depending on your needs, we can sort the results by the number of documents (the default behavior, parameter set to true) or alphabetically (value set to false).

We may limit the suggestions to those which have more results than a specified number. To take advantage of this opportunity pass in a parameter facet.mincount with the appropriate number.

And as for me the biggest advantage of this method is the possibility of getting only those suggestions that not only match the letters that the user typed but also some other parameters, like category for example. For example, we want to show hints for the user who is in the household section of our store. We suspect that at this moment the user will not be interested in DVD-type products, and therefore we add a parameter fq=department:homeAppliances (assuming that we have such a department). After such a modified query, you do not get hints generated from the entire index, we only get those narrowed to the selected department.

A few words at the end

As other method, this one too, have its advantages and disadvantages. The advantage of this solution is its ease of use, no additional components requirement, and that the result hints can be easily narrowed to be generated only from those documents that match the query entered by the user. As a big plus is that the method includes number of result that will be shown after selecting the hint (of course with the same search parameters). For the downside is definitely need to have additional types and fields, quite limited abilities and the load caused by the use of faceting mechanism.

The next entry about the autocomplete will try to expand on and show a further methods of generating hints using Solr.

One of the few sources of information about faceting is Solr wiki – to be more specific – the page at: http://wiki.apache.org/solr/SimpleFacetParameters. The following article is an extension to the information available on the wiki website.

Solr faceting mechanism can be divided into four basic types:

• field faceting,
• query faceting,
• date faceting,
• range facteing.

To turn Solr faceting mechanism on, one need to pass facet parameter with the value true.

Field faceting

First type of faceting. This type of faceting categorize documents found due to specified field. With this type of faceting we are able to get a number of documents found for example in each category or geographical location. Faceting by field is characterized by a large number of options which configure its behavior. This are the parameters available for use:

• facet.field – parameter specifying which field will be used to perform faceting. This parameter can be specified multiple times. Remember that adding multiple facet.field parameters to the query can affect performance.
• facet.prefix – restricts faceting results to those that begin with the specified prefix. The parameter can be defined for each field specified by the facet.field parameter – you can do it, by adding a parameter like this: facet.field_name.prefix. This parameter is a relatively simple way to implement autocomplete mechanism.
• facet.sort – specifies how to sort faceting results. If You use Solr version lower than 1.4, this parameter takes values of true or false indicating successively – sort by the number of results and sort by index order (in the case of ASCII this means alphabetical sorting). If however You are using Solr version 1.4 or higher You should use count value (meaning the same as true), or index value (meaning the same as false). The default value for this parameter is true/count when facet.limit set to 0 or false/index for other values of facet.limit parameter. The parameter can be defined for each field specified by the facet.field parameter.
• facet.limit – parameter specifying how many unique values of faceting results to display. A negative value for this parameter mean no limit. Please note that the larger the limit, the more memory you need and the longer query execution. Default parameter value is 100. The parameter can be defined for each field specified by the facet.field parameter.
• facet.offset – parameter defining from offset (from the first faceting result) of presented faceting results. Default parameter value is 0. This parameter is designed to help implementing faceting result paging. The parameter can be defined for each field specified by the facet.field parameter.
• facet.mincount – parameter specifying the minimum size of result to be included in faceting results. The default value is 0. The parameter can be defined for each field specified by the facet.field parameter.
• facet.missing – parameter specifying whether, in addition to standard faceting results, number of documents without a value in the specified field should be included. This parameter can take values of true or false. The default parameter value is false. The parameter can be defined for each field specified by the facet.field parameter.
• facet.method – parameter introduced in Solr 1.4. It takes the value of enum or fc. Specifies a method for faceting calculation. Setting this parameter to enum effects in using term enumeration to calculate faceting results. This method is proven to be most efficient when dealing with fields with small number of unique terms. The second method, labeled fc, is the standard method for faceting calculation. It takes all the results and iterate over all documents in the result set. The parameter can be defined for each field specified by the facet.field parameter. The default value is fc for all the fields not based on Boolean type.
• facet.enum.cache.minDf – parameter with strange sounding name specifying the minimum number of matching documents to a single term to the fc method to be used for faceting result calculation. I know it sounds strange but i do not know how to explain it easier

These are the parameters of field faceting. In case of most parameters I have written that there is a possibility to define their values for each field specified by facet.field parameter. How does it look like ? Suppose we have a query like this:

q=solr&facet=true&facet.field=category&facet.field=location

It is a simple query for ‘solr’ term with faceting mechanism turned on. There are two facet fields defined – category and location. Lets say, that we would like to have 200 facet results for category field sorted by count and 50 facet results for location field sorted alphabetically. To do that we add the following fragment to the query shown above:

facet.category.limit=200&facet.category.sort=count&facet.location.limit=50&facet.location.sort=index

As shown we can easily modify facet mechanism behavior for individual facet fields.

Query faceting

Facet mechanism based on a single parameter – facet.query to which we give a query. The query passed to the parameter must be constructed so that standard Lucene query parser can understand it. An example use of this parameter is, for example query a group of pricing, which could look like:

facet.query=price: [0+TO+100]

Note, however, that each added facet.query parameter is another query to Lucene, which means performance loss. Many facet.query parameters in a query can be painful to Solr.

There is one more thing worth mentioning when talking about query faceting – there is a possibility to define your own parser to parse facet.query parameter value. To use your own parser, for example, called myParser parameter passed to Solr should look like this:

facet.query={!myParser}aaa

Date faceting

New faceting functionality introduced in Solr 1.3. Date faceting allows you to calculate faceting results including all the intricacies of processing dates. Please note that date faceting can only be used with fields based on the type solr.DateField. Now let’s get on with the parameters associated with date faceting:

• facet.date – like facet.field parameter, this parameter is used to identify fields where dates faceting should be used. As in the case of facet.field parameter you can specify this parameter several times to allow date faceting on many fields in one query.
• facet.date.start – parameter specifying the lower limit of date on which the faceting calculation should be started. This parameter can be defined for each field specified by the facet.date parameter. This parameter is mandatory when using facet.date and should be defined for each facet.date parameter.
• facet.date.end – parameter defining the upper limit of the date, on which the faceting calculation should be ended. This parameter can be defined for each field specified by the facet.date parameter. This parameter is mandatory when using facet.date and should be defined for each facet.date parameter.
• facet.date.gap – parameter specifying date compartments to be generated for the defined boundaries. This parameter is mandatory when using facet.date and should be defined for each facet.date parameter. The parameter can be defined for each field specified by the facet.date parameter.
• facet.date.hardend – parameter taking values true and false, telling Solr what to do in the case when the parameter facet.date.gap is not evenly splitting the compartments. If we set this parameter to true the last compartment generated by facet.date.gap parameter can be wider than the boundary defined by facet.date.end parameter. If we set this parameter to false (default value) the last compartment generated by facet.date.gap parameter can be smaller then the rest of the ranges. The parameter can be defined for each field specified by the facet.date parameter.
• facet.date.other – parameter specifying what values besides the standard ones (ranges) should be added to results of date faceting. The parameter can be defined for each field specified by the facet.date parameter. The parameter can take following values:
  • before – in addition to the standard date faceting results, there will be one more – number of documents with a date before the one defined in the facet.date.start parameter,
  • after – in addition to the standard date faceting results, there will be one more – number of documents with the date after the one defined in the facet.date.end parameter,
  • between – in addition to the standard date faceting results, there will be one more – number of documents with the date between facet.date.start and facet.date.end parameters,
  • all – a shortcut to define all the above,
  • none – none of the additional results will be added to date faceting results.
• facet.date.include – parameter that will be introduced in Solr 4.0. It allows of closing or opening of the compartments defined by the boundaries and the gap. The parameter will accept the following values:
  • lower – each of the resulting compartment will contain its lower limit,
  • upper – each of the resulting compartment will contain its upper limit,
  • egde – the first and last interval will include its external borders – that is, for the first lower and upper range for the last interval,
  • outer – a parameter specifying that the compartments defined by the values before and after of the facet.date.other parameter will contain its borders, even if other compartments already contain these borders,
  • all – a parameter that causes the inclusion of all of the above options.

That is how we can modify the behavior of the date faceting. Now, some example of using this kind of faceting:

q=solr&facet=true&facet.date=addDate&facet.date.start=NOW/DAY-30DAYS&facet.date.end=NOW/DAY%2B30DAYS&facet.date.gap=%2B1DAY

What does the above query do ? We turn the faceting mechanism on, we define date faceting for addDate field. What we want to get is the compartments between 30 days before today (NOW/DAY-30DAYS) and 30 days after today (NOW/DAY+30DAYS). The compartments will be of the size of a single day.

Range faceting

Functionality which will be available in Solr 3.1. If someone want to test it right now, both the trunk and branch 3.x have this functionality implemented. This method of faceting is the extension of date faceting. This functionality works similar to date faceting – as a result we get a list of compartments constructed automatically based on parameters. Here are the list of parameters that can be used to define range faceting behavior:

• facet.range – like facet.field parameter, this parameter is used to identify fields where range faceting should be used. As in the case of facet.field parameter you can specify this parameter several times to allow range faceting on many fields in one query.
• facet.range.start – parameter specifying the lower limit of range on which the faceting calculation should be started. This parameter can be defined for each field specified by the facet.range parameter. This parameter is mandatory when using facet.range and should be defined for each facet.range parameter.
• facet.range.end – parameter defining the upper limit of the range, on which the faceting calculation should be ended. This parameter can be defined for each field specified by the facet.range parameter. This parameter is mandatory when using facet.range and should be defined for each facet.range parameter.
• facet.range.gap – parameter specifying range compartments to be generated for the defined boundaries. This parameter is mandatory when using facet.range and should be defined for each facet.date parameter. The parameter can be defined for each field specified by the facet.date parameter.
• facet.range.hardend – parameter taking values true and false, telling Solr what to do in the case when the parameter facet.range.gap is not evenly splitting the compartments. If we set this parameter to true the last compartment generated by facet.range.gap parameter can be wider than the boundary defined by facet.range.end parameter. If we set this parameter to false (default value) the last compartment generated by facet.range.gap parameter can be smaller then the rest of the ranges. The parameter can be defined for each field specified by the facet.rangeparameter.
• facet.range.other – parameter specifying what values besides the standard ones (ranges) should be added to results of range faceting. The parameter can be defined for each field specified by the facet.range parameter. The parameter can take following values:
  • before – in addition to the standard range faceting results, there will be one more – number of documents with a values lower than the one defined in the facet.range.start parameter,
  • after – in addition to the standard range faceting results, there will be one more – number of documents with the values higher than the one defined in the facet.range.end parameter,
  • between – in addition to the standard range faceting results, there will be one more – number of documents with the values between facet.range.start and facet.range.end parameters,
  • all – a shortcut to define all the above,
  • none – none of the additional results will be added to range faceting results.
• facet.range.include – parameter allowing closing or opening of the compartments defined by the boundaries and the gap. The parameter will accept the following values:
  • lower – each of the resulting compartment will contain its lower limit,
  • upper – each of the resulting compartment will contain its upper limit,
  • egde – the first and last interval will include its external borders – that is, for the first lower and upper range for the last interval,
  • outer – a parameter specifying that the compartments defined by the values before and after of the facet.range.other parameter will contain its borders, even if other compartments already contain these borders,
  • all – a parameter that causes the inclusion of all of the above options.

As you can see the range faceting parameters are almost identical to those in date faceting. The behavior is also almost identical. An example query using ranges faceting may be the following query:

q=solr&facet=true&facet.range=price&facet.range.start=0&facet.range.end=1000&facet.range.gap=100

So, we went through all of the types of faceting. But thats not all. Users of Solr version 1.4 and higher have the opportunity to use the so-called LocalParams.

LocalParams and faceting

Suppose we have a requirement. We have a query that returns search results for the term ‘solr’ and in which we have defined two filters, one for category and one for the country of origin of the document. In addition to the search results we want to enable navigation through the regions and categories, but we would like them not to be dependend on each other. That is, we want to give the opportunity to navigate through the regions for the term ‘solr’ but we dont want it to be limited to the selected category, and vice versa. To do it in Solr version 1.3 or earlier, we would write the following query:

q=solr&fq=category:search&fq=region:poland
q=solr&facet=true&facet.field=category&facet.field=region

Two queries, because first we have to get narrowed search results, on the other hand we need the faceting result not to be narrowed by filters. For Solr version 1.4 or higher, we can shorten this to one query. For this purpose, we use the possibility of tagging and exclusion of tagged parameters. First we change the query as follows:

q=solr&fq={!tag=categoryFQ}fq=category:search&fq={!tag=regionFQ}region:poland

For now, the search results will not change. We added tags to the filters in the above query so we can later exclude them in faceting. Then we modify the second query as follows:

q=solr&facet=true&facet.field={!ex=categoryFQ,regionFQ}category&facet.field={!ex=categoryFQ,regionFQ}region

So far the faceting results will not change. We added exclusions to the facet.field parameters, so filters named categoryFQ and regionFQ will not be taken into consideration when calculating faceting results.

Then we combine the modified query, so it should look as follows:

q=solr&fq={!tag=categoryFQ}fq=category:search&fq={!tag=regionFQ}region:poland&facet=true&facet.field={!ex=categoryFQ,regionFQ}category&facet.field={!ex=categoryFQ,regionFQ}region

I`ll write more about LocalParams in a future entries.

A few words at the end

I hope that this article approached the possibility of using Solr faceting, both in earlier versions of Solr, in the present, as well as those that arise in the nearest future.

1. Lack of filters

One of the fundamental errors that I encounter from time to time is the lack of filters, which in context of query means no fq parameter. Let us remember that filters are out friends Remember that because of filters Solr cache is used more optimally. Filter do not affect relevance of the document in the context of query and search results (score factor), and thus, we can perform filtering without fear of the change in the score value of individual documents (useful for example in e-commerce for product groups narrowing).

2. Logical conditions and q parameter

Another of the “sins” that I come across quite often is a one with close relationship with the previous point. It’s not a bug in the literal sense, but it is an area where a simple change will have a significant influence on performance. Assuming that the default logical operator is OR, imagine your query in the form of: q=(java+design+patterns)+AND+category:books+AND+promotion:true+AND+publisher:ABC. This query is correct from the perspective of the application logic, where we get the appropriate group search results. But what if we also want to optimally use Solr cache and thus boost performance. The anserw is quite simple – move some of the terms to filters. By changing out a query to q=java+design+patterns&fq=category:books&fq=promotion:true&fq=publisher:ABC Solr benefit from two types of cache – queryDocumentCache to retrieve documents for a query with parameter q and the filterCache for each of the filters. With the change of the query we were able to optimize the query to use two types of cache and in addition to optimize the entries of queryDocumentsCache (due to the shortening of the query parameter q).

3. Hugh numbers of facet queries

Another “sin” associated with handling groups of documents. Quite often, especially, in applications that can categorize products in many ways, I have met queries with a lot of facet.query parameters that correspond to the grouping of documents. Grouping by price, location, product groups, and so on. A good example is grouping by price where the business customer can set the price ranges for each category and then application must group products by those ranges. This leads to queries that have 100, 200 or more facet.query parameters added. Please remember that each facet.query has an impact on efficiency, not to mention 100 or 200 of them. If we are interested in a quick response from Solr we can not make such a queries. In such cases, I always propose modifying the index structure if needed, and they are needed in most cases. Some modifications (like defining ranges at index time) allows to eliminate tens or hundreds of facet.query for one facet.field parameter. But this method is associated to another problem – explanation for the customer, why “re-index button” must be pressed after range changes. As a rule, however, performance testing at high loads and large variety of queries speak for themselves.

4. Facet limits

The problem appears in the line where Solr meets business logic. An example of this “sin” is a simple list of categories that a customer wants to have displayed depending on user location on the website. When we have a small numbers of categories we do not have a problem, but what about thousands of categories. Very often, I met with the approach taken by the developers to retrieve all categories of Solr (with increased facet.limit parameter compared to the default value) and choose the right categories in the application that is using Solr. I think this approach can generate problems – first of all faceting requires memory, second aggregating of facet elements need time, and of course getting all of the 50.000 categories with it’s counts can be painful to Solr. If we want a fast queries, try to use the parameter facet.limit reasonable. If You need many facet results try to build your application so it can use facet.offset parameter and therfore use paging. If this is not possible, at least configure Your container to have enough memory to handle parallel queries and get ready to have queries that can perform longer when having high facet.limit value.

5. Downloading of unnecessary data

Very common problem is the retrieval of all information, not just those that we need. Of course, the problem does not apply to deployments where Sole offers information such as, for example, only the product ID. However, a large number of deployments that I’ve deal with was based almost entirely on Solr, and hence Solr index was made up of multiple stored fields. Developers using Solr very rarely used the parameter fl and the possibility of limiting the fields that are returned. In extreme cases, this led to problems with the amount of data that had to be sent over the network.

6. Many requests to obtain count of groups of documents

In some applications more important than the actual search capabilities were the navigation, where users can browse document repository by it’s feature, like department, category, subcategory, and so on. Very often, in addition to names there are also numbers displayed – the numbers of documents with this feature. I met cases were the number of documents were obtained using a separate query. Effect – 100 categories displayed on a web page led to 100 separate queries to Solr. Do not go this way, if You have to modify the Solr index to use the facet mechanism. Maybe at that time it will be more work, but certainly in the long run this is worth it.

A few words at the end

Please note that these are just examples that I think are fairly universal, at least, which I quite often encountered during my work. They are not all the errors that happen when using the Solr, but I hope to highlight some of the mistakes people tend to make and how to go around them.