{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.
-
In this page:
{NOTE/}
{PANEL: 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.
{PANEL/}
{PANEL: 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.
{WARNING/}
{PANEL/}
{PANEL: 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.
{CODE:nodejs suggest_1@ClientApi\Session\Querying\workWithSuggestions.js /}
-
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 fieldName.
The generated terms are visible in the Studio - see image below. -
If you suspect that the term
chaigin the query criteria is written incorrectly,
you can ask RavenDB to suggest existing terms that are similar tochaig, as follows:.
{CODE-TABS} {CODE-TAB:nodejs:Query suggest_2@ClientApi\Session\Querying\workWithSuggestions.js /} {CODE-TAB-BLOCK:sql:RQL} // Query for terms from field 'Name' that are similar to 'chaig' from "Products" select suggest(Name, "chaig") {CODE-TAB-BLOCK/} {CODE-TABS/}
{CODE:nodejs suggest_3@ClientApi\Session\Querying\workWithSuggestions.js /}
{PANEL/}
{PANEL: Suggest terms - for multiple terms}
{CODE-TABS} {CODE-TAB:nodejs:Query suggest_4@ClientApi\Session\Querying\workWithSuggestions.js /} {CODE-TAB-BLOCK:sql:RQL} // Query for terms from field 'Name' that are similar to 'chaig' OR 'tof' from "Products" select suggest(Name, $p0) { "p0" : ["chaig", "tof"] } {CODE-TAB-BLOCK/} {CODE-TABS/}
{CODE:nodejs suggest_5@ClientApi\Session\Querying\workWithSuggestions.js /}
{PANEL/}
{PANEL: Suggest terms - for multiple fields}
{CODE-TABS} {CODE-TAB:nodejs:Query suggest_6@ClientApi\Session\Querying\workWithSuggestions.js /} {CODE-TAB-BLOCK:sql:RQL} // Query for suggested terms from field 'Name' and field 'Contact.Name' from "Companies" select suggest(Name, "chop-soy china"), suggest(Contact.Name, "maria larson") {CODE-TAB-BLOCK/} {CODE-TABS/}
{CODE:nodejs suggest_7@ClientApi\Session\Querying\workWithSuggestions.js /}
{PANEL/}
{PANEL: Suggest terms - customize options and display name}
{CODE-TABS} {CODE-TAB:nodejs:Query suggest_8@ClientApi\Session\Querying\workWithSuggestions.js /} {CODE-TAB-BLOCK:sql:RQL} // 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" {CODE-TAB-BLOCK/} {CODE-TABS/}
{CODE:nodejs suggest_9@ClientApi\Session\Querying\workWithSuggestions.js /}
{PANEL/}
{PANEL: The auto-index terms in Studio}
Based on the Northwind sample data, these are the terms generated for index Auto/Products/ByName:
-
The field name - derived from the document field that was used in the dynamic-query.
In this example the field name isName. -
The terms generated from the data that the Products collection documents have in their
Namefield.
{PANEL/}
{PANEL: Syntax}
Suggest using:
{CODE:nodejs syntax_1@ClientApi\Session\Querying\workWithSuggestions.js /}
| Parameter | Type | Description |
|---|---|---|
| action | (builder) => void |
Builder function with a fluent API that constructs a SuggestionBase instance. |
Builder operations:
{CODE:nodejs syntax_2@ClientApi\Session\Querying\workWithSuggestions.js /}
| Parameter | Type | Description |
|---|---|---|
| fieldName | string |
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 | object |
Non-default suggestion options to use in the operation (optional). See available options below. |
Suggestions options:
| Option | Type | Description |
|---|---|---|
| pageSize | number |
|
| distance | string |
|
| accuracy | number |
|
| sortMode | string |
|
{PANEL/}