Skip to main content

Query for Suggestions

What are terms​

  • All queries in RavenDB use an index - learn more about that here.
    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.

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

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.

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

  • 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 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();
// 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 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();
// 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 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();
// 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 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();
// 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

  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:

// 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);
ParameterTypeDescription
suggestionSuggestionWithTerm / SuggestionWithTermsAn instance of SuggestionBase.
Defines the type of suggestion requested.
builderAction<ISuggestionBuilder<T>>Builder with a fluent API that constructs a SuggestionBase instance.

Builder operations:

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);
ParameterTypeDescription
fieldNamestringThe index field in which to search for similar terms
pathExpression<Func<T, object>>The index field in which to search for similar terms
termstringThe term for which to get suggested similar terms
termsstring[]List of terms for which to get suggested similar terms
displayNamestringA custom name for the suggestions result (optional).
optionsSuggestionOptionsNon-default options to use in the operation (optional).

Suggestions options:

public int PageSize { get; set; }
public StringDistanceTypes? Distance { get; set; }
public float? Accuracy { get; set; }
public SuggestionSortMode SortMode { get; set; }
OptionTypeDescription
PageSizeint<ul><li>Maximum number of suggested terms that will be returned</li><li>Default is <strong>15</strong></li></ul>
DistanceStringDistanceTypes<ul><li>String distance algorithm to use</li><li>None / Levenshtein / JaroWinkler / NGram</li><li>Default is <strong>Levenshtein</strong></li></ul>
Accuracyfloat?<ul><li>Suggestion accuracy</li><li>Default is <strong>0.5f</strong></li></ul>
SortModeSuggestionSortMode<ul><li>Indicates the order by which results are returned</li><li>None / Popularity</li><li>Default is <strong>Popularity</strong></li></ul>