Configure Human-Readable Facet Value Ranges

Introduction

Goal

Configure human-readable dynamic facet value ranges in a faceted tree.

Background

Using document property values as facets in a faceted navigation can result in a high number of facet values. To make a facet easier to navigate, it is possible to configure human-readable dynamic value ranges such as "this week" or "under $100".

Ranges are dynamic in two ways:

1. You can have multiple faceted navigations, with different ranges, you can have one and the same property added multiple times with different ranges, etc.

2. When configuring ranges for dates, the 'ranges' themselve shift in time. For example, a range for 'today' has been shifted to another date range tomorrow.

Configuration

Ranges can be configured for Date, Double, Long, and String values using JSON array format after a delimiter '$'. For example:

myhippoproject:date$[{name:'today', resolution:'day', begin:0, end:1},
{name:'yesterday', resolution:'day', begin:-1, end:0}]

The range configuration for Date, Double, and Long values are equivalent:

Supported attributes:

• name (mandatory; type: String)

• resolution (mandatory; type: String, options: ' long', ' double', ' year', ' month', ' week', ' day', ' hour')

• begin (optional; type: double, inclusive, default Double.NEGATIVE_INFINITY)

• end (optional; type: double, exclusive, default Double.POSITIVE_INFINITY)

The range query for String values:
A String range query is very useful for creating for example an index page, where for each range and index word you want to display the number of documents. String range configuration is similar to the range configuration for Longs, Doubles and Dates with a small difference:

Supported attributes:

• name (mandatory ; type: String)

• resolution (mandatory ; type: String, options: 'string')

• lower (optional ; type: string, inclusive)

• upper (optional ; type: string, exclusive)

When no lower is defined, all facet values before upper are counted. When no upper is defined, all facet values after lower are counted. If both are missing, all values are counted.

Limitation: If you use a lower and an upper bound, the configured ranges must have an equal number of chars. Thus 'aa' to 'ab' is correct, 'aa' to 'b' is not supported and will throw an exception.

We support ranges for String values with the limitation that you can only have a range of at most 3 chars. So you can for example define a String range from 'a' to 'b', or from 'aa' to 'ab' or 'aaa' to 'aab', but not from 'aaaa' to 'aaab'. This is for performance reasons, and also unlikely that it is needed as a range.

Examples

Date Ranges

Suppose you want to configure the following date facet value ranges for the property myhippoproject:date:

• today

• yesterday

• this week

• this month

• this year

• before this year

This can be configured as follows:

/content/documents/myhippoproject:
  /faceted-news:
    jcr:primaryType: hippofacnav:facetnavigation
    hippo:docbase: d2b1775c-fb97-4080-bd66-ede4ac874b5a
    hippofacnav:facets: [ "myhippoproject:date$[\
      \ {name:'today', resolution:'day', begin:0, end:1},\
      \ {name:'yesterday', resolution:'day', begin:-1, end:0},\
      \ {name:'this week', resolution:'week', begin:0, end:1},\
      \ {name:'this month', resolution:'month', begin:0, end:1},\
      \ {name:'this year', resolution:'year', begin:0, end:1},\
      \ {name:'before this year', resolution:'year', end:0}]" ]
    hippofacnav:facetnodenames: [ Date ]

The result is a faceted tree as in the example below:

/content/documents/myhippoproject:
  /faceted-news [30]:
    /Date [27]:
      /today [1]:
      /yesterday [1]:
      /this week [2]:
      /this month [3]:
      /this year [6]:
      /before this year [21]:
      /hippo:resultset [27]:
    /hippo:resultset [30]:

Price Ranges

Suppose you have product documents with prices stored as Double in the property myhippoproject:price. Now, you'd like to show prices under $100, between $100 and $500, and over $500. This can be configured as follows:

/content/documents/myhippoproject:
  /faceted-products:
    jcr:primaryType: hippofacnav:facetnavigation
    hippo:docbase: d2b1775c-fb97-4080-bd66-ede4ac874b5a
    hippofacnav:facets: [ "myhippoproject:price$[\
      \ {name:'under $100', resolution:'double', end:100},\
      \ {name:'$100 $500', resolution:'double', begin:100, end:500},\
      \ {name:'over $500', resolution:'double', begin:500}]" ]
    hippofacnav:facetnodenames: [ Price ]

The result is a faceted tree as in the example below:

/content/documents/myhippoproject:
  /faceted-products [30]:
    /Price [27]:
      /under $100 [3]:
      /$100 - $500 [18]:
      /over $500 [5]:
      /hippo:resultset [27]:
    /hippo:resultset [30]:

String Ranges

Suppose you have product documents with a property myhippoproject:brand and want to create an index page for all brands, grouped together in 3 groups, and one extra group for 'all'. This can be configured as follows:

/content/documents/myhippoproject:
  /faceted-products:
    jcr:primaryType: hippofacnav:facetnavigation
    hippo:docbase: d2b1775c-fb97-4080-bd66-ede4ac874b5a
    hippofacnav:facets: [ "myhippoproject:brand$[\
     \ {name:'all', resolution:'string'},\
     \ {name:'a f', resolution:'string', lower:'a', upper:'g'},\
     \ {name:'g m', resolution:'string', lower:'g', upper:'n'},\
     \ {name:'n z', resolution:'string', lower:'n', upper:'{'}]" ]
    hippofacnav:facetnodenames: [ Brand ]

The result is a faceted tree as in the example below:

/content/documents/myhippoproject:
  /faceted-products [30]:
    /Brand [27]:
      /all [27]:
      /a - f [3]:
      /g - m [18]:
      /n - z [5]:
      /hippo:resultset [27]:
    /hippo:resultset [30]: