Query for Suggestions

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

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.

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
const products = await session
    .query({ collection: "Products" })
    .whereEquals("Name", "Chai")
    .all();

• 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:
// ==========================================

const suggestions = await session
     // Make a dynamic query on collection 'Products'
    .query({ collection: "Products" })
     // Call 'suggestUsing'
    .suggestUsing(x => x
         // Request to get terms from field 'Name' that are similar to 'chaig' 
        .byField("Name", "chaig"))
    .execute();

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

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

console.log("Suggested terms in field 'Name' that are similar to 'chaig':");
suggestions["Name"].suggestions.forEach(suggestedTerm => {
    console.log("\t" + suggestedTerm);
});

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

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

const suggestions = await session
     // Make a dynamic query on collection 'Products'
    .query({ collection: "Products" })
     // Call 'suggestUsing'
    .suggestUsing(x => x
         // Request to get terms from field 'Name' that are similar to 'chaig' OR 'tof' 
        .byField("Name", ["chaig", "tof"]))
    .execute();

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

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

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

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

const suggestions = await session
     // Make a dynamic query on collection 'Companies'
    .query({ collection: "Companies" })
     // Call 'suggestUsing' to get suggestions for terms that are 
     // similar to 'chop-soy china' in first document field (e.g. 'Name') 
    .suggestUsing(x => x
        .byField("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(x => x
        .byField("Contact.Name", "maria larson"))
    .execute();        

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

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

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

const suggestions = await session
     // Make a dynamic query on collection 'Products'
    .query({ collection: "Products" })
     // Call 'suggestUsing'
    .suggestUsing(x => x
        .byField("Name", "chaig")
         // Customize suggestions options
        .withOptions({
            accuracy: 0.4,
            pageSize: 5,
            distance: "JaroWinkler",
            sortMode: "Popularity"
        })
         // Customize display name for results
        .withDisplayName("SomeCustomName"))
    .execute();

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

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

console.log("Suggested terms:");
// Results are available under the custom name entry
suggestions["SomeCustomName"].suggestions.forEach(suggestedTerm => {
    console.log("\t" + suggestedTerm);
});

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

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

Terms generated for index Auto/Products/ByName

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.

Suggest using:

// Requesting suggestions for term(s) in a field: 
suggestUsing(action);

// Requesting suggestions for term(s) in another field in the same query:
andSuggestUsing(action);

Builder operations:

byField(fieldName, term);
byField(fieldName, terms);

withDisplayName(displayName);
withOptions(options);

Suggestions options: