SimpleFacetParameters

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.

For More information on General Issues involved with Faceted searchs in Solr, please read the SolrFacetingOverview.

Parameters
Deprecated Parameters
1. facet.zeros
Examples
Warming

Parameters

These are the parameters used to drive the Simple Faceting behavior, grouped based on the type of faceting they support.

Note that many parameters may be overridden on a per-field basis with the following syntax:

f.<fieldName>.<originalParam>=<value>

eg. f.category.facet.limit=5

facet

Set to "true" this param enables facet counts in the query response. Any blank or missing value, or "false" will disable faceting. None of the other parameters listed below will have any effect without setting this param to "true"

The default value is blank.

Arbitrary Query Faceting: facet.query

This param allows you to specify an arbitrary query in the Lucene default syntax to generate a facet count. It can be particularly useful for numeric range based facets, or prefix based facets.

This parameter can be specified multiple times to indicate that multiple queries should be used as separate facet constraints.

Field Value Faceting Parameters

Several params can be used to trigger faceting based on the indexed Terms of a field.

When using this param, it is important to remember that "Term" is a very specific concept in Lucene -- it relates to the literal field/value pairs that are Indexed after any Analysis occurs. For text fields that include stemming, or lowercasing, or word splitting you may not get what you expect. If you want both Analysis (for searching) and Faceting on the full literal Strings, use copyField to create two versions of the field: one Text and one String. Make sure both are indexed="true"

facet.field

This param allows you to specify a field which should be treated as a facet. It will iterate over each Term in the field and generate a facet count using that Term as the constraint.

This parameter can be specified multiple times to indicate multiple facet fields.

None of the other params in this section will have any effect without specifying at least one field name using this param.

facet.prefix

Limits the terms on which to facet to those starting with the given string prefix.

This parameter can be specified on a per field basis.

Solr1.2

facet.sort

Set to "true", this parameter indicates that constraints should be sorted by their count. If "false", facets will be in their natural index order (unicode). For terms in the ascii range, this will be alphabetically sorted. The default is true if facet.limit is greater than 0, false otherwise.

This parameter can be specified on a per field basis.

facet.limit

This param indicates the maximum number of constraint counts that should be returned for the facet fields. A negative value means unlimited.

The default value is 100.

This parameter can be specified on a per field basis to indicate a separate limit for certain fields.

facet.offset

This param indicates an offset into the list of constraints to allow paging.

The default value is 0.

This parameter can be specified on a per field basis.

Solr1.2

facet.mincount

This param indicates the minimum counts for facet fields should be included in the response.

The default value is 0.

This parameter can be specified on a per field basis.

Solr1.2

facet.missing

Set to "true" this param indicates that in addition to the Term based constraints of a facet field, a count of all matching results which have no value for the field should be computed

The default value is blank.

This parameter can be specified on a per field basis.

facet.enum.cache.minDf

This param indicates the minimum document frequency (number of documents matching a term) for which the filterCache should be used when determining the constraint count for that term. This is only used during the term enumeration method of faceting (facet.field type faceting on multi-valued or full-text fields).

A value greater than zero will decrease memory usage of the filterCache, but increase the query time. When faceting on a field with a very large number of terms, and you wish to decrease memory usage, try a low value of 25 to 50 first.

The default value is 0, causing the filterCache to be used for all terms in the field.

This parameter can be specified on a per field basis.

Solr1.2

Date Faceting Parameters

Several params can be used to trigger faceting based on Date ranges computed using simple DateMathParser expressions.

When using Date Faceting, the facet.date, facet.date.start, facet.date.end, and facet.date.gap params are all mandatory...

Solr1.3

facet.date

This param allows you to specify names of fields (of type DateField) which should be treated as date facets.

This parameter can be specified multiple times to indicate multiple date facet fields.

facet.date.start

The lower bound for the first date range for all Date Faceting on this field. This should be a single date expression which may use the DateMathParser syntax.

This parameter can be specified on a per field basis.

facet.date.end

The minimum upper bound for the last date range for all Date Faceting on this field (see facet.date.hardend for an explanation of what the actual end value may be greater). This should be a single date expression which may use the DateMathParser syntax.

This parameter can be specified on a per field basis.

facet.date.gap

The size of each date range expressed as an interval to be added to the lower bound using the DateMathParser syntax.

Example: facet.date.gap=%2B1DAY (+1DAY)

This parameter can be specified on a per field basis.

facet.date.hardend

A Boolean parameter instructing Solr what do do in the event that facet.date.gap does not divide evenly between facet.date.start and facet.date.end. If this is true, the last date range constraint will have an upper bound of facet.date.end; if false, the last date range will have the smallest possible upper bound greater then facet.date.end such that the range is exactly facet.date.gap wide.

The default is false.

This parameter can be specified on a per field basis.

facet.date.other

This param indicates that in addition to the counts for each date range constraint between facet.date.start and facet.date.end, counts should also be computed for...

before all records with field values lower then lower bound of the first range
after all records with field values greater then the upper bound of the last range
between all records with field values between the start and end bounds of all ranges
none compute none of this information
all shortcut for before, between, and after

This parameter can be specified on a per field basis.

In addition to the all option, this parameter can be specified multiple times to indicate multiple choices -- but none will override all other options.

Deprecated Parameters

facet.zeros

Set to "true" this param indicates that constraint counts for facet fields should be included even if the count is "0", set to "false" or blank and the "0" counts will be suppressed to save on the amount of data returned in the response.

The default value is "true".

This parameter can be specified on a per field basis.

Use facet.mincount instead.

Examples

Note: In many of these examples "rows" is set to 0 so that the main result set is empty, to better emphasize the facet data.

Facet Fields

http://localhost:8983/solr/select?q=ipod&rows=0&facet=true&facet.limit=-1&facet.field=cat&facet.field=inStock

<response>
<responseHeader><status>0</status><QTime>2</QTime></responseHeader>
<result numFound="4" start="0"/>
<lst name="facet_counts">
 <lst name="facet_queries"/>
 <lst name="facet_fields">
  <lst name="cat">
        <int name="search">0</int>
        <int name="memory">0</int>
        <int name="graphics">0</int>
        <int name="card">0</int>
        <int name="music">1</int>
        <int name="software">0</int>
        <int name="electronics">3</int>
        <int name="copier">0</int>
        <int name="multifunction">0</int>
        <int name="camera">0</int>
        <int name="connector">2</int>
        <int name="hard">0</int>
        <int name="scanner">0</int>
        <int name="monitor">0</int>
        <int name="drive">0</int>
        <int name="printer">0</int>
  </lst>
  <lst name="inStock">
        <int name="false">3</int>
        <int name="true">1</int>
  </lst>
 </lst>
</lst>
</response>

Facet Fields with No Zeros

http://localhost:8983/solr/select?q=ipod&rows=0&facet=true&facet.limit=-1&facet.field=cat&facet.mincount=1&facet.field=inStock

<response>
<responseHeader><status>0</status><QTime>3</QTime></responseHeader>
<result numFound="4" start="0"/>
<lst name="facet_counts">
 <lst name="facet_queries"/>
 <lst name="facet_fields">
  <lst name="cat">
        <int name="music">1</int>
        <int name="connector">2</int>
        <int name="electronics">3</int>
  </lst>
  <lst name="inStock">
        <int name="false">3</int>
        <int name="true">1</int>
  </lst>
 </lst>
</lst>
</response>

Facet Fields with No Zeros And Missing Count For One Field

http://localhost:8983/solr/select?q=ipod&rows=0&facet=true&facet.limit=-1&facet.field=cat&f.cat.facet.missing=true&facet.mincount=1&facet.field=inStock

<response>
<responseHeader><status>0</status><QTime>3</QTime></responseHeader>
<result numFound="4" start="0"/>
<lst name="facet_counts">
 <lst name="facet_queries"/>
 <lst name="facet_fields">
  <lst name="cat">
        <int name="music">1</int>
        <int name="connector">2</int>
        <int name="electronics">3</int>
        <int>1</int>
  </lst>
  <lst name="inStock">
        <int name="false">3</int>
        <int name="true">1</int>
  </lst>
 </lst>
</lst>
</response>

Facet Field with Limit

http://localhost:8983/solr/select?rows=0&q=inStock:true&facet=true&facet.field=cat&facet.limit=5

<response>
<responseHeader><status>0</status><QTime>4</QTime></responseHeader>
<result numFound="12" start="0"/>
<lst name="facet_counts">
 <lst name="facet_queries"/>
 <lst name="facet_fields">
  <lst name="cat">
        <int name="electronics">10</int>
        <int name="memory">3</int>
        <int name="drive">2</int>
        <int name="hard">2</int>
        <int name="monitor">2</int>
  </lst>
 </lst>
</lst>
</response>

Facet Fields and Facet Queries

http://localhost:8983/solr/select?q=video&rows=0&facet=true&facet.field=inStock&facet.query=price:[*+TO+500]&facet.query=price:[500+TO+*]

<response>
<responseHeader><status>0</status><QTime>11</QTime></responseHeader>
<result numFound="3" start="0"/>
<lst name="facet_counts">
 <lst name="facet_queries">
  <int name="price:[* TO 500]">2</int>
  <int name="price:[500 TO *]">1</int>
 </lst>
 <lst name="facet_fields">
  <lst name="inStock">
        <int name="false">2</int>
        <int name="true">1</int>
  </lst>
 </lst>
</lst>
</response>

Facet prefix (term suggest)

http://localhost:8983/solr/select?q=hatcher&wt=ruby&indent=on&facet=on&rows=0&facet.field=text&facet.prefix=xx&facet.limit=5&facet.mincount=1

{
'responseHeader'=>{
  'status'=>0,
  'QTime'=>88,
  'params'=>{
        'facet.limit'=>'5',
        'wt'=>'ruby',
        'rows'=>'0',
        'facet'=>'on',
        'facet.mincount'=>'1',
        'facet.field'=>'text',
        'indent'=>'on',
        'facet.prefix'=>'xx',
        'q'=>'hatcher'}},
'response'=>{'numFound'=>90,'start'=>0,'docs'=>[]
},
'facet_counts'=>{
  'facet_queries'=>{},
  'facet_fields'=>{
        'text'=>[
         'xx',7,
         'xxxviii',2,
         'xx909337',1,
         'xxvi',1] } } }

Date Faceting: per day for the past 5 days

Solr1.3

http://localhost:8983/solr/select/?q=*:*&rows=0&facet=true&facet.date=timestamp&facet.date.start=NOW/DAY-5DAYS&facet.date.end=NOW/DAY%2B1DAY&facet.date.gap=%2B1DAY

<response>
<lst name="responseHeader">
 <int name="status">0</int>
 <int name="QTime">5</int>
 <lst name="params">
  <str name="facet.date">timestamp</str>
  <str name="facet.date.end">NOW/DAY+1DAY</str>
  <str name="facet.date.gap">+1DAY</str>
  <str name="rows">0</str>
  <str name="facet">true</str>
  <str name="facet.date.start">NOW/DAY-5DAYS</str>
  <str name="indent">true</str>
  <str name="q">*:*</str>
 </lst>
</lst>
<result name="response" numFound="42" start="0"/>
<lst name="facet_counts">
 <lst name="facet_queries"/>
 <lst name="facet_fields"/>
 <lst name="facet_dates">
  <lst name="timestamp">
        <int name="2007-08-11T00:00:00.000Z">1</int>
        <int name="2007-08-12T00:00:00.000Z">5</int>
        <int name="2007-08-13T00:00:00.000Z">3</int>
        <int name="2007-08-14T00:00:00.000Z">7</int>
        <int name="2007-08-15T00:00:00.000Z">2</int>
        <int name="2007-08-16T00:00:00.000Z">16</int>
        <str name="gap">+1DAY</str>
        <date name="end">2007-08-17T00:00:00Z</date>
  </lst>
 </lst>
</lst>
</response>

Warming

facet.field queries using the term enumeration method can avoid the evaluation of some terms for greater efficiency. To force the evaluation of all terms for warming, the base query should match a single document.