diff --git a/Documentation/5.2/Raven.Documentation.Pages/client-api/session/querying/.docs.json b/Documentation/5.2/Raven.Documentation.Pages/client-api/session/querying/.docs.json index 2028ecf54a..6a77aac946 100644 --- a/Documentation/5.2/Raven.Documentation.Pages/client-api/session/querying/.docs.json +++ b/Documentation/5.2/Raven.Documentation.Pages/client-api/session/querying/.docs.json @@ -132,7 +132,7 @@ }, { "Path": "how-to-work-with-suggestions.markdown", - "Name": "How to Work With Suggestions", + "Name": "Query for Suggestions", "DiscussionId": "a4f62c57-a06a-440c-b1a3-4cbaa9a4f0d0", "Mappings": [ { diff --git a/Documentation/5.2/Raven.Documentation.Pages/client-api/session/querying/document-query/what-is-document-query.dotnet.markdown b/Documentation/5.2/Raven.Documentation.Pages/client-api/session/querying/document-query/what-is-document-query.dotnet.markdown index be657c3778..d19b4e7bec 100644 --- a/Documentation/5.2/Raven.Documentation.Pages/client-api/session/querying/document-query/what-is-document-query.dotnet.markdown +++ b/Documentation/5.2/Raven.Documentation.Pages/client-api/session/querying/document-query/what-is-document-query.dotnet.markdown @@ -218,7 +218,7 @@ Available custom methods and extensions: - Skip - [Query] [Spatial](../../../../client-api/session/querying/how-to-make-a-spatial-query) - Statistics -- SuggestUsing +- [SuggestUsing](../../../../client-api/session/querying/how-to-work-with-suggestions) - Take - [Query] [Timings](../../../../client-api/session/querying/how-to-customize-query#timings) - UsingDefaultOperator diff --git a/Documentation/5.2/Raven.Documentation.Pages/client-api/session/querying/how-to-query.js.markdown b/Documentation/5.2/Raven.Documentation.Pages/client-api/session/querying/how-to-query.js.markdown index 4b48faaef6..8b6fc106ea 100644 --- a/Documentation/5.2/Raven.Documentation.Pages/client-api/session/querying/how-to-query.js.markdown +++ b/Documentation/5.2/Raven.Documentation.Pages/client-api/session/querying/how-to-query.js.markdown @@ -307,7 +307,7 @@ Available methods for the session's [query](../../../client-api/session/querying - skip - spatial - [statistics](../../../client-api/session/querying/how-to-get-query-statistics) -- suggestUsing +- [suggestUsing](../../../client-api/session/querying/how-to-work-with-suggestions) - take - timings - usingDefaultOperator diff --git a/Documentation/5.2/Raven.Documentation.Pages/client-api/session/querying/how-to-work-with-suggestions.dotnet.markdown b/Documentation/5.2/Raven.Documentation.Pages/client-api/session/querying/how-to-work-with-suggestions.dotnet.markdown new file mode 100644 index 0000000000..9772405fdf --- /dev/null +++ b/Documentation/5.2/Raven.Documentation.Pages/client-api/session/querying/how-to-work-with-suggestions.dotnet.markdown @@ -0,0 +1,221 @@ +# Query for Suggestions + +--- + +{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](../../../indexes/querying/suggestions). + +--- + +* In this page: + + * Overview: + * [What are terms](../../../client-api/session/querying/how-to-work-with-suggestions#what-are-terms) + * [When to use suggestions](../../../client-api/session/querying/how-to-work-with-suggestions#when-to-use-suggestions) + + * Examples: + * [Suggest terms - for single term](../../../client-api/session/querying/how-to-work-with-suggestions#suggest-terms---for-single-term) + * [Suggest terms - for multiple terms](../../../client-api/session/querying/how-to-work-with-suggestions#suggest-terms---for-multiple-terms) + * [Suggest terms - for multiple fields](../../../client-api/session/querying/how-to-work-with-suggestions#suggest-terms---for-multiple-fields) + * [Suggest terms - customize options and display name](../../../client-api/session/querying/how-to-work-with-suggestions#suggest-terms---customize-options-and-display-name) + + * [The auto-index terms in Studio](../../../client-api/session/querying/how-to-work-with-suggestions#the-auto-index-terms-in-studio) + * [Syntax](../../../client-api/session/querying/how-to-work-with-suggestions#syntax) + +{NOTE/} + +--- + +{PANEL: What are terms} + +* All queries in RavenDB use an index - learn more about that [here](../../../client-api/session/querying/how-to-query#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](../../../indexes/using-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 suggest_1@ClientApi\Session\Querying\HowToWorkWithSuggestions.cs /} + +* 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](../../../client-api/session/querying/how-to-work-with-suggestions#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:. + +{CODE-TABS} +{CODE-TAB:csharp:Query suggest_2@ClientApi\Session\Querying\HowToWorkWithSuggestions.cs /} +{CODE-TAB:csharp:Query_async suggest_3@ClientApi\Session\Querying\HowToWorkWithSuggestions.cs /} +{CODE-TAB:csharp:Query_overload suggest_4@ClientApi\Session\Querying\HowToWorkWithSuggestions.cs /} +{CODE-TAB:csharp:DocumentQuery suggest_5@ClientApi\Session\Querying\HowToWorkWithSuggestions.cs /} +{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 suggest_6@ClientApi\Session\Querying\HowToWorkWithSuggestions.cs /} + +{PANEL/} + +{PANEL: Suggest terms - for multiple terms} + +{CODE-TABS} +{CODE-TAB:csharp:Query suggest_7@ClientApi\Session\Querying\HowToWorkWithSuggestions.cs /} +{CODE-TAB:csharp:Query_async suggest_8@ClientApi\Session\Querying\HowToWorkWithSuggestions.cs /} +{CODE-TAB:csharp:Query_overload suggest_9@ClientApi\Session\Querying\HowToWorkWithSuggestions.cs /} +{CODE-TAB:csharp:DocumentQuery suggest_10@ClientApi\Session\Querying\HowToWorkWithSuggestions.cs /} +{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 suggest_11@ClientApi\Session\Querying\HowToWorkWithSuggestions.cs /} + +{PANEL/} + +{PANEL: Suggest terms - for multiple fields} + +{CODE-TABS} +{CODE-TAB:csharp:Query suggest_12@ClientApi\Session\Querying\HowToWorkWithSuggestions.cs /} +{CODE-TAB:csharp:Query_async suggest_13@ClientApi\Session\Querying\HowToWorkWithSuggestions.cs /} +{CODE-TAB:csharp:Query_overload suggest_14@ClientApi\Session\Querying\HowToWorkWithSuggestions.cs /} +{CODE-TAB:csharp:DocumentQuery suggest_15@ClientApi\Session\Querying\HowToWorkWithSuggestions.cs /} +{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 suggest_16@ClientApi\Session\Querying\HowToWorkWithSuggestions.cs /} + +{PANEL/} + +{PANEL: Suggest terms - customize options and display name} + +{CODE-TABS} +{CODE-TAB:csharp:Query suggest_17@ClientApi\Session\Querying\HowToWorkWithSuggestions.cs /} +{CODE-TAB:csharp:Query_async suggest_18@ClientApi\Session\Querying\HowToWorkWithSuggestions.cs /} +{CODE-TAB:csharp:Query_overload suggest_19@ClientApi\Session\Querying\HowToWorkWithSuggestions.cs /} +{CODE-TAB:csharp:DocumentQuery suggest_20@ClientApi\Session\Querying\HowToWorkWithSuggestions.cs /} +{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 suggest_21@ClientApi\Session\Querying\HowToWorkWithSuggestions.cs /} + +{PANEL/} + +{PANEL: 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](images/auto-index-terms.png "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. + +{PANEL/} + +{PANEL: Syntax} + +__Suggest using__: + +{CODE syntax_1@ClientApi\Session\Querying\HowToWorkWithSuggestions.cs /} + +| Parameter | Type | Description | +|----------------|----------------------------------------------|-------------------------------------------------------------------------------| +| __suggestion__ | `SuggestionWithTerm` / `SuggestionWithTerms` | An instance of `SuggestionBase`.
Defines the type of suggestion requested. | +| __builder__ | `Action>` | Builder with a fluent API that constructs a `SuggestionBase` instance. | + +__Builder operations__: + +{CODE syntax_2@ClientApi\Session\Querying\HowToWorkWithSuggestions.cs /} + +| Parameter | Type | Description | +|-----------------|-------------------------------|---------------------------------------------------------| +| __fieldName__ | `string` | The index field in which to search for similar terms | +| __path__ | `Expression>` | 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__: + +{CODE syntax_3@ClientApi\Session\Querying\HowToWorkWithSuggestions.cs /} + +| Option | Type | Description | +|--------------|-----------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------| +| __PageSize__ | `int` | | +| __Distance__ | `StringDistanceTypes` | | +| __Accuracy__ | `float?` | | +| __SortMode__ | `SuggestionSortMode` | | + +{PANEL/} + +## Related Articles + +### Session + +- [How to Query](../../../client-api/session/querying/how-to-query) + +### Indexes + +- [Query for suggestions with index](../../../indexes/querying/suggestions) diff --git a/Documentation/5.2/Raven.Documentation.Pages/client-api/session/querying/how-to-work-with-suggestions.java.markdown b/Documentation/5.2/Raven.Documentation.Pages/client-api/session/querying/how-to-work-with-suggestions.java.markdown new file mode 100644 index 0000000000..a6072b8f4b --- /dev/null +++ b/Documentation/5.2/Raven.Documentation.Pages/client-api/session/querying/how-to-work-with-suggestions.java.markdown @@ -0,0 +1,64 @@ +# Query for Suggestions + +The `suggestion` feature is available through query extension methods. It gives you the ability to find word similarities using string distance algorithms. + +## Syntax + +{CODE:java suggest_1@ClientApi\Session\Querying\HowToWorkWithSuggestions.java /} + +| Parameters | | | +| ------------- | ------------- | ----- | +| **suggestion** | `SuggestionBase` | Defines the type of suggestion that should be executed | +| **builder** | `Consumer>` | Builder with a fluent API that constructs a `SuggestionBase` instance | + +### Builder + +{CODE:java suggest_2@ClientApi\Session\Querying\HowToWorkWithSuggestions.java /} + +| Parameters | | | +| ------------- | ------------- | ----- | +| **fieldName** | String | Points to the index field that should be used for operation | +| **term** | String | Term that will be used as a basis of the suggestions | +| **terms** | String[] | Terms that will be used as a basis of the suggestions | +| **options** | `SuggestionOptions` | Non-default options that should be used for operation | + +### Options + +{CODE:java suggest_7@ClientApi\Session\Querying\HowToWorkWithSuggestions.java /} + +| Options | | | +| ------------- | ------------- | ----- | +| **pageSize** | int | Maximum number of suggestions that will be returned | +| **distance** | `StringDistanceTypes` | String distance algorithm to use (`NONE`, `LEVENSTEIN`, `JARO_WINKLER`, `N_GRAM`) | +| **accuracy** | Float | Suggestion accuracy | +| **sortMode** | `SuggestionSortMode` | Indicates in what order the results should be returned (`None`, `Popularity`) | + +## Example I + +{CODE-TABS} +{CODE-TAB:java:Java suggest_5@ClientApi\Session\Querying\HowToWorkWithSuggestions.java /} +{CODE-TAB-BLOCK:sql:RQL} +from index 'Employees/ByFullName' +select suggest('FullName', 'johne', '{ "Accuracy" : 0.4, "PageSize" : 5, "Distance" : "JaroWinkler", "SortMode" : "Popularity" }') +{CODE-TAB-BLOCK/} +{CODE-TABS/} + +## Example II + +{CODE-TABS} +{CODE-TAB:java:Java suggest_8@ClientApi\Session\Querying\HowToWorkWithSuggestions.java /} +{CODE-TAB-BLOCK:sql:RQL} +from index 'Employees/ByFullName' +select suggest('FullName', 'johne') +{CODE-TAB-BLOCK/} +{CODE-TABS/} + +## Related Articles + +### Session + +- [How to Query](../../../client-api/session/querying/how-to-query) + +### Indexes + +- [Query for suggestions with index](../../../indexes/querying/suggestions) diff --git a/Documentation/5.2/Raven.Documentation.Pages/client-api/session/querying/how-to-work-with-suggestions.js.markdown b/Documentation/5.2/Raven.Documentation.Pages/client-api/session/querying/how-to-work-with-suggestions.js.markdown new file mode 100644 index 0000000000..8f1e0a5fd5 --- /dev/null +++ b/Documentation/5.2/Raven.Documentation.Pages/client-api/session/querying/how-to-work-with-suggestions.js.markdown @@ -0,0 +1,205 @@ +# Query for Suggestions + +--- + +{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](../../../indexes/querying/suggestions). + +--- + +* In this page: + + * Overview: + * [What are terms](../../../client-api/session/querying/how-to-work-with-suggestions#what-are-terms) + * [When to use suggestions](../../../client-api/session/querying/how-to-work-with-suggestions#when-to-use-suggestions) + + * Examples: + * [Suggest terms - for single term](../../../client-api/session/querying/how-to-work-with-suggestions#suggest-terms---for-single-term) + * [Suggest terms - for multiple terms](../../../client-api/session/querying/how-to-work-with-suggestions#suggest-terms---for-multiple-terms) + * [Suggest terms - for multiple fields](../../../client-api/session/querying/how-to-work-with-suggestions#suggest-terms---for-multiple-fields) + * [Suggest terms - customize options and display name](../../../client-api/session/querying/how-to-work-with-suggestions#suggest-terms---customize-options-and-display-name) + + * [The auto-index terms in Studio](../../../client-api/session/querying/how-to-work-with-suggestions#the-auto-index-terms-in-studio) + * [Syntax](../../../client-api/session/querying/how-to-work-with-suggestions#syntax) + +{NOTE/} + +--- + +{PANEL: What are terms} + +* All queries in RavenDB use an index - learn more about that [here](../../../client-api/session/querying/how-to-query#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](../../../indexes/using-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 field `Name`. + The generated terms are visible in the Studio - see image [below](../../../client-api/session/querying/how-to-work-with-suggestions#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:. + +{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`: + +![Figure 1. Auto-index terms](images/auto-index-terms.png "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. + +{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` |
  • Maximum number of suggested terms that will be returned
  • Default is 15
| +| __distance__ | `string` |
  • String distance algorithm to use
  • `None` / `Levenshtein` / `JaroWinkler` / `NGram`
  • Default is Levenshtein
| +| __accuracy__ | `number ` |
  • Suggestion accuracy
  • Default is 0.5
| +| __sortMode__ | `string` |
  • Indicates the order by which results are returned
  • `None` / `Popularity`
  • Default is Popularity
| + +{PANEL/} + +## Related Articles + +### Session + +- [How to Query](../../../client-api/session/querying/how-to-query) + +### Indexes + +- [Query for suggestions with index](../../../indexes/querying/suggestions) diff --git a/Documentation/5.2/Raven.Documentation.Pages/client-api/session/querying/images/auto-index-terms.png b/Documentation/5.2/Raven.Documentation.Pages/client-api/session/querying/images/auto-index-terms.png new file mode 100644 index 0000000000..21d961f3ec Binary files /dev/null and b/Documentation/5.2/Raven.Documentation.Pages/client-api/session/querying/images/auto-index-terms.png differ diff --git a/Documentation/5.2/Raven.Documentation.Pages/indexes/querying/images/index-terms.png b/Documentation/5.2/Raven.Documentation.Pages/indexes/querying/images/index-terms.png new file mode 100644 index 0000000000..edfffd7ea8 Binary files /dev/null and b/Documentation/5.2/Raven.Documentation.Pages/indexes/querying/images/index-terms.png differ diff --git a/Documentation/5.2/Raven.Documentation.Pages/indexes/querying/suggestions.dotnet.markdown b/Documentation/5.2/Raven.Documentation.Pages/indexes/querying/suggestions.dotnet.markdown new file mode 100644 index 0000000000..bf2d7620cc --- /dev/null +++ b/Documentation/5.2/Raven.Documentation.Pages/indexes/querying/suggestions.dotnet.markdown @@ -0,0 +1,160 @@ +# Query for suggestions with index + +--- + +{NOTE: } + +* Prior to this article, please refer to article [Query for Suggestions](../../client-api/session/querying/how-to-work-with-suggestions) + for general knowledge about Suggestions, and for dynamic-queries examples. + +* In addition to getting suggested terms when making a dynamic-query, + you can query for similar terms when querying an index. + +* This article provides examples of querying an index for suggestions. + Find the Suggestions API methods listed [here](../../client-api/session/querying/how-to-work-with-suggestions#syntax). + +* In this page: + + * [Configure the index for suggestions](../../indexes/querying/suggestions#configure-the-index-for-suggestions) + * [The index terms](../../indexes/querying/suggestions#the-index-terms) + * [Suggest terms - for single term](../../indexes/querying/suggestions#suggest-terms---for-single-term) + * [Suggest terms - for multiple terms](../..//indexes/querying/suggestions#suggest-terms---for-multiple-terms) + * [Suggest terms - for multiple fields](../..//indexes/querying/suggestions#suggest-terms---for-multiple-fields) + * [Suggest terms - customize options and display name](../..//indexes/querying/suggestions#suggest-terms---customize-options-and-display-name) + +{NOTE/} + +--- + +{PANEL: 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). + +{CODE suggestions_index_1@Indexes\Querying\Suggestions.cs /} + +{NOTE: } + +__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. + +{NOTE/} + +{PANEL/} + +{PANEL: The index terms} + +Based on the Northwind sample data, +these are the terms generated for the above index `Products/ByName`: + +![Figure 1. Index terms](images/index-terms.png "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](../../indexes/using-analyzers#ravendb) since full-text search was set on this field. + +{PANEL/} + +{PANEL: 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`. + +{CODE suggestions_2@Indexes\Querying\Suggestions.cs /} + +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: + +{CODE-TABS} +{CODE-TAB:csharp:Query suggestions_3@Indexes\Querying\Suggestions.cs /} +{CODE-TAB:csharp:Query_async suggestions_4@Indexes\Querying\Suggestions.cs /} +{CODE-TAB:csharp:Query_overload suggestions_5@Indexes\Querying\Suggestions.cs /} +{CODE-TAB:csharp:DocumentQuery suggestions_6@Indexes\Querying\Suggestions.cs /} +{CODE-TAB-BLOCK:sql:RQL} +// Query for terms from index-field 'ProductName' that are similar to 'chokolade' +from index "Products/ByName" +select suggest(ProductName, "chokolade") +{CODE-TAB-BLOCK/} +{CODE-TABS/} + +{CODE suggestions_7@Indexes\Querying\Suggestions.cs /} + +{PANEL/} + +{PANEL: Suggest terms - for multiple terms} + +{CODE-TABS} +{CODE-TAB:csharp:Query suggestions_8@Indexes\Querying\Suggestions.cs /} +{CODE-TAB:csharp:Query_async suggestions_9@Indexes\Querying\Suggestions.cs /} +{CODE-TAB:csharp:Query_overload suggestions_10@Indexes\Querying\Suggestions.cs /} +{CODE-TAB:csharp:DocumentQuery suggestions_11@Indexes\Querying\Suggestions.cs /} +{CODE-TAB-BLOCK:sql:RQL} +// 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"] } +{CODE-TAB-BLOCK/} +{CODE-TABS/} + +{CODE suggestions_12@Indexes\Querying\Suggestions.cs /} + +{PANEL/} + +{PANEL: Suggest terms - for multiple fields} + +{CODE-TABS} +{CODE-TAB:csharp:Query suggestions_13@Indexes\Querying\Suggestions.cs /} +{CODE-TAB:csharp:Query_async suggestions_14@Indexes\Querying\Suggestions.cs /} +{CODE-TAB:csharp:Query_overload suggestions_15@Indexes\Querying\Suggestions.cs /} +{CODE-TAB:csharp:DocumentQuery suggestions_16@Indexes\Querying\Suggestions.cs /} +{CODE-TAB:csharp:The_index suggestions_index_2@Indexes\Querying\Suggestions.cs /} +{CODE-TAB-BLOCK:sql:RQL} +// Query for suggested terms +// from index-field 'CompanyName' AND from index-field 'ContactName' +from index "Companies/ByNameAndByContactName" +select suggest(CompanyName, "chese"), suggest(ContactName, "frank") +{CODE-TAB-BLOCK/} +{CODE-TABS/} + +{CODE suggestions_17@Indexes\Querying\Suggestions.cs /} + +{PANEL/} + +{PANEL: Suggest terms - customize options and display name} + +{CODE-TABS} +{CODE-TAB:csharp:Query suggestions_18@Indexes\Querying\Suggestions.cs /} +{CODE-TAB:csharp:Query_async suggestions_19@Indexes\Querying\Suggestions.cs /} +{CODE-TAB:csharp:Query_overload suggestions_20@Indexes\Querying\Suggestions.cs /} +{CODE-TAB:csharp:DocumentQuery suggestions_21@Indexes\Querying\Suggestions.cs /} +{CODE-TAB-BLOCK:sql:RQL} +// 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" +{CODE-TAB-BLOCK/} +{CODE-TABS/} + +{CODE suggestions_22@Indexes\Querying\Suggestions.cs /} + +{PANEL/} + +## Related Articles + +### Client API + +- [Query for Suggestions](../../client-api/session/querying/how-to-work-with-suggestions) diff --git a/Documentation/5.2/Raven.Documentation.Pages/indexes/querying/suggestions.java.markdown b/Documentation/5.2/Raven.Documentation.Pages/indexes/querying/suggestions.java.markdown new file mode 100644 index 0000000000..e36e2ed685 --- /dev/null +++ b/Documentation/5.2/Raven.Documentation.Pages/indexes/querying/suggestions.java.markdown @@ -0,0 +1,60 @@ +# Query for suggestions with index + +RavenDB has an indexing mechanism built upon the Lucene engine which has a great suggestions feature. This capability allows a significant improvement of search functionalities enhancing the overall user experience of the application. + +Let's consider an example where the users have the option to look for products by their name. The index and query would appear as follows: + +{CODE:java suggestions_1@Indexes\Querying\Suggestions.java /} + +{CODE:java suggestions_2@Indexes\Querying\Suggestions.java /} + +If our database has `Northwind` samples deployed then it will not return any results. However, we can ask RavenDB for help: + +{CODE-TABS} +{CODE-TAB:java:Query suggestions_3@Indexes\Querying\Suggestions.java /} +{CODE-TAB-BLOCK:sql:RQL} +from index 'Products/ByName' +select suggest('Name', 'chaig') +{CODE-TAB-BLOCK/} +{CODE-TABS/} + +It will produce these suggestions: + + Did you mean? + chang + chai + +{NOTE:Client API} + +You can read more about suggestions in our [Client API](../../client-api/session/querying/how-to-work-with-suggestions) article. + +{NOTE/} + +## Suggest Over Multiple Words + +RavenDB allows you to perform a suggestion query over multiple words. + +{CODE:java query_suggestion_over_multiple_words@Indexes\Querying\Suggestions.java /} + +This will produce the following results: + + Did you mean? + chai + chang + chartreuse + chef + tofu + +## Remarks + +{WARNING: Increased indexing time} + +Indexes with turned on suggestions tend to use a lot more CPU power than other indexes. This can impact indexing speed (querying is not impacted). + +{WARNING/} + +## Related Articles + +### Client API + +- [Query for Suggestions](../../client-api/session/querying/how-to-work-with-suggestions) diff --git a/Documentation/5.2/Raven.Documentation.Pages/indexes/querying/suggestions.js.markdown b/Documentation/5.2/Raven.Documentation.Pages/indexes/querying/suggestions.js.markdown new file mode 100644 index 0000000000..23de769efc --- /dev/null +++ b/Documentation/5.2/Raven.Documentation.Pages/indexes/querying/suggestions.js.markdown @@ -0,0 +1,148 @@ +# Query for suggestions with index + +--- + +{NOTE: } + +* Prior to this article, please refer to article [Query for Suggestions](../../client-api/session/querying/how-to-work-with-suggestions) + for general knowledge about Suggestions, and for dynamic-queries examples. + +* In addition to getting suggested terms when making a dynamic-query, + you can query for similar terms when querying an index. + +* This article provides examples of querying an index for suggestions. + Find the Suggestions API methods listed [here](../../client-api/session/querying/how-to-work-with-suggestions#syntax). + +* In this page: + + * [Configure the index for suggestions](../../indexes/querying/suggestions#configure-the-index-for-suggestions) + * [The index terms](../../indexes/querying/suggestions#the-index-terms) + * [Suggest terms - for single term](../../indexes/querying/suggestions#suggest-terms---for-single-term) + * [Suggest terms - for multiple terms](../..//indexes/querying/suggestions#suggest-terms---for-multiple-terms) + * [Suggest terms - for multiple fields](../..//indexes/querying/suggestions#suggest-terms---for-multiple-fields) + * [Suggest terms - customize options and display name](../..//indexes/querying/suggestions#suggest-terms---customize-options-and-display-name) + +{NOTE/} + +--- + +{PANEL: 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). + +{CODE:nodejs suggestions_index_1@Indexes\Querying\suggestions.js /} + +{NOTE: } + +__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. + +{NOTE/} + +{PANEL/} + +{PANEL: The index terms} + +Based on the __Northwind sample data__, +these are the terms generated for the above index `Products/ByName`: + +![Figure 1. Index terms](images/index-terms.png "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](../../indexes/using-analyzers#ravendb) since full-text search was set on this field. + +{PANEL/} + +{PANEL: 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`. + +{CODE:nodejs suggestions_2@Indexes\Querying\suggestions.js /} + +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: + +{CODE-TABS} +{CODE-TAB:nodejs:Query suggestions_3@Indexes\Querying\suggestions.js /} +{CODE-TAB-BLOCK:sql:RQL} +// Query for terms from index-field 'ProductName' that are similar to 'chokolade' +from index "Products/ByName" +select suggest(ProductName, "chokolade") +{CODE-TAB-BLOCK/} +{CODE-TABS/} + +{CODE:nodejs suggestions_4@Indexes\Querying\suggestions.js /} + +{PANEL/} + +{PANEL: Suggest terms - for multiple terms} + +{CODE-TABS} +{CODE-TAB:nodejs:Query suggestions_5@Indexes\Querying\suggestions.js /} +{CODE-TAB-BLOCK:sql:RQL} +// 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"] } +{CODE-TAB-BLOCK/} +{CODE-TABS/} + +{CODE:nodejs suggestions_6@Indexes\Querying\suggestions.js /} + +{PANEL/} + +{PANEL: Suggest terms - for multiple fields} + +{CODE-TABS} +{CODE-TAB:nodejs:Query suggestions_7@Indexes\Querying\suggestions.js /} +{CODE-TAB:nodejs:The_index suggestions_index_2@Indexes\Querying\suggestions.js /} +{CODE-TAB-BLOCK:sql:RQL} +// Query for suggested terms +// from index-field 'CompanyName' AND from index-field 'ContactName' +from index "Companies/ByNameAndByContactName" +select suggest(CompanyName, "chese"), suggest(ContactName, "frank") +{CODE-TAB-BLOCK/} +{CODE-TABS/} + +{CODE:nodejs suggestions_8@Indexes\Querying\suggestions.js /} + +{PANEL/} + +{PANEL: Suggest terms - customize options and display name} + +{CODE-TABS} +{CODE-TAB:nodejs:Query suggestions_9@Indexes\Querying\suggestions.js /} +{CODE-TAB-BLOCK:sql:RQL} +// 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" +{CODE-TAB-BLOCK/} +{CODE-TABS/} + +{CODE:nodejs suggestions_10@Indexes\Querying\suggestions.js /} + +{PANEL/} + +## Related Articles + +### Client API + +- [Query for Suggestions](../../client-api/session/querying/how-to-work-with-suggestions) diff --git a/Documentation/5.2/Samples/csharp/Raven.Documentation.Samples/ClientApi/Session/Querying/HowToWorkWithSuggestions.cs b/Documentation/5.2/Samples/csharp/Raven.Documentation.Samples/ClientApi/Session/Querying/HowToWorkWithSuggestions.cs new file mode 100644 index 0000000000..99196b13f5 --- /dev/null +++ b/Documentation/5.2/Samples/csharp/Raven.Documentation.Samples/ClientApi/Session/Querying/HowToWorkWithSuggestions.cs @@ -0,0 +1,459 @@ +using System; +using System.Collections.Generic; +using System.Linq; +using System.Linq.Expressions; +using System.Threading.Tasks; +using Raven.Client.Documents; +using Raven.Client.Documents.Indexes; +using Raven.Client.Documents.Queries.Suggestions; +using Raven.Documentation.Samples.Orders; + +namespace Raven.Documentation.Samples.ClientApi.Session.Querying +{ + public class HowToWorkWithSuggestions + { + public async Task Sample() + { + using (var store = new DocumentStore()) + { + using (var session = store.OpenSession()) + { + #region suggest_1 + // This dynamic query on the 'Products' collection has NO resulting documents + List products = session + .Query() + .Where(x => x.Name == "chaig") + .ToList(); + #endregion + } + + using (var session = store.OpenSession()) + { + #region suggest_2 + // Query for suggested terms for single term: + // ========================================== + + Dictionary suggestions = session + // Make a dynamic query on collection 'Products' + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from field 'Name' that are similar to 'chaig' + .ByField(x => x.Name, "chaig")) + .Execute(); + #endregion + } + + using (var asyncSession = store.OpenAsyncSession()) + { + #region suggest_3 + // Query for suggested terms for single term: + // ========================================== + + Dictionary suggestions = await asyncSession + // Make a dynamic query on collection 'Products' + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from field 'Name' that are similar to 'chaig' + .ByField(x => x.Name, "chaig")) + .ExecuteAsync(); + #endregion + } + + using (var session = store.OpenSession()) + { + #region suggest_4 + // 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 suggestions = session + .Query() + // Call 'SuggestUsing' - pass the suggestion request + .SuggestUsing(suggestionRequest) + .Execute(); + #endregion + } + + using (var session = store.OpenSession()) + { + #region suggest_5 + // Query for suggested terms for single term: + // ========================================== + + Dictionary suggestions = session.Advanced + // Make a dynamic document-query on collection 'Products' + .DocumentQuery() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from field 'Name' that are similar to 'chaig' + .ByField(x => x.Name, "chaig")) + .Execute(); + #endregion + + #region suggest_6 + // 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 + #endregion + } + + using (var session = store.OpenSession()) + { + #region suggest_7 + // Query for suggested terms for multiple terms: + // ============================================= + + Dictionary suggestions = session + // Make a dynamic query on collection 'Products' + .Query() + // 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(); + #endregion + } + + using (var asyncSession = store.OpenAsyncSession()) + { + #region suggest_8 + // Query for suggested terms for multiple terms: + // ============================================= + + Dictionary suggestions = await asyncSession + // Make a dynamic query on collection 'Products' + .Query() + // 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(); + #endregion + } + + using (var session = store.OpenSession()) + { + #region suggest_9 + // 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 suggestions = session + .Query() + // Call 'SuggestUsing' - pass the suggestion request + .SuggestUsing(suggestionRequest) + .Execute(); + #endregion + } + + using (var session = store.OpenSession()) + { + #region suggest_10 + // Query for suggested terms for multiple terms: + // ============================================= + + Dictionary suggestions = session.Advanced + // Make a dynamic document-query on collection 'Products' + .DocumentQuery() + // 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(); + #endregion + + #region suggest_11 + // The resulting suggested terms: + // ============================== + + // Suggested terms in field 'Name' that are similar to 'chaig' OR to 'tof': + // chai + // chang + // tofu + #endregion + } + + using (var session = store.OpenSession()) + { + #region suggest_12 + // Query for suggested terms in multiple fields: + // ============================================= + + Dictionary suggestions = session + // Make a dynamic query on collection 'Companies' + .Query() + // 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(); + #endregion + } + + using (var asyncSession = store.OpenAsyncSession()) + { + #region suggest_13 + // Query for suggested terms in multiple fields: + // ============================================= + + Dictionary suggestions = await asyncSession + // Make a dynamic query on collection 'Companies' + .Query() + // 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(); + #endregion + } + + using (var session = store.OpenSession()) + { + #region suggest_14 + // 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 suggestions = session + .Query() + // 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(); + #endregion + } + + using (var session = store.OpenSession()) + { + #region suggest_15 + // Query for suggested terms in multiple fields: + // ============================================= + + Dictionary suggestions = session.Advanced + // Make a dynamic document-query on collection 'Companies' + .DocumentQuery() + // 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(); + #endregion + + #region suggest_16 + // 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 + #endregion + } + + using (var session = store.OpenSession()) + { + #region suggest_17 + // Query for suggested terms - customize options and display name: + // =============================================================== + + Dictionary suggestions = session + // Make a dynamic query on collection 'Products' + .Query() + // 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(); + #endregion + } + + using (var asyncSession = store.OpenAsyncSession()) + { + #region suggest_18 + // Query for suggested terms - customize options and display name: + // =============================================================== + + Dictionary suggestions = await asyncSession + // Make a dynamic query on collection 'Products' + .Query() + // 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(); + #endregion + } + + using (var session = store.OpenSession()) + { + #region suggest_19 + // 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 suggestions = session + .Query() + // Call 'SuggestUsing' - pass the suggestion request + .SuggestUsing(suggestionRequest) + .Execute(); + #endregion + } + + using (var session = store.OpenSession()) + { + #region suggest_20 + // Query for suggested terms - customize options and display name: + // =============================================================== + + Dictionary suggestions = session.Advanced + // Make a dynamic query on collection 'Products' + .DocumentQuery() + // 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(); + #endregion + + #region suggest_21 + // 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 + #endregion + } + } + } + + private interface IFoo + { + #region syntax_1 + // Overloads for requesting suggestions for term(s) in a field: + ISuggestionQuery SuggestUsing(SuggestionBase suggestion); + ISuggestionQuery SuggestUsing(Action> builder); + + // Overloads requesting suggestions for term(s) in another field in the same query: + ISuggestionQuery AndSuggestUsing(SuggestionBase suggestion); + ISuggestionQuery AndSuggestUsing(Action> builder); + #endregion + + #region syntax_2 + ISuggestionOperations ByField(string fieldName, string term); + ISuggestionOperations ByField(string fieldName, string[] terms); + ISuggestionOperations ByField(Expression> path, string term); + ISuggestionOperations ByField(Expression> path, string[] terms); + + ISuggestionOperations WithDisplayName(string displayName); + ISuggestionOperations WithOptions(SuggestionOptions options); + #endregion + } + + private class Foo + { + #region syntax_3 + public int PageSize { get; set; } + public StringDistanceTypes? Distance { get; set; } + public float? Accuracy { get; set; } + public SuggestionSortMode SortMode { get; set; } + #endregion + } + } +} diff --git a/Documentation/5.2/Samples/csharp/Raven.Documentation.Samples/Indexes/Querying/Suggestions.cs b/Documentation/5.2/Samples/csharp/Raven.Documentation.Samples/Indexes/Querying/Suggestions.cs new file mode 100644 index 0000000000..06064e3355 --- /dev/null +++ b/Documentation/5.2/Samples/csharp/Raven.Documentation.Samples/Indexes/Querying/Suggestions.cs @@ -0,0 +1,492 @@ +using System; +using System.Collections.Generic; +using System.Linq; +using System.Threading.Tasks; +using Raven.Client.Documents; +using Raven.Client.Documents.Indexes; +using Raven.Client.Documents.Queries.Suggestions; +using Raven.Documentation.Samples.Orders; + +namespace Raven.Documentation.Samples.Indexes.Querying +{ + public class Suggestions + { + #region suggestions_index_1 + public class Products_ByName : AbstractIndexCreationTask + { + // 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); + } + } + #endregion + + #region suggestions_index_2 + public class Companies_ByNameAndByContactName : + AbstractIndexCreationTask + { + // 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); + } + } + #endregion + + public async Task Samples() + { + using (var store = new DocumentStore()) + { + using (var session = store.OpenSession()) + { + #region suggestions_2 + + // This query on index 'Products/ByName' has NO resulting documents + List products = session + .Query() + .Search(x => x.ProductName, "chokolade") + .OfType() + .ToList(); + #endregion + } + + using (var session = store.OpenSession()) + { + #region suggestions_3 + // Query the index for suggested terms for single term: + // ==================================================== + + Dictionary suggestions = session + // Query the index + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' + .ByField(x => x.ProductName, "chokolade")) + .Execute(); + #endregion + } + + using (var asyncSession = store.OpenAsyncSession()) + { + #region suggestions_4 + // Query the index for suggested terms for single term: + // ==================================================== + + Dictionary suggestions = await asyncSession + // Query the index + .Query() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' + .ByField(x => x.ProductName, "chokolade")) + .ExecuteAsync(); + #endregion + } + + using (var session = store.OpenSession()) + { + #region suggestions_5 + // 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 suggestions = session + .Query() + // Call 'SuggestUsing' - pass the suggestion request + .SuggestUsing(suggestionRequest) + .Execute(); + #endregion + } + + using (var session = store.OpenSession()) + { + #region suggestions_6 + // Query the index for suggested terms for single term: + // ==================================================== + + Dictionary suggestions = session.Advanced + // Query the index + .DocumentQuery() + // Call 'SuggestUsing' + .SuggestUsing(builder => builder + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' + .ByField(x => x.ProductName, "chokolade")) + .Execute(); + #endregion + + #region suggestions_7 + // 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 + #endregion + } + + using (var session = store.OpenSession()) + { + #region suggestions_8 + // Query the index for suggested terms for multiple terms: + // ======================================================= + + Dictionary suggestions = session + // Query the index + .Query() + // 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(); + #endregion + } + + using (var asyncSession = store.OpenAsyncSession()) + { + #region suggestions_9 + // Query the index for suggested terms for multiple terms: + // ======================================================= + + Dictionary suggestions = await asyncSession + // Query the index + .Query() + // 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(); + #endregion + } + + using (var session = store.OpenSession()) + { + #region suggestions_10 + // 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 suggestions = session + .Query() + // Call 'SuggestUsing' - pass the suggestion request + .SuggestUsing(suggestionRequest) + .Execute(); + #endregion + } + + using (var session = store.OpenSession()) + { + #region suggestions_11 + // Query the index for suggested terms for multiple terms: + // ======================================================= + + Dictionary suggestions = session.Advanced + // Query the index + .DocumentQuery() + // 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(); + #endregion + + #region suggestions_12 + // The resulting suggested terms: + // ============================== + + // Suggested terms in index-field 'ProductName' that are similar to 'chokolade' OR to 'syrop': + // schokolade + // chocolade + // chocolate + // sirop + // syrup + #endregion + } + + using (var session = store.OpenSession()) + { + #region suggestions_13 + // Query the index for suggested terms in multiple fields: + // ======================================================= + + Dictionary suggestions = session + // Query the index + .Query() + // 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(); + #endregion + } + + using (var asyncSession = store.OpenAsyncSession()) + { + #region suggestions_14 + // Query the index for suggested terms in multiple fields: + // ======================================================= + + Dictionary suggestions = await asyncSession + // Query the index + .Query() + // 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(); + #endregion + } + + using (var session = store.OpenSession()) + { + #region suggestions_15 + // 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 suggestions = session + .Query() + // 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(); + #endregion + } + + using (var session = store.OpenSession()) + { + #region suggestions_16 + // Query the index for suggested terms in multiple fields: + // ======================================================= + + Dictionary suggestions = session.Advanced + // Query the index + .DocumentQuery() + // 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(); + #endregion + + #region suggestions_17 + // 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 + #endregion + } + + using (var session = store.OpenSession()) + { + #region suggestions_18 + // Query the index for suggested terms - customize options and display name: + // ========================================================================= + + Dictionary suggestions = session + // Query the index + .Query() + // 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(); + #endregion + } + + using (var asyncSession = store.OpenAsyncSession()) + { + #region suggestions_19 + // Query the index for suggested terms - customize options and display name: + // ========================================================================= + + Dictionary suggestions = await asyncSession + // Query the index + .Query() + // 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(); + #endregion + } + + using (var session = store.OpenSession()) + { + #region suggestions_20 + // 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 suggestions = session + .Query() + // Call 'SuggestUsing' - pass the suggestion request + .SuggestUsing(suggestionRequest) + .Execute(); + #endregion + } + + using (var session = store.OpenSession()) + { + #region suggestions_21 + // Query the index for suggested terms - customize options and display name: + // ========================================================================= + + Dictionary suggestions = session.Advanced + // Query the index + .DocumentQuery() + // 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(); + #endregion + + #region suggestions_22 + // 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 + #endregion + } + } + } + } +} diff --git a/Documentation/5.2/Samples/java/src/test/java/net/ravendb/ClientApi/Session/Querying/HowToWorkWithSuggestions.java b/Documentation/5.2/Samples/java/src/test/java/net/ravendb/ClientApi/Session/Querying/HowToWorkWithSuggestions.java new file mode 100644 index 0000000000..da8be86efe --- /dev/null +++ b/Documentation/5.2/Samples/java/src/test/java/net/ravendb/ClientApi/Session/Querying/HowToWorkWithSuggestions.java @@ -0,0 +1,85 @@ +package net.ravendb.ClientApi.Session.Querying; + +import net.ravendb.client.documents.DocumentStore; +import net.ravendb.client.documents.IDocumentStore; +import net.ravendb.client.documents.indexes.AbstractIndexCreationTask; +import net.ravendb.client.documents.queries.suggestions.*; +import net.ravendb.client.documents.session.IDocumentSession; + +import java.util.Map; +import java.util.function.Consumer; + +public class HowToWorkWithSuggestions { + + private class Foo { + + //region suggest_7 + private int pageSize = 15; + + private StringDistanceTypes distance = StringDistanceTypes.LEVENSHTEIN; + + private Float accuracy = 0.5f; + + private SuggestionSortMode sortMode = SuggestionSortMode.POPULARITY; + + // getters and setters for fields listed above + //endregion + } + + private interface IFoo { + //region suggest_1 + ISuggestionDocumentQuery suggestUsing(SuggestionBase suggestion); + + ISuggestionDocumentQuery suggestUsing(Consumer> builder); + //endregion + + //region suggest_2 + ISuggestionOperations byField(String fieldName, String term); + + ISuggestionOperations byField(String fieldName, String[] terms); + + ISuggestionOperations withOptions(SuggestionOptions options); + //endregion + } + + private static class Employees_ByFullName extends AbstractIndexCreationTask { + + } + + private static class Employee { + + } + + public void sample() { + try (IDocumentStore store = new DocumentStore()) { + try (IDocumentSession session = store.openSession()) { + //region suggest_5 + SuggestionOptions options = new SuggestionOptions(); + options.setAccuracy(0.4f); + options.setPageSize(5); + options.setDistance(StringDistanceTypes.JARO_WINKLER); + options.setSortMode(SuggestionSortMode.POPULARITY); + + Map suggestions = session + .query(Employee.class, Employees_ByFullName.class) + .suggestUsing(builder -> + builder.byField("FullName", "johne") + .withOptions(options)) + .execute(); + //endregion + } + + try (IDocumentSession session = store.openSession()) { + //region suggest_8 + SuggestionWithTerm suggestionWithTerm = new SuggestionWithTerm("FullName"); + suggestionWithTerm.setTerm("johne"); + + Map suggestions = session + .query(Employee.class, Employees_ByFullName.class) + .suggestUsing(suggestionWithTerm) + .execute(); + //endregion + } + } + } +} diff --git a/Documentation/5.2/Samples/java/src/test/java/net/ravendb/Indexes/Querying/Suggestions.java b/Documentation/5.2/Samples/java/src/test/java/net/ravendb/Indexes/Querying/Suggestions.java new file mode 100644 index 0000000000..8fc55178b7 --- /dev/null +++ b/Documentation/5.2/Samples/java/src/test/java/net/ravendb/Indexes/Querying/Suggestions.java @@ -0,0 +1,88 @@ +package net.ravendb.Indexes.Querying; + +import net.ravendb.client.documents.DocumentStore; +import net.ravendb.client.documents.IDocumentStore; +import net.ravendb.client.documents.indexes.AbstractIndexCreationTask; +import net.ravendb.client.documents.indexes.FieldIndexing; +import net.ravendb.client.documents.queries.suggestions.StringDistanceTypes; +import net.ravendb.client.documents.queries.suggestions.SuggestionOptions; +import net.ravendb.client.documents.queries.suggestions.SuggestionResult; +import net.ravendb.client.documents.queries.suggestions.SuggestionSortMode; +import net.ravendb.client.documents.session.IDocumentSession; + +import java.util.Map; + +public class Suggestions { + + //region suggestions_1 + public class Products_ByName extends AbstractIndexCreationTask { + public Products_ByName() { + map = "from product in docs.Products " + + "select new " + + "{ " + + " product.Name " + + "} "; + + index("Name", FieldIndexing.SEARCH); // (optional) splitting name into multiple tokens + suggestion("Name");// configuring suggestions + } + } + //endregion + + private class Product { + + } + + public Suggestions() { + try (IDocumentStore store = new DocumentStore()) { + try (IDocumentSession session = store.openSession()) { + //region suggestions_2 + Product product = session + .query(Product.class, Products_ByName.class) + .search("Name", "chaig") + .firstOrDefault(); + //endregion + } + + try (IDocumentSession session = store.openSession()) { + //region suggestions_3 + Map suggestionResult = session + .query(Product.class, Products_ByName.class) + .suggestUsing(builder -> builder.byField("Name", "chaig")) + .execute(); + + System.out.println("Did you mean?"); + + for (String suggestion : suggestionResult.get("Name").getSuggestions()) { + System.out.println("\t" + suggestion); + } + //endregion + } + } + + try (IDocumentStore store = new DocumentStore()) { + try (IDocumentSession session = store.openSession()) { + //region query_suggestion_over_multiple_words + SuggestionOptions options = new SuggestionOptions(); + options.setAccuracy(0.4f); + options.setPageSize(5); + options.setDistance(StringDistanceTypes.JARO_WINKLER); + options.setSortMode(SuggestionSortMode.POPULARITY); + + Map resultsByMultipleWords = session + .query(Product.class, Products_ByName.class) + .suggestUsing(builder -> + builder.byField("Name", new String[]{"chaig", "tof"}) + .withOptions(options)) + .execute(); + + System.out.println("Did you mean?"); + + for (String suggestion : resultsByMultipleWords.get("Name").getSuggestions()) { + System.out.println("\t" + suggestion); + } + //endregion + } + } + } +} diff --git a/Documentation/5.2/Samples/nodejs/ClientApi/Session/Querying/workWithSuggestions.js b/Documentation/5.2/Samples/nodejs/ClientApi/Session/Querying/workWithSuggestions.js new file mode 100644 index 0000000000..5dd67c9c17 --- /dev/null +++ b/Documentation/5.2/Samples/nodejs/ClientApi/Session/Querying/workWithSuggestions.js @@ -0,0 +1,178 @@ +import { DocumentStore, AbstractIndexCreationTask } from "ravendb"; + +const documentStore = new DocumentStore(); +const session = documentStore.openSession(); + +async function suggestions() { + { + //region suggest_1 + // This dynamic query on the 'Products' collection has NO resulting documents + const products = await session + .query({ collection: "Products" }) + .where(x => x.Name == "chaig") + .all(); + //endregion + } + + { + //region suggest_2 + // 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(); + //endregion + } + + { + //region suggest_3 + // 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 + //endregion + } + + { + //region suggest_4 + // 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(); + //endregion + } + + { + //region suggest_5 + // The resulting suggested terms: + // ============================== + + // Suggested terms in field 'Name' that are similar to 'chaig' OR to 'tof': + // chai + // chang + // tofu + //endregion + } + + { + //region suggest_6 + // 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(); + //endregion + } + + { + //region suggest_7 + // 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 + //endregion + } + + { + //region suggest_8 + // 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(); + //endregion + } + + { + //region suggest_9 + // 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 + //endregion + } +} + +//region syntax +{ + { + //region syntax_1 + // Requesting suggestions for term(s) in a field: + suggestUsing(action); + + // Requesting suggestions for term(s) in another field in the same query: + andSuggestUsing(action); + //endregion + } + { + //region syntax_2 + byField(fieldName, term); + byField(fieldName, terms); + + withDisplayName(displayName); + withOptions(options); + //endregion + } +} +//endregion diff --git a/Documentation/5.2/Samples/nodejs/indexes/querying/suggestions.js b/Documentation/5.2/Samples/nodejs/indexes/querying/suggestions.js new file mode 100644 index 0000000000..f8f1b1a8e9 --- /dev/null +++ b/Documentation/5.2/Samples/nodejs/indexes/querying/suggestions.js @@ -0,0 +1,208 @@ +import { + DocumentStore, + AbstractIndexCreationTask, + QueryData +} from "ravendb"; + +const store = new DocumentStore(); +const session = store.openSession(); + +{ + //region suggestions_index_1 + class Products_ByName extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + this.map("Products", p => { + return { + ProductName: p.Name + }; + }); + + // Configure index-field 'ProductName' for suggestions + this.suggestion("ProductName"); + + // Optionally: set 'Search' on this field + // This will split the field content into multiple terms allowing for a full-text search + this.index("ProductName", "Search"); + } + } + //endregion + + //region suggestions_index_2 + class Companies_ByNameAndByContactName extends AbstractJavaScriptIndexCreationTask { + constructor() { + super(); + + this.map("Companies", p => { + return { + CompanyName: p.Name, + ContactName: p.Contact.Name + }; + }); + + // Configure the index-fields for suggestions + this.suggestion("CompanyName"); + this.suggestion("ContactName"); + + // Optionally: set 'Search' on the index-fields + // This will split the fields' content into multiple terms allowing for a full-text search + this.index("CompanyName", "Search"); + this.index("ContactName", "Search"); + } + } + //endregion + + async function suggestions() { + + { + //region suggestions_2 + // This query on index 'Products/ByName' has NO resulting documents + const products = await session + .query({ indexName: "Products/ByName" }) + .search("ProductName", "chokolade") + .all(); + //endregion + } + + { + //region suggestions_3 + // Query the index for suggested terms for single term: + // ==================================================== + + const suggestions = await session + // Query the index + .query({ indexName: "Products/ByName" }) + // Call 'suggestUsing' + .suggestUsing(x => x + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' + .byField("ProductName", "chokolade")) + .execute(); + //endregion + } + + { + //region suggestions_4 + // The resulting suggested terms: + // ============================== + + console.log("Suggested terms in index-field 'ProductName' that are similar to 'chokolade':"); + suggestions["ProductName"].suggestions.forEach(suggestedTerm => { + console.log("\t" + suggestedTerm); + }); + + // Suggested terms in index-field 'ProductName' that are similar to 'chokolade': + // schokolade + // chocolade + // chocolate + //endregion + } + + { + //region suggestions_5 + // Query the index for suggested terms for multiple terms: + // ======================================================= + + const suggestions = await session + // Query the index + .query({ indexName: "Products/ByName" }) + // Call 'suggestUsing' + .suggestUsing(x => x + // Request to get terms from index-field 'ProductName' that are similar to 'chokolade' OR 'syrop' + .byField("ProductName", ["chokolade", "syrop"])) + .execute(); + //endregion + } + + { + //region suggestions_6 + // The resulting suggested terms: + // ============================== + + // Suggested terms in index-field 'ProductName' that are similar to 'chokolade' OR to 'syrop': + // schokolade + // chocolade + // chocolate + // sirop + // syrup + //endregion + } + + { + //region suggestions_7 + // Query the index for suggested terms in multiple fields: + // ======================================================= + + const suggestions = await session + // Query the index + .query({ indexName: "Companies/ByNameAndByContactName" }) + // Call 'suggestUsing' to get suggestions for terms that are + // similar to 'chese' in first index-field (e.g. 'CompanyName') + .suggestUsing(x => x.byField("CompanyName", "chese")) + // Call 'andSuggestUsing' to get suggestions for terms that are + // similar to 'frank' in an additional index-field (e.g. 'ContactName') + .andSuggestUsing(x => x.byField("ContactName", "frank")) + .execute(); + //endregion + } + + { + //region suggestions_8 + // 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 + //endregion + } + + { + //region suggestions_9 + // Query the index for suggested terms - customize options and display name: + // ========================================================================= + + const suggestions = await session + // Query the index + .query({ indexName: "Products/ByName" }) + // Call 'suggestUsing' + .suggestUsing(x => x + .byField("ProductName", "chokolade") + // Customize suggestions options + .withOptions({ + accuracy: 0.3, + pageSize: 5, + distance: "NGram", + sortMode: "Popularity" + }) + // Customize display name for results + .withDisplayName("SomeCustomName")) + .execute(); + //endregion + } + + { + //region suggestions_10 + // 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: + // chocolade + // schokolade + // chocolate + // chowder + // marmalade + //endregion + } + } +} diff --git a/Documentation/5.3/Raven.Documentation.Pages/client-api/session/querying/.docs.json b/Documentation/5.3/Raven.Documentation.Pages/client-api/session/querying/.docs.json index 3e272d7d34..9bfb10e1a3 100644 --- a/Documentation/5.3/Raven.Documentation.Pages/client-api/session/querying/.docs.json +++ b/Documentation/5.3/Raven.Documentation.Pages/client-api/session/querying/.docs.json @@ -123,7 +123,7 @@ }, { "Path": "how-to-work-with-suggestions.markdown", - "Name": "How to Work With Suggestions", + "Name": "Query for Suggestions", "DiscussionId": "a4f62c57-a06a-440c-b1a3-4cbaa9a4f0d0", "Mappings": [ { diff --git a/Documentation/5.4/Raven.Documentation.Pages/client-api/session/querying/.docs.json b/Documentation/5.4/Raven.Documentation.Pages/client-api/session/querying/.docs.json index 022bf7e044..a242bfd670 100644 --- a/Documentation/5.4/Raven.Documentation.Pages/client-api/session/querying/.docs.json +++ b/Documentation/5.4/Raven.Documentation.Pages/client-api/session/querying/.docs.json @@ -123,7 +123,7 @@ }, { "Path": "how-to-work-with-suggestions.markdown", - "Name": "How to Work With Suggestions", + "Name": "Query for Suggestions", "DiscussionId": "a4f62c57-a06a-440c-b1a3-4cbaa9a4f0d0", "Mappings": [ { diff --git a/Documentation/6.0/Raven.Documentation.Pages/client-api/session/querying/.docs.json b/Documentation/6.0/Raven.Documentation.Pages/client-api/session/querying/.docs.json index 5541fc7d30..7c422182f8 100644 --- a/Documentation/6.0/Raven.Documentation.Pages/client-api/session/querying/.docs.json +++ b/Documentation/6.0/Raven.Documentation.Pages/client-api/session/querying/.docs.json @@ -128,7 +128,7 @@ }, { "Path": "how-to-work-with-suggestions.markdown", - "Name": "How to Work With Suggestions", + "Name": "Query for Suggestions", "DiscussionId": "a4f62c57-a06a-440c-b1a3-4cbaa9a4f0d0", "Mappings": [ {