You are currently browsing legacy 5.2 version of documentation. Click here to switch to the newest 6.0 version.
    We can help you with migration to the latest RavenDB
    Contact Us Now
    see on GitHub

    Query for suggestions with index

    Configure the index for suggestions

    • In order to be able to ask for suggested terms when querying an index field,
      that field must first be configured for suggestions in the index definition.

    • See the following sample index:
      (This index will be used in the examples ahead).

    public class Products_ByName : AbstractIndexCreationTask<Product, Products_ByName.IndexEntry>
{
    // The IndexEntry class defines the index-fields
    public class IndexEntry
    {
        public string ProductName { get; set; }
    }
    
    public Products_ByName()
    {
        // The 'Map' function defines the content of the index-fields
        Map = products => from product in products
            select new IndexEntry
            {
                ProductName = product.Name
            };

        // Configure index-field 'ProductName' for suggestions
        Suggestion(x => x.ProductName);
        
        // Optionally: set 'Search' on this field
        // This will split the field content into multiple terms allowing for a full-text search
        Indexes.Add(x => x.ProductName, FieldIndexing.Search);
    }
}

    Increased indexing time:

    • When configuring an index for suggestions, then during the indexing process,
      in addition to the regular breakdown of the data into terms (tokenization),
      RavenDB will scramble the terms to simulate common errors.

    • This can impact indexing speed but the cost of querying suggestions is Not impacted.

    The index terms

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

    Figure 1. Index terms

    Terms generated for index Products/ByName

    1. The index-field name - as defined in the index definition.
      In this example the field name is ProductName.

    2. The terms that were generated for this index-field from the documents in the Products collection.

      • The image shows a partial view out of the 163 terms in this list.
      • The terms were generated by RavenDB's default search analyzer since full-text search was set on this field.

    Suggest terms - for single term

    Based on the Northwind sample data,
    the following query on the index Products/ByName from above has no resulting documents,
    since the term chokolade does Not exist in the index terms for index-field ProductName.

    // This query on index 'Products/ByName' has NO resulting documents
List<Product> products = session
    .Query<Products_ByName.IndexEntry, Products_ByName>()
    .Search(x => x.ProductName, "chokolade")
    .OfType<Product>()
    .ToList();

    If you suspect that the term chokolate in the query criteria is written incorrectly,
    you can ask RavenDB to suggest similar terms from the index, as follows:

    // Query the index for suggested terms for single term:
// ====================================================

Dictionary<string, SuggestionResult> suggestions = session
     // Query the index   
    .Query<Products_ByName.IndexEntry, Products_ByName>()
     // Call 'SuggestUsing'
    .SuggestUsing(builder => builder
         // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' 
        .ByField(x => x.ProductName, "chokolade"))
    .Execute();
    // Query the index for suggested terms for single term:
// ====================================================

Dictionary<string, SuggestionResult> suggestions = await asyncSession
     // Query the index   
    .Query<Products_ByName.IndexEntry, Products_ByName>()
     // Call 'SuggestUsing'
    .SuggestUsing(builder => builder
         // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' 
        .ByField(x => x.ProductName, "chokolade"))
    .ExecuteAsync();
    // Define the suggestion request for single term
var suggestionRequest = new SuggestionWithTerm("ProductName")
{
    // Looking for terms from index-field 'ProductName' that are similar to 'chokolade'  
    Term = "chokolade"
};

// Query the index for suggestions 
Dictionary<string, SuggestionResult> suggestions = session
    .Query<Products_ByName.IndexEntry, Products_ByName>()
     // Call 'SuggestUsing' - pass the suggestion request
    .SuggestUsing(suggestionRequest)
    .Execute();
    // Query the index for suggested terms for single term:
// ====================================================

Dictionary<string, SuggestionResult> suggestions = session.Advanced
     // Query the index   
    .DocumentQuery<Products_ByName.IndexEntry, Products_ByName>()
     // Call 'SuggestUsing'
    .SuggestUsing(builder => builder
         // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' 
        .ByField(x => x.ProductName, "chokolade"))
    .Execute();
    // Query for terms from index-field 'ProductName' that are similar to 'chokolade'
from index "Products/ByName" 
select suggest(ProductName, "chokolade")

    // The resulting suggested terms:
// ==============================

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

// Suggested terms in index-field 'ProductName' that are similar to 'chokolade':
//     schokolade
//     chocolade
//     chocolate

    Suggest terms - for multiple terms 

    // Query the index for suggested terms for multiple terms:
// =======================================================

Dictionary<string, SuggestionResult> suggestions = session
     // Query the index
    .Query<Products_ByName.IndexEntry, Products_ByName>()
     // Call 'SuggestUsing'
    .SuggestUsing(builder => builder
         // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' 
        .ByField(x => x.ProductName, new[] { "chokolade", "syrop" }))
    .Execute();
    // Query the index for suggested terms for multiple terms:
// =======================================================

Dictionary<string, SuggestionResult> suggestions = await asyncSession
     // Query the index   
    .Query<Products_ByName.IndexEntry, Products_ByName>()
     // Call 'SuggestUsing'
    .SuggestUsing(builder => builder
         // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' 
        .ByField(x => x.ProductName, new[] { "chokolade", "syrop" }))
    .ExecuteAsync();
    // Define the suggestion request for multiple terms
var suggestionRequest = new SuggestionWithTerms("ProductName")
{
    // Looking for terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop'  
    Terms = new[] { "chokolade", "syrop"}
};

// Query the index for suggestions 
Dictionary<string, SuggestionResult> suggestions = session
    .Query<Products_ByName.IndexEntry, Products_ByName>()
     // Call 'SuggestUsing' - pass the suggestion request
    .SuggestUsing(suggestionRequest)
    .Execute();
    // Query the index for suggested terms for multiple terms:
// =======================================================

Dictionary<string, SuggestionResult> suggestions = session.Advanced
     // Query the index   
    .DocumentQuery<Products_ByName.IndexEntry, Products_ByName>()
     // Call 'SuggestUsing'
    .SuggestUsing(builder => builder
         // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop'  
        .ByField(x => x.ProductName, new[] { "chokolade", "syrop" }))
    .Execute();
    // Query for terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop'
from index "Products/ByName" select suggest(ProductName, $p0)
{ "p0" : ["chokolade", "syrop"] }

    // The resulting suggested terms:
// ==============================

// Suggested terms in index-field 'ProductName' that are similar to 'chokolade' OR to 'syrop':
//     schokolade
//     chocolade
//     chocolate
//     sirop
//     syrup

    Suggest terms - for multiple fields 

    // Query the index for suggested terms in multiple fields:
// =======================================================

Dictionary<string, SuggestionResult> suggestions = session
     // Query the index
    .Query<Companies_ByNameAndByContactName.IndexEntry, Companies_ByNameAndByContactName>()
     // Call 'SuggestUsing' to get suggestions for terms that are 
     // similar to 'chese' in first index-field (e.g. 'CompanyName') 
    .SuggestUsing(builder => builder
        .ByField(x => x.CompanyName, "chese" ))
     // Call 'AndSuggestUsing' to get suggestions for terms that are 
     // similar to 'frank' in an additional index-field (e.g. 'ContactName')
    .AndSuggestUsing(builder => builder
        .ByField(x => x.ContactName, "frank"))
    .Execute();
    // Query the index for suggested terms in multiple fields:
// =======================================================

Dictionary<string, SuggestionResult> suggestions = await asyncSession
     // Query the index
    .Query<Companies_ByNameAndByContactName.IndexEntry, Companies_ByNameAndByContactName>()
     // Call 'SuggestUsing' to get suggestions for terms that are 
     // similar to 'chese' in first index-field (e.g. 'CompanyName') 
    .SuggestUsing(builder => builder
        .ByField(x => x.CompanyName, "chese" ))
     // Call 'AndSuggestUsing' to get suggestions for terms that are 
     // similar to 'frank' in an additional index-field (e.g. 'ContactName')
    .AndSuggestUsing(builder => builder
        .ByField(x => x.ContactName, "frank"))
    .ExecuteAsync();
    // Define suggestion requests for multiple fields:

var request1 = new SuggestionWithTerm("CompanyName")
{
    // Looking for terms from index-field 'CompanyName' that are similar to 'chese'  
    Term = "chese"
};

var request2 = new SuggestionWithTerm("ContactName")
{
    // Looking for terms from nested index-field 'ContactName' that are similar to 'frank'  
    Term = "frank"
};

// Query the index for suggestions 
Dictionary<string, SuggestionResult> suggestions = session
    .Query<Companies_ByNameAndByContactName.IndexEntry, Companies_ByNameAndByContactName>()
     // Call 'SuggestUsing' - pass the suggestion request for the first index-field
    .SuggestUsing(request1)
     // Call 'AndSuggestUsing' - pass the suggestion request for the second index-field
    .AndSuggestUsing(request2)
    .Execute();
    // Query the index for suggested terms in multiple fields:
// =======================================================

Dictionary<string, SuggestionResult> suggestions = session.Advanced
     // Query the index
    .DocumentQuery<Companies_ByNameAndByContactName.IndexEntry, Companies_ByNameAndByContactName>()
     // Call 'SuggestUsing' to get suggestions for terms that are 
     // similar to 'chese' in first index-field (e.g. 'CompanyName') 
    .SuggestUsing(builder => builder
        .ByField(x => x.CompanyName, "chese" ))
     // Call 'AndSuggestUsing' to get suggestions for terms that are 
     // similar to 'frank' in an additional index-field (e.g. 'ContactName')
    .AndSuggestUsing(builder => builder
        .ByField(x => x.ContactName, "frank"))
    .Execute();
    public class Companies_ByNameAndByContactName :
    AbstractIndexCreationTask<Company, Companies_ByNameAndByContactName.IndexEntry>
{
    // The IndexEntry class defines the index-fields.
    public class IndexEntry
    {
        public string CompanyName { get; set; }
        public string ContactName { get; set; }
    }
    
    public Companies_ByNameAndByContactName()
    {
        // The 'Map' function defines the content of the index-fields
        Map = companies => from company in companies
            select new IndexEntry
            {
                CompanyName = company.Name,
                ContactName = company.Contact.Name
            };

        // Configure the index-fields for suggestions
        Suggestion(x => x.CompanyName);
        Suggestion(x => x.ContactName);
        
        // Optionally: set 'Search' on the index-fields
        // This will split the fields' content into multiple terms allowing for a full-text search
        Indexes.Add(x => x.CompanyName, FieldIndexing.Search);
        Indexes.Add(x => x.ContactName, FieldIndexing.Search);
    }
}
    // Query for suggested terms 
// from index-field 'CompanyName' AND from index-field 'ContactName'
from index "Companies/ByNameAndByContactName"
select suggest(CompanyName, "chese"), suggest(ContactName, "frank")

    // The resulting suggested terms:
// ==============================

// Suggested terms in index-field 'CompanyName' that is similar to 'chese':
//     cheese
//     chinese

// Suggested terms in index-field 'ContactName' that are similar to 'frank':
//     fran
//     franken

    Suggest terms - customize options and display name 

    // Query the index for suggested terms - customize options and display name:
// =========================================================================

Dictionary<string, SuggestionResult> suggestions = session
     // Query the index   
    .Query<Products_ByName.IndexEntry, Products_ByName>()
     // Call 'SuggestUsing'
    .SuggestUsing(builder => builder
        .ByField(x => x.ProductName, "chokolade")
     // Customize suggestions options
    .WithOptions(new SuggestionOptions
    {
        Accuracy = 0.3f,
        PageSize = 5,
        Distance = StringDistanceTypes.NGram,
        SortMode = SuggestionSortMode.Popularity
    })
     // Customize display name for results
    .WithDisplayName("SomeCustomName"))
    .Execute();
    // Query the index for suggested terms - customize options and display name:
// =========================================================================

Dictionary<string, SuggestionResult> suggestions = await asyncSession
     // Query the index   
    .Query<Products_ByName.IndexEntry, Products_ByName>()
     // Call 'SuggestUsing'
    .SuggestUsing(builder => builder
        .ByField(x => x.ProductName, "chokolade")
     // Customize suggestions options
    .WithOptions(new SuggestionOptions
    {
        Accuracy = 0.3f,
        PageSize = 5,
        Distance = StringDistanceTypes.NGram,
        SortMode = SuggestionSortMode.Popularity
    })
     // Customize display name for results
    .WithDisplayName("SomeCustomName"))
    .ExecuteAsync();
    // Define the suggestion request
var suggestionRequest = new SuggestionWithTerm("ProductName")
{
    // Looking for terms from index-field 'ProductName' that are similar to 'chokolade'  
    Term = "chokolade",
    // Customize options
    Options = new SuggestionOptions 
    {
        Accuracy = 0.3f,
        PageSize = 5,
        Distance = StringDistanceTypes.NGram,
        SortMode = SuggestionSortMode.Popularity
    },
    // Customize display name
    DisplayField = "SomeCustomName"
};

// Query the index for suggestions 
Dictionary<string, SuggestionResult> suggestions = session
    .Query<Products_ByName.IndexEntry, Products_ByName>()
    // Call 'SuggestUsing' - pass the suggestion request
    .SuggestUsing(suggestionRequest)
    .Execute();
    // Query the index for suggested terms - customize options and display name:
// =========================================================================

Dictionary<string, SuggestionResult> suggestions = session.Advanced
     // Query the index   
    .DocumentQuery<Products_ByName.IndexEntry, Products_ByName>()
     // Call 'SuggestUsing'
    .SuggestUsing(builder => builder
        .ByField(x => x.ProductName, "chokolade")
         // Customize suggestions options
        .WithOptions(new SuggestionOptions
        {
            Accuracy = 0.3f,
            PageSize = 5,
            Distance = StringDistanceTypes.NGram,
            SortMode = SuggestionSortMode.Popularity
        })
         // Customize display name for results
        .WithDisplayName("SomeCustomName"))
    .Execute();
    // Query for suggested terms - customize options and display name
from index "Products/ByName"
select suggest(
    ProductName,
    "chokolade",
    '{ "Accuracy" : 0.3, "PageSize" : 5, "Distance" : "NGram", "SortMode" : "Popularity" }'
) as "SomeCustomName"

    // 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:
//     chocolade
//     schokolade
//     chocolate
//     chowder
//     marmalade

    see on GitHub

    related articlesRelated Articles

    Client API

    Home / Docs / Indexes / Querying / Suggestions