HomeDev GuideAPI Reference
Dev GuideAPI ReferenceUser GuideGitHubNuGetDev CommunitySubmit a ticketLog In
GitHubNuGetDev CommunitySubmit a ticket

Terms facets

Describes how facets based on terms are used in Optimizely Search & Navigation.

Facets group documents based on criteria, such as specific terms or a date range.

Term facets are group terms, words, or whole strings, and Optimizely Search & Navigation provides a count for each. To retrieve a term facet using the fluent API, use the TermsFacetFor and TermsFacetForWordsIn methods.

  • The TermsFacetFor method works on exact values in strings in a case-sensitive manner. So, Optimizely Search & Navigation treats Foo, foo, and foo bar as three different terms.
  • The TermsFacetForWordsIn method works on analyzed values of strings in a case-insensitive manner. So, it treats each word in a string as a separate term. This method treats Foo, foo, and foo bar as two terms, foo and bar.

Each method works on values of type string and IEnumerable of string. Also, each has an overload that lets you specify the number of terms to return. Unless specified, 10 is the default number of items returned for a facet. To return more items, use x.Size as in the example below.

  .TermsFacetFor(x => x.CountiesList, x => x.Size = 20)

Before providing examples, you need to provide context. Assume there is a class with a string property, a list of strings property, and a property of a complex type that also has a string property.

public class Book {
  public string Title {
  public string Author {
  public List < string > Tags {

public class Author {
  public string Name {

Assume you indexed three instances of this class with the following values:

Ten Little Indianscrime, fictionAgatha Christie
The Origin of SpeciesscienceCharles Darwin
David Copperfieldscifi, fictionCharles Dickens

Retrieve a tag cloud

Use the TermsFacetFor method to retrieve a list of the most common tags in a search request.

var searchResults = client.Search<Book>()
  .TermsFacetFor(x => x.Tags)



Use the Take method to exclude actual search results, since you are not interested in them in this scenario.

After getting the search results, you can extract the tag terms facet.

var tagCounts = searchResults
  .TermsFacetFor(x => x.Tags).Terms;
foreach(var tagCount in tagCounts) {
  string tag = tagCount.Term;
  int count = tagCount.Count;
  Console.WriteLine(tag + ": " + count);

The above code prints:
fiction: 2
crime: 1
science: 1
scifi: 1

Group authors

If you modify the code to retrieve a terms facet for the author name instead, the code will look like this.

var searchResults = client.Search < Book > ()
  .TermsFacetFor(x => x.Author.Name)

var authorCounts = searchResults
  .TermsFacetFor(x => x.Author.Name).Terms;
foreach(var authorCount in authorCounts) {
  string authorName = authorCount.Term;
  int count = authorCount.Count;
  Console.WriteLine(authorName + ": " + count);

The above code prints:
Agatha Christie: 1
Charles Darwin: 1
Charles Dickens: 1

Group by single words

In contrast, if you used the TermsFacetForWordsIn method (instead of the TermsFacetFor method) in the above code, it prints:
charles: 2
agatha: 1
christie: 1
darwin: 1
dickens: 1