---
title: "Query for Suggestions"
url: "https://docs.ravendb.net/6.2/client-api/session/querying/how-to-work-with-suggestions"
version: "6.2"
language: "csharp"
---

# Query for Suggestions

> Client language: C#. Also available for [Java](https://docs.ravendb.net/6.2/client-api/session/querying/how-to-work-with-suggestions.java.md), [Python](https://docs.ravendb.net/6.2/client-api/session/querying/how-to-work-with-suggestions.python.md), [PHP](https://docs.ravendb.net/6.2/client-api/session/querying/how-to-work-with-suggestions.php.md), [Node.js](https://docs.ravendb.net/6.2/client-api/session/querying/how-to-work-with-suggestions.nodejs.md).
>
> RavenDB publishes an official agent skill for coding assistants at https://docs.ravendb.net/skills/ravendb/SKILL.md (also installable with `npx skills add ravendb/skills`). The skill describes itself as: "Read this before writing any RavenDB query, client call or /databases/ request. Covers server setup, document modelling, the Node.js, .NET and Python clients, RQL, indexes, vector search and AI agents. Code written from recall tends to run and return the wrong rows, because RQL resembles SQL and the clients take field names as plain strings."

> **Note**
>
> - Given a string term, the Suggestion feature will offer **similar terms** from your data.
>
> - Word similarities are found using string distance algorithms.
>
> - Examples in this article demonstrate getting suggestions with a **dynamic-query**.  
>   For getting suggestions with an **index-query** see [query for suggestions with index](https://docs.ravendb.net/6.2/indexes/querying/suggestions.md).
>
> - In this page:
>
>   - Overview:
>     - [What are terms](#what-are-terms)
>     - [When to use suggestions](#when-to-use-suggestions)
>
>   - Examples:
>     - [Suggest terms - for single term](#suggest-terms---for-single-term)
>     - [Suggest terms - for multiple terms](#suggest-terms---for-multiple-terms)
>     - [Suggest terms - for multiple fields](#suggest-terms---for-multiple-fields)
>     - [Suggest terms - customize options and display name](#suggest-terms---customize-options-and-display-name)
>
>   - [The auto-index terms in Studio](#the-auto-index-terms-in-studio)
>
>   - [Syntax](#syntax)

## What are terms

- All queries in RavenDB use an index - learn more about that [here](https://docs.ravendb.net/6.2/client-api/session/querying/how-to-query.md#queries-always-provide-results-using-an-index).  
  Whether making a dynamic query which generates an auto-index or using a static index,  
  the data from your documents is 'broken' into **terms** that are kept in the index.

- This tokenization process (what terms will be generated) depends on the analyzer used,  
  various analyzers differ in the way they split the text stream. Learn more in [Analyzers](https://docs.ravendb.net/6.2/indexes/using-analyzers.md).

- The terms can then be queried to retrieve matching documents that contain them.

## When to use suggestions

Querying for suggestions is useful in the following scenarios:

- **When query has no results**:

  - When searching for documents that match some condition on a given string term,  
    if the term is misspelled then you will Not get any results.  
    You can then ask RavenDB to suggest similar terms that do exist in the index.

  - The suggested terms can then be used in a new query to retrieve matching documents,  
    or simply presented to the user asking what they meant to query.

- **When looking for alternative terms**:

  - When simply searching for additional alternative terms for a term that does exist.

> **Warning**
>
> The resulting suggested terms will Not include the term for which you search,  
> they will only contain the similar terms.

## Suggest terms - for single term

Consider this example:  
Based on the Northwind sample data, the following query has no resulting documents,  
as no document in the Products collection contains the term `chaig` in its `Name` field.

```csharp
// This dynamic query on the 'Products' collection has NO resulting documents
List<Product> products = session
  .Query<Product>()
  .Where(x => x.Name == "chaig")
  .ToList();
```

- Executing the above query will generate the auto-index `Auto/Products/ByName`.  
  This auto-index will contain a list of all available terms from the document field `Name`.  
  The generated terms are visible in the Studio - see image [below](#the-auto-index-terms-in-studio).

- If you suspect that the term `chaig` in the query criteria is written incorrectly,  
  you can ask RavenDB to suggest **existing terms** that are similar to `chaig`, as follows:.

### Query

```csharp
// Query for suggested terms for single term:
// ==========================================

Dictionary<string, SuggestionResult> suggestions = session
   // Make a dynamic query on collection 'Products'
  .Query<Product>()
   // Call 'SuggestUsing'
  .SuggestUsing(builder => builder
       // Request to get terms from field 'Name' that are similar to 'chaig' 
      .ByField(x => x.Name, "chaig"))
  .Execute();
```

### Query\_async

```csharp
// Query for suggested terms for single term:
// ==========================================

Dictionary<string, SuggestionResult> suggestions = await asyncSession
   // Make a dynamic query on collection 'Products'
  .Query<Product>()
   // Call 'SuggestUsing'
  .SuggestUsing(builder => builder
       // Request to get terms from field 'Name' that are similar to 'chaig'  
      .ByField(x => x.Name, "chaig"))
  .ExecuteAsync();
```

### Query\_overload

```csharp
// Define the suggestion request for single term
var suggestionRequest = new SuggestionWithTerm("Name")
{
  // Looking for terms from field 'Name' that are similar to term 'chaig'  
  Term = "chaig"
};

// Query for suggestions 
Dictionary<string, SuggestionResult> suggestions = session
  .Query<Product>()
   // Call 'SuggestUsing' - pass the suggestion request
  .SuggestUsing(suggestionRequest)
  .Execute();
```

### DocumentQuery

```csharp
// Query for suggested terms for single term:
// ==========================================

Dictionary<string, SuggestionResult> suggestions = session.Advanced
   // Make a dynamic document-query on collection 'Products'
  .DocumentQuery<Product>()
   // Call 'SuggestUsing' 
  .SuggestUsing(builder => builder
       // Request to get terms from field 'Name' that are similar to 'chaig' 
      .ByField(x => x.Name, "chaig"))
  .Execute();
```

### RQL

```sql
// Query for terms from field 'Name' that are similar to 'chaig'
from "Products"
select suggest(Name, "chaig")
```

```csharp
// The resulting suggested terms:
// ==============================

Console.WriteLine("Suggested terms in field 'Name' that are similar to 'chaig':");
foreach (string suggestedTerm in suggestions["Name"].Suggestions)
{
  Console.WriteLine("\t{0}", suggestedTerm);
}

// Suggested terms in field 'Name' that are similar to 'chaig':
//     chai
//     chang
```

## Suggest terms - for multiple terms

### Query

```csharp
// Query for suggested terms for multiple terms:
// =============================================

Dictionary<string, SuggestionResult> suggestions = session
   // Make a dynamic query on collection 'Products'
  .Query<Product>()
   // Call 'SuggestUsing'
  .SuggestUsing(builder => builder
       // Request to get terms from field 'Name' that are similar to 'chaig' OR 'tof' 
      .ByField(x => x.Name, new[] { "chaig", "tof" }))
  .Execute();
```

### Query\_async

```csharp
// Query for suggested terms for multiple terms:
// =============================================

Dictionary<string, SuggestionResult> suggestions = await asyncSession
   // Make a dynamic query on collection 'Products'
  .Query<Product>()
   // Call 'SuggestUsing' 
  .SuggestUsing(builder => builder
       // Request to get terms from field 'Name' that are similar to 'chaig' OR 'tof'
      .ByField(x => x.Name, new[] { "chaig", "tof" }))
  .ExecuteAsync();
```

### Query\_overload

```csharp
// Define the suggestion request for multiple terms
var suggestionRequest = new SuggestionWithTerms("Name")
{
  // Looking for terms from field 'Name' that are similar to terms 'chaig' OR 'tof'  
  Terms = new[] { "chaig", "tof"}
};

// Query for suggestions 
Dictionary<string, SuggestionResult> suggestions = session
  .Query<Product>()
   // Call 'SuggestUsing' - pass the suggestion request
  .SuggestUsing(suggestionRequest)
  .Execute();
```

### DocumentQuery

```csharp
// Query for suggested terms for multiple terms:
// =============================================

Dictionary<string, SuggestionResult> suggestions = session.Advanced
   // Make a dynamic document-query on collection 'Products'
  .DocumentQuery<Product>()
   // Call 'SuggestUsing'
  .SuggestUsing(builder => builder
       // Request to get terms from field 'Name' that are similar to 'chaig' OR 'tof' 
      .ByField(x => x.Name, new[] { "chaig", "tof" }))
  .Execute();
```

### RQL

```sql
// Query for terms from field 'Name' that are similar to 'chaig' OR 'tof'
from "Products" select suggest(Name, $p0)
{ "p0" : ["chaig", "tof"] }
```

```csharp
// The resulting suggested terms:
// ==============================

// Suggested terms in field 'Name' that are similar to 'chaig' OR to 'tof':
//     chai
//     chang
//     tofu
```

## Suggest terms - for multiple fields

### Query

```csharp
// Query for suggested terms in multiple fields:
// =============================================

Dictionary<string, SuggestionResult> suggestions = session
   // Make a dynamic query on collection 'Companies'
  .Query<Company>()
   // Call 'SuggestUsing' to get suggestions for terms that are 
   // similar to 'chop-soy china' in first document field (e.g. 'Name') 
  .SuggestUsing(builder => builder
      .ByField(x => x.Name, "chop-soy china"))
   // Call 'AndSuggestUsing' to get suggestions for terms that are 
   // similar to 'maria larson' in an additional field (e.g. 'Contact.Name')
  .AndSuggestUsing(builder => builder
      .ByField(x => x.Contact.Name, "maria larson"))
  .Execute();
```

### Query\_async

```csharp
// Query for suggested terms in multiple fields:
// =============================================

Dictionary<string, SuggestionResult> suggestions = await asyncSession
   // Make a dynamic query on collection 'Companies'   
  .Query<Company>()
   // Call 'SuggestUsing' to get suggestions for terms that are 
   // similar to 'chop-soy china' in first document field (e.g. 'Name') 
  .SuggestUsing(builder => builder
      .ByField(x => x.Name, "chop-soy china"))
   // Call 'AndSuggestUsing' to get suggestions for terms that are 
   // similar to 'maria larson' in an additional field (e.g. 'Contact.Name')
  .AndSuggestUsing(builder => builder
      .ByField(x => x.Contact.Name, "maria larson"))
  .ExecuteAsync();
```

### Query\_overload

```csharp
// Define suggestion requests for multiple fields:

var request1 = new SuggestionWithTerm("Name")
{
  // Looking for terms from field 'Name' that are similar to 'chop-soy china'  
  Term = "chop-soy china"
};

var request2 = new SuggestionWithTerm("Contact.Name")
{
  // Looking for terms from nested field 'Contact.Name' that are similar to 'maria larson'  
  Term = "maria larson"
};

Dictionary<string, SuggestionResult> suggestions = session
  .Query<Company>()
   // Call 'SuggestUsing' - pass the suggestion request for the first field
  .SuggestUsing(request1)
   // Call 'AndSuggestUsing' - pass the suggestion request for the second field
  .AndSuggestUsing(request2)
  .Execute();
```

### DocumentQuery

```csharp
// Query for suggested terms in multiple fields:
// =============================================

Dictionary<string, SuggestionResult> suggestions = session.Advanced
   // Make a dynamic document-query on collection 'Companies'
  .DocumentQuery<Company>()
   // Call 'SuggestUsing' to get suggestions for terms that are 
   // similar to 'chop-soy china' in first document field (e.g. 'Name') 
  .SuggestUsing(builder => builder
      .ByField(x => x.Name, "chop-soy china"))
   // Call 'AndSuggestUsing' to get suggestions for terms that are 
   // similar to 'maria larson' in an additional field (e.g. 'Contact.Name')
  .AndSuggestUsing(builder => builder
      .ByField(x => x.Contact.Name, "maria larson"))
  .Execute();
```

### RQL

```sql
// Query for suggested terms from field 'Name' and field 'Contact.Name'
from "Companies"
select suggest(Name, "chop-soy china"), suggest(Contact.Name, "maria larson")
```

```csharp
// The resulting suggested terms:
// ==============================

// Suggested terms in field 'Name' that is similar to 'chop-soy china':
//     chop-suey chinese

// Suggested terms in field 'Contact.Name' that are similar to 'maria larson':
//     maria larsson
//     marie bertrand
//     aria cruz
//     paula wilson
//     maria anders
```

## Suggest terms - customize options and display name

### Query

```csharp
// Query for suggested terms - customize options and display name:
// ===============================================================

Dictionary<string, SuggestionResult> suggestions = session
   // Make a dynamic query on collection 'Products'
  .Query<Product>()
   // Call 'SuggestUsing'
  .SuggestUsing(builder => builder
      .ByField(x => x.Name, "chaig")
       // Customize suggestions options
      .WithOptions(new SuggestionOptions
      {
          Accuracy = 0.4f,
          PageSize = 5,
          Distance = StringDistanceTypes.JaroWinkler,
          SortMode = SuggestionSortMode.Popularity
      })
       // Customize display name for results
      .WithDisplayName("SomeCustomName"))
  .Execute();
```

### Query\_async

```csharp
// Query for suggested terms - customize options and display name:
// ===============================================================

Dictionary<string, SuggestionResult> suggestions = await asyncSession
   // Make a dynamic query on collection 'Products'
  .Query<Product>()
   // Call 'SuggestUsing'
  .SuggestUsing(builder => builder
      .ByField(x => x.Name, "chaig")
       // Customize suggestions options
      .WithOptions(new SuggestionOptions
      {
          Accuracy = 0.4f,
          PageSize = 5,
          Distance = StringDistanceTypes.JaroWinkler,
          SortMode = SuggestionSortMode.Popularity
      })
       // Customize display name for results
      .WithDisplayName("SomeCustomName"))
  .ExecuteAsync();
```

### Query\_overload

```csharp
// Define the suggestion request
var suggestionRequest = new SuggestionWithTerm("Name")
{
  // Looking for terms from field 'Name' that are similar to term 'chaig'  
  Term = "chaig",
  // Customize options
  Options = new SuggestionOptions 
  {
      Accuracy = 0.4f,
      PageSize = 5,
      Distance = StringDistanceTypes.JaroWinkler,
      SortMode = SuggestionSortMode.Popularity
  },
  // Customize display name
  DisplayField = "SomeCustomName"
};

// Query for suggestions 
Dictionary<string, SuggestionResult> suggestions = session
  .Query<Product>()
  // Call 'SuggestUsing' - pass the suggestion request
  .SuggestUsing(suggestionRequest)
  .Execute();
```

### DocumentQuery

```csharp
// Query for suggested terms - customize options and display name:
// ===============================================================

Dictionary<string, SuggestionResult> suggestions = session.Advanced
   // Make a dynamic query on collection 'Products'
  .DocumentQuery<Product>()
   // Call 'SuggestUsing'
  .SuggestUsing(builder => builder
      .ByField(x => x.Name, "chaig")
       // Customize suggestions options
      .WithOptions(new SuggestionOptions
      {
          Accuracy = 0.4f,
          PageSize = 5,
          Distance = StringDistanceTypes.JaroWinkler,
          SortMode = SuggestionSortMode.Popularity
      })
       // Customize display name for results
      .WithDisplayName("SomeCustomName"))
  .Execute();
```

### RQL

```sql
// Query for suggested terms - customize options and display name
from "Products"
select suggest(
  Name,
  'chaig',
  '{ "Accuracy" : 0.4, "PageSize" : 5, "Distance" : "JaroWinkler", "SortMode" : "Popularity" }'
) as "SomeCustomName"
```

```csharp
// The resulting suggested terms:
// ==============================

Console.WriteLine("Suggested terms:");
// Results are available under the custom name entry
foreach (string suggestedTerm in suggestions["SomeCustomName"].Suggestions)
{
  Console.WriteLine("\t{0}", suggestedTerm);
}

// Suggested terms:
//     chai
//     chang
//     chartreuse verte
```

## The auto-index terms in Studio

Based on the Northwind sample data, these are the terms generated for index `Auto/Products/ByName`:

![Figure 1. Auto-index terms](https://docs.ravendb.net/assets/images/auto-index-terms-22a0dd88b792b1192dc5f78cb5a63cd4.png)

1. **The field name** - derived from the document field that was used in the dynamic-query.  
   In this example the field name is `Name`.

2. **The terms** generated from the data that the Products collection documents have in their `Name` field.

## Syntax

**Suggest using**:

```csharp
// Overloads for requesting suggestions for term(s) in a field: 
ISuggestionQuery<T> SuggestUsing<T>(SuggestionBase suggestion);
ISuggestionQuery<T> SuggestUsing<T>(Action<ISuggestionBuilder<T>> builder);

// Overloads requesting suggestions for term(s) in another field in the same query:
ISuggestionQuery<T> AndSuggestUsing(SuggestionBase suggestion);
ISuggestionQuery<T> AndSuggestUsing(Action<ISuggestionBuilder<T>> builder);
```

| Parameter | Type | Description |
| - | - | - |
| **suggestion** | `SuggestionWithTerm` / `SuggestionWithTerms` | An instance of `SuggestionBase`.<br />Defines the type of suggestion requested. |
| **builder** | `Action<ISuggestionBuilder<T>>` | Builder with a fluent API that constructs a `SuggestionBase` instance. |

**Builder operations**:

```csharp
ISuggestionOperations<T> ByField(string fieldName, string term);
ISuggestionOperations<T> ByField(string fieldName, string[] terms);
ISuggestionOperations<T> ByField(Expression<Func<T, object>> path, string term);
ISuggestionOperations<T> ByField(Expression<Func<T, object>> path, string[] terms);

ISuggestionOperations<T> WithDisplayName(string displayName);
ISuggestionOperations<T> WithOptions(SuggestionOptions options);
```

| Parameter | Type | Description |
| - | - | - |
| **fieldName** | `string` | The index field in which to search for similar terms |
| **path** | `Expression<Func<T, object>>` | The index field in which to search for similar terms |
| **term** | `string` | The term for which to get suggested similar terms |
| **terms** | `string[]` | List of terms for which to get suggested similar terms |
| **displayName** | `string` | A custom name for the suggestions result (optional). |
| **options** | `SuggestionOptions` | Non-default options to use in the operation (optional). |

**Suggestions options**:

```csharp
public int PageSize { get; set; }
public StringDistanceTypes? Distance { get; set; }
public float? Accuracy { get; set; }
public SuggestionSortMode SortMode { get; set; }
```

| Option | Type | Description |
| - | - | - |
| **PageSize** | `int` | <ul><li>Maximum number of suggested terms that will be returned.</li><li>Default is <strong>15</strong></li></ul> |
| **Distance** | `StringDistanceTypes` | <ul><li>String distance algorithm to use.</li><li><code>None</code> / <code>Levenshtein</code> / <code>JaroWinkler</code> / <code>NGram</code></li><li>Default is <strong>Levenshtein</strong>.</li></ul> |
| **Accuracy** | `float?` | <ul><li>Suggestion accuracy.</li><li>Default is <strong>0.5f</strong></li></ul> |
| **SortMode** | `SuggestionSortMode` | <ul><li>Indicates the order by which results are returned.</li><li><code>None</code> / <code>Popularity</code></li><li>Default is <strong>Popularity</strong>.</li></ul> |

## See also

- [Querying: Basics](https://docs.ravendb.net/6.2/indexes/querying/query-index.md)
- [How to Query](https://docs.ravendb.net/6.2/client-api/session/querying/how-to-query.md)
- [Query for suggestions with index](https://docs.ravendb.net/6.2/indexes/querying/suggestions.md)
