Solr provides a [ Simple Faceting toolkit] which can be reused by various Request Handlers to include "Facet counts" based on some simple criteria. Both the StandardRequestHandler and the DisMaxRequestHandler currently use these utilities. Detailed descriptions of the parameters used to control faceting can be found (along with several examples) at [SimpleFacetParameters].

This page briefly provides some general background information:

Facet Indexing

Faceting is done on indexed rather than stored values. This is because the primary use for faceting is drill-down into a subset of hits resulting from a query, and so the chosen facet value is used to construct a filter query which literally matches that value in the index. For the stock Solr request handlers this is done by adding an fq=<facet-field>:<quoted facet-value> parameter and resubmitting the query.

Because faceting fields are often specified to serve two purposes, human-readable text and drill-down query value, they are frequently indexed differently from fields used for searching and sorting:

As an example, if I had an "author" field with a list of authors, such as:

I might want to index the same data differently in three different fields (perhaps using the Solr [:SchemaXml#Copy Fields:copyField] directive):

Then when the user drills down on the "Schildt, Herbert" string I would reissue the query with an added fq=author:"Schild, Herbert" parameter. If you wanted to drill-down or query by multiple authors you would add more 'fq' parameters as needed, e.g. fq=author:"Schield, Herbet"&fq=author:"Wolpert, Lewis".

Facet Operation

Currently SimpleFacets has 3 modes of operation, selected by a combination of SimpleFacetParameters, Response Handler parameters and [:SchemaXml: schema.xml] Field definitions:


Any number of [:SimpleFacetParameters#facet.query:facet.query] parameters can be passed to the request handler. Each distinct facet.query will first be executed against the entire index, with the results cached as a hashed set (if fewer than hashDocSet) or a bit set (if greater) of document IDs (see [:SolrCaching#The hashDocSet Max Size:hashDocSet]). Then, every time that facet.query is used for faceting a query, the cached set will be intersected against the set of document IDs returned by the query to count the number of documents for which the facet.query condition is true.


Any number of [:SimpleFacetParameters#facet.field:facet.field] parameters can be passed to the request handler. For each facet.field, one of two approaches will be used based on the Field definiton in schema.xml:

Note that at this time there is no way to manually control whether facet.field is handled via field queries or field cache, other than defining in the schema whether the field is single- or multi-valued and the analyzer used: solr.TextField is always tokenized while solr.StrField is never tokenized. Control may be improved in the future, along with a means to handle multi-valued fields with a variant of the Field Cache mechanism.