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

Facets are used for grouping documents based on criteria, such as specific terms or date ranges. 

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 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.

Before providing examples, you need to give 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.

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.


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.

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.

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