Configure Human-Readable Facet Value Ranges

Overview

You can configure dynamic, human-readable facet value ranges in a faceted navigation tree. This approach helps reduce the number of individual facet values and improves navigation by grouping values into ranges such as "this week" or "under $100".

When to Use

Use human-readable facet value ranges when a document property used as a facet produces too many values, making navigation difficult. Ranges allow you to present grouped, meaningful options to users.

Facet value ranges are dynamic in two ways:

You can define different ranges for the same property across multiple faceted navigations, or add the same property multiple times with different range definitions.
For date properties, range definitions shift over time. For example, the range for "today" always represents the current day.

Configuration

You can configure ranges for properties of type Date, Double, Long, or String. Ranges are defined using a JSON array format, appended to the property name with a $ delimiter.

Example configuration:

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

Range Attributes

For Date, Double, and Long properties, use the following attributes:

name (required, String): The label for the range.
resolution (required, String): One of 'long', 'double', 'year', 'month', 'week', 'day', or 'hour'.
begin (optional, double): Inclusive lower bound. Defaults to Double.NEGATIVE_INFINITY.
end (optional, double): Exclusive upper bound. Defaults to Double.POSITIVE_INFINITY.

For String properties, use these attributes:

name (required, String): The label for the range.
resolution (required, String): Must be 'string'.
lower (optional, string): Inclusive lower bound.
upper (optional, string): Exclusive upper bound.

If lower is not defined, all facet values before upper are included. If upper is not defined, all values after lower are included. If both are omitted, all values are included.

Limitation: When both lower and upper are set, their values must have the same number of characters. For example, 'aa' to 'ab' is valid, but 'aa' to 'b' is not and will cause an exception.

Performance Note: String ranges are limited to a maximum of 3 characters. For example, you can define a range from 'a' to 'b', 'aa' to 'ab', or 'aaa' to 'aab', but not from 'aaaa' to 'aaab'.

Examples

Date Ranges

To configure date facet value ranges for the property myproject:date such as today, yesterday, this week, this month, this year, and before this year:

/content/documents/myproject:
  /faceted-news:
    jcr:primaryType: hippofacnav:facetnavigation
    hippo:docbase: d2b1775c-fb97-4080-bd66-ede4ac874b5a
    hippofacnav:facets: [ "myproject: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 ]

This configuration produces a faceted tree like the following:

/content/documents/myproject:
  /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

For product documents with prices stored as Double in the property myproject:price, you can define price ranges such as under $100, between $100 and $500, and over $500:

/content/documents/myproject:
  /faceted-products:
    jcr:primaryType: hippofacnav:facetnavigation
    hippo:docbase: d2b1775c-fb97-4080-bd66-ede4ac874b5a
    hippofacnav:facets: [ "myproject: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 ]

This produces a faceted tree similar to:

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

String Ranges

To group product brands into three alphabetical groups and an "all" group using the property myproject:brand:

/content/documents/myproject:
  /faceted-products:
    jcr:primaryType: hippofacnav:facetnavigation
    hippo:docbase: d2b1775c-fb97-4080-bd66-ede4ac874b5a
    hippofacnav:facets: [ "myproject: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 ]

Note: The character '{' follows 'z' in Unicode order, so it is used as the upper bound for the last range.

This configuration results in a faceted tree like:

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

Verification

After configuring facet value ranges, verify that the faceted navigation tree displays the expected range labels and document counts under each range.