Introduction

According to Peter Morville faceted search "leverages metadata fields and values to provide users with visible options for narrowing or refining their query." Faceting is currently only supported in the Solr engine but this interface will be the same for other engines as they're implemented.

Indexing

Although the only supported engine at the moment is Solr and solr has to be configured seperately there is a method for marking a field as a facet at index time and it should be done for the sake of portability. In egines which support it, setting a field to facet will prevent the field from being tokenized or analyzed, it will be indexed 'as-is'.

$document = new ForageDocument();
$document->add('my_facet', 'the value', array('facet'=>true));

In The Query Object

In order to facet on a particular field you have to set it as a facet. This is done with setFacetFields method. Any fields which have been added as facet fields can be filtered on with the addFacetFilter method. See the example below.

$query->setFacetFields(array('category'));
$query->addFacetFilter('category', 'Cars');

In The Response Object

When searching with a faceted query you can access these facets as ForageFacet objects with getFacets or getFacet. A ForageFacet object is made up of ForageFacetValue objects, each of which has the value string, it's count and a flag to say if it's being filtered on.

$facet = $response->getFacet('category');
foreach ($facet->values as $value) {
  echo $value->value;
  if ($value->filter) {
    echo '*';
  }
  echo ' (' . $value->count . ")\n";
}