<img src="https://secure.leadforensics.com/84962.png" style="display:none;">

Faceting

Before returning results, the engine can count the unique occurrences of certain product attributes and return this data along with the results. The engine can also be configured so that a client can filter the results based on attributes before the engine returns them. This can be used to present the user with, for instance, a list of categories that products in the result belong to, so that the user can choose which results to see, we call this facets.

Faceting is used to filter the search results and to give the user a sense of in what part of the store they ended up with their query. The facets can be put either at the side or on top of the results.

Best practice

You need to decide which attributes that are to be used as facets. In the example we've used Manufacturer and Category, two common ones along with price. You should not use too many types of facets, as it will only confuse the user. Depending on the store, 2-3 is usually sufficient. Under each faceting type we recommend showing five options along with a button saying "show all" (if there are more). The facets come sorted from us in a list with a number attached to each entity. Those numbers represent the amount of products that fit the facet. That number should also be displayed to the user. See example below.

cont-img.jpg
Code examples
SHOW INSTRUCTIONS FOR: PHP JSON JAVA .NET
Example 1:
Search with a single facet
if(isset($_GET{"categories"}))
    $request->setValue("Faceting.Category",explode(",",$_GET{"categories"}));
Example 2:
Search with multiple facets
if(isset($_GET{"categories"}))
    $request->setValue("Faceting.Category",explode(",",$_GET{"categories"}));
if(isset($_GET{"manufacturers"}))
    $request->setValue("Faceting.Manufacturer",explode(",",$_GET{"manufacturers"}));
Engine response

The engine will always respond with lists of available facets - these can be used to display the faceting links to the visitor. The names of the lists will be the same as the attribute from where the data is taken. In this case the data is taken from the attributes "Category" and "Manufacturer". The value of each key is the number of times the facet is represented in the search results.


//if there are faceting categories 
if($response->hasData("Category"))
{
    $facetItems = $response->getCollection("Category");

    if(count($facetItems)>0)
        echo "Categories: ";

    foreach($facetItems as $item)
        echo $item->key . ": " . $item->value . " "; //key is the facet name, value is the number of products in the facet
}

//if there are faceting manufacturers 
if($response->hasData("Manufacturer"))
{
    $facetItems = $response->getCollection("Manufacturer");

    if(count($facetItems)>0)
        echo "Brands: ";

    foreach($facetItems as $item)
        echo $item->key . ": " . $item->value . " "; //key is the facet name, value is the number of products in the facet
}

The naming convention for the faceting list on the request is "Faceting." + [name_of_attribute]. In the following code example it will be "Faceting.Category" since we want to facet on the attribute called "Category".

Example 1:
Search with a single facet
POST to helloworld.54proxy.com/search
{
    "UserId" : "helloworlduser",
    "IP" : "127.0.0.1",

    "QueryString" : "fruit",
    "DirectResults_FromIndex" : 0,
    "DirectResults_ToIndex" : 9,
    "RecommendedResults_FromIndex" : 0,
    "RecommendedResults_ToIndex" : 9,

    "Faceting.Category" : ["Fruits"]
}
Example 4:
Search with multiple facets
POST to helloworld.54proxy.com/search
{
    "UserId" : "helloworlduser",
    "IP" : "127.0.0.1",

    "QueryString" : "fruit",
    "DirectResults_FromIndex" : 0,
    "DirectResults_ToIndex" : 9,
    "RecommendedResults_FromIndex" : 0,
    "RecommendedResults_ToIndex" : 9,

    "Faceting.Category" : ["Fruits"],
    "Faceting.Manufacturer" : ["The banana company", "Fruits n Veggies"]
}
Engine response

The engine will always respond with lists of available facets - these can be used to display the faceting links to the visitor. The names of the lists will be the same as the attribute from where the data is taken. In this case the data is taken from the attributes "Category" and "Manufacturer". The value of each key is the number of times the facet is represented in the search results.

Response: 200 OK
{
  "Success": true,
  "HeroId": "The Warrior of the Dull Cupboard",
  "Data": {
    "MakesSense": true,
    "DirectResults_TotalItems": 3,
    "RecommendedResults_TotalItems": 0,
    "RelatedQueries": [],
    "DirectResults": [...],
    "RecommendedResults": [],
    "Category": [
      {
        "Key": "Fruits",
        "Value": 3
      },
      {
        "Key": "Fruit",
        "Value": 1
      }
    ],
    "Manufacturer": [
      {
        "Key": "Fruits n Veggies",
        "Value": 2
      },
      {
        "Key": "The banana company",
        "Value": 1
      }
    ]
  }
}

    

The naming convention for the faceting list on the request is "Faceting." + [name_of_attribute]. In the following code example it will be "Faceting.Category" since we want to facet on the attribute called "Category".

Example 1:
Search with a single facet
if(request.getParameterValues("categories")!=null) loopRequest.setValue("Faceting.Category",request.getParameterValues("categories"));
Example 6:
Search with multiple facets
if(request.getParameterValues("categories")!=null)
    loopRequest.setValue("Faceting.Category",request.getParameterValues("categories"));
if(request.getParameterValues("manufacturers")!=null)
    loopRequest.setValue("Faceting.Manufacturer",request.getParameterValues("manufacturers"));
Engine response

The engine will always respond with lists of available facets - these can be used to display the faceting links to the visitor. The names of the lists will be the same as the attribute from where the data is taken. In this case the data is taken from the attributes "Category" and "Manufacturer". The value of each key is the number of times the facet is represented in the search results.

//if there are faceting categories
if(loopResponse.hasData("Categories"))
{
    List facetItems = loopResponse.getItemArray("Categories");

    if(!facetItems.isEmpty())
        response.getWriter().print("Categories: ");

    for(Item facetItem: facetItems)
        response.getWriter().print(facetItem.key + ": " + facetItem.value); //String is the facet name, Value is the number of products in the facet
}
//if there are faceting manufacturers
if(loopResponse.hasData("Manufacturer"))
{
    List facetItems = loopResponse.getItemArray("Manufacturer");

    if(!facetItems.isEmpty())
        response.getWriter().print("Brands: ");

    for(Item facetItem: facetItems)
        response.getWriter().print(facetItem.key + ": " + facetItem.value); //String is the facet name, Value is the number of products in the facet
}

The naming convention for the faceting list on the request is "Faceting." + [name_of_attribute]. In the following code example it will be "Faceting.Category" since we want to facet on the attribute called "Category".

Example 1:
Search with a single facet
if(!string.IsNullOrWhiteSpace(Request.QueryString["categories"]))
    request.SetValue("Faceting.Category", Request.QueryString["categories"].Split(','));
Example 2:
Search with multiple facets
if(!string.IsNullOrWhiteSpace(Request.QueryString["categories"]))
    request.SetValue("Faceting.Category", Request.QueryString["categories"].Split(','));
if (!string.IsNullOrWhiteSpace(Request.QueryString["manufacturers"]))
    request.SetValue("Faceting.Manufacturer", Request.QueryString["manufacturers"].Split(','));
Engine response

The engine will always respond with lists of available facets - these can be used to display the faceting links to the visitor. The names of the lists will be the same as the attribute from where the data is taken. In this case the data is taken from the attributes "Category" and "Manufacturer". The value of each key is the number of times the facet is represented in the search results.

//if there are faceting categories
if (response.HasData("Category"))
{
    var facetItems = response.GetValue<list<item>>("Category");

    if(facetItems.Any())
        Response.Write("Categories: ");

    foreach (var facetItem in facetItems)
        Response.Write(facetItem.Key + ": " + facetItem.Value + Environment.NewLine); //Key is the facet name, Value is the number of products in the facet
}
//if there are faceting manufacturers
if (response.HasData("Manufacturer"))
{
    var facetItems = response.GetValue<list<item>>("Manufacturer");

    if (facetItems.Any())
        Response.Write("Brands: ");

    foreach (var facetItem in facetItems)
        Response.Write(facetItem.Key + ": " + facetItem.Value + Environment.NewLine); //Key is the facet name, Value is the number of products in the facet
}