Last updated: Nov 16 2015

Term facets group terms, words, or whole strings, and provide 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, "Foo", "foo," and "foo bar" are treated 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 a separate term. With this method "Foo", "foo," and "foo bar" are treated as two terms, "foo" and "bar".

Both methods work on values of type string and IEnumerable of string. Also, both have an overload that lets you specify the number of terms to return. If no size is specified, the service defaults to ten.


Before providing examples, we need to provide a 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 { get; set; }
    public string Author { get; set; }
    public List<string> Tags { get; set; }

public class Author
    public string Name { get; set; }

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

Ten Little Indians crime, fiction Agatha Christie
The Origin of Species science Charles Darwin
David Copperfield scifi, fiction Charles Dickens

Retrieving 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)

Note: You 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 terms facet for the tags.

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

Grouping authors

If you modify the code and instead retrieve a terms facet for author name, the code would 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

Grouping by single words

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


The default maximum number of facets is 10. If you don't take this into account it may lead to surprising results.

You can change this with 

TermsFacetFor(x => x.Something, facet => facet.Size = 50)