What are facets and facet filtering?

You can use faceted search to narrow your search results. Faceted search is described here.

Using facets and facet filtering with the REST API v2 Search endpoint

The Telligent Evolution web services v2 Search endpoint supports faceting and facet filters.

Field facets: You add field facets to your query by using the fieldfacets querystring parameter. Multiple field facets can be added by separating each one with a double pipe delimiter ("||"). The following parameters are supported and are separated by commas:

  • Field Name
  • Sort
  • Page Count
  • Page Index
  • Minimum Document Count
  • Filters to Ignore

 Field Name is the search index field to build the facets on, for example "type", "user", etc. Valid Sort values are "alpha" and "count". Filters to Ignore are defined as comma-separated ID values preceded by an exclamation point (bang !), for example: "!0" or "!0,1,2". The IDs used in the Filters to Ignore parameter are those you assign to each filter you use, using a zero-based index. An example field facets parameter may look like: fieldfacets=type,alpha,10,0,2!0,1. Only the Field Name field is required, and when using just the Field Name your parameter may look like: fieldfacets=type. Additionally, any optional parameters can be left empty, for example: fieldfacets=type,,,,!0,1.

Date range facets: You add date range facets to your query using the daterangefacets querystring parameter. Multiple date range facets can be added by separating each one with a double pipe delimiter ("||"). The following parameters are supported and are separated by commas:

  • Field Name
  • Start Date
  • End Date
  • Inclusive
  • Filters to Ignore

Field Name is the search index field to build the facets on, for example include "date", "modifieddate", etc. You must set one of the dates, either Start Date or End Date, or you can provide values for both. Inclusive is a Boolean field (true/false) and specifies whether to filter the dates inclusive of the supplied Start Date and End Date or exclusive. Filters to Ignore are defined as comma-separated ID values preceded by an exclamation point (bang !), for example: "!0" or "!0,1,2". The IDs used in the Filters to Ignore parameter are the ones you assign to each filter that you use, using a zero-based index. An example date range facet parameter may look like: daterangefacets=date,2010-01-01T00:00:00,2010-12-31-T23:59:59,true,!0,1. The Field Name and Start or End Date are required. When only specifying a Field Name and a Start Date, your parameter may look like: daterangefacets=date,2010-01-01T00:00:00. Additionally, any optional parameter can be left empty: daterangefacets=date,2010-01-01T00:00:00,,!0,1.

Field facet filters: You add field facet filters to your query using the fieldfacetfilters querystring parameter. Multiple field facet filters can be added by separating each one with a double pipe delimiter ("||"). The following parameters are supported and are separated by commas:

  • Id
  • Field Name
  • Value

Id is an integer value that you set for each filter that is unique among all filters (both field facet filters and date range facet filters). It uses a zero-based index and is ultimately used to identify each filter for assigning to the Filters To Ignore for facets. Field Name is the search index field to build the filter on, for example: "type", "user", etc. Value is value for a search index field that you want to filter, for example: "blogapp", "2100", etc. An example field facet filter may look something like: fieldfacetfilters=0,type,wikiapp. All three fields are required and must be included. 

Date range facet filters: You add date range facet filters to your query using the daterangefacetfilters querystring parameter. Multiple date range facet filters can be added by separating each one with a double pipe delimiter ("||"). The following parameters are supported and are separated by commas:

  • Id
  • Field Name
  • Start Date
  • End Date
  • Inclusive

Id is an integer value that you set for each filter that is unique among all filters (both field facet filtes and date range facet filters). It uses a zero-based index and is ultimately used to identify each filter for assigning to the Filters To Ignore for facets. Field Name is the search index field to build the filter on, for example: "date", "lastmodifieddate", etc. You must set one of the dates, either Start Date or End Date, or you can provide values for both. Inclusive is a Boolean field (true/false) and specifies whether to filter the dates inclusive of the supplied Start Date and End Date or exclusive. The Id, Field Name and Start or End Date are required. When only specifying an Id, Field Name and a Start Date, your parameter may look like: daterangefacetfilters=0,date,2010-01-01T00:00:00. Additionally, any optional parameter can be left empty: daterangefacetfilters=0,date,2010-01-01T00:00:00,,false.

Example search query:

/api.ashx/v2/search.xml?query=sample&filters=type::blog||groupid::4 
    &fieldfacets=type,alpha,10,0,2!0,1||user,count,10,0,3!0
    &daterangefacets=date,2000-01-01T00:00:00,2010-12-31T11:59:59,true!2,3
        ||date,2011-01-01T00:00:00,2011-01-20T11:59:599,false!3
    &fieldfacetfilters=0,user,2100||1,group,45
    &daterangefacetfilters=2,date,2000-01-01T00:00:00,2010-12-31T11:59:59,true
        ||3,date,2011-01-01T00:00:00,2011-01-20T11:59:59,false

Format notes:

  • Separate multiple items with "||".
  • Null/empty entries are valid for optional values. Examples – both of the below would be valid:
    • &fieldfacets=type,,,,!1,2
    • &fieldfacets=type
  • Formats:
    • FieldFacets format = FieldName,Sort,PageSize,PageIndex,MinCount!ids of filters to ignore – FieldName is only required value; all others optional/
    • DateRangeFacets format = FieldName,Start,End,Inclusive!ids of filters to ignore – FieldName is required. Either Start or End is required. All others optional.
    • FieldFacetFilters format = Id,FieldName,FieldValue – Id is required and is only used for identifying which filters to assign to a facet’s FiltersToIgnore property. All values are required.
    • DateRangeFacetFilters format = Id,Start,End,Inclusive – Id is required and is only used for identifying which filters to assign to a facet’s FiltersToIgnore property. Either Start or End is required.

Example result:

<SearchResults PageSize="20" PageIndex="0" TotalCount="5">
  <FieldFacets>
    <FieldFacetResult>
      <FieldName>type</FieldName>
      <FieldValue>group</FieldValue>
      <DocumentCount>3</DocumentCount>
    </FieldFacetResult>
    <FieldFacetResult>
      <FieldName>type</FieldName>
      <FieldValue>forumapp</FieldValue>
      <DocumentCount>2</DocumentCount>
    </FieldFacetResult>
  </FieldFacets>
  <SearchResult>
    ...
  </SearchResult>
  ...
</SearchResults>