Upravit

Sdílet prostřednictvím

Dataverse Search suggest

  • Článek

Use this API to support a richer search box experience. For example, as the user enters each character of their search term, call this API and populate the dropdown list of the search field with the suggested query results.

In addition to a search term, the results returned can be influenced by passing values for the following parameters:

Name Type Description More information
search string Required. The text to search with. search parameter
entities string The default is searching across all search–configured entities. entities parameter
filter string Filter criteria to reduce results returned. filter parameter
fuzzy bool Use fuzzy search to aid with misspellings. The default is false. fuzzy parameter
options string Options are settings configured to search a search term. For example "{ 'advancedsuggestenabled': 'true' }". options parameter
orderby string List of comma-separated clauses where each clause is an attribute name followed by asc or desc. orderby parameter
top int Number of suggestions to retrieve. The default is 5. top parameter

Parameters

This section contains details about the parameters introduced by the table above.

search parameter

Type: string
Optional: false

The text to search with. Search term must be at least three characters long and has a 100 character limit.

entities parameter

Type: string
Optional: true

The default is searching across all search–configured entities. Use this property to narrow the results.

filter parameter

Type: string
Optional: true

Filter criteria to reduce results returned based on records that match the filter criteria.

fuzzy parameter

Type: bool
Optional: true

Use fuzzy search to aid with misspellings. The default is false.

options parameter

Type: string
Optional: true

Options are settings configured to search a search term. Valid options for suggest query is:

"{ 'advancedsuggestenabled': 'true' }".

orderby parameter

Type: string
Optional: true

List of comma-separated clauses where each clause is an attribute name followed by asc or desc.

top parameter

Type: int
Optional: true

Number of suggestions to retrieve. The default is 5.

Response

The response from the suggest operation is an escaped string that includes JSON data.

The unescaped response contains JSON using the following properties.

Name Type Description
Error ErrorDetail Provides error information from Azure Cognitive search.
Value SuggestResult[] A collection of matching records.
QueryContext QueryContext The query context returned as part of response. This property is used for backend search. It's included for future feature releases and isn't currently used.

Response Types

The response returns the following types:

ErrorDetail

This is the same ErrorDetail returned by the query API.

SuggestResult

Provides the suggested text.

Name Type Description
Text string Provides the suggested text.
Document Dictionary<string, object> The document.

QueryContext

This is the same QueryContext returned by the query API.

Examples

The following examples show how to use the suggest operation. Each of these examples pass the value "Cont" as the search parameter and request the top three suggestions.

This example is from the SDK for .NET search operations sample on GitHub. The static OutputSearchSuggest method returns the top three suggestions for any search term.

/// <summary>
/// Demonstrate suggest API
/// </summary>
/// <param name="service">The authenticated IOrganizationService instance to use.</param>
/// <param name="searchTerm">The term to use</param>
/// <returns></returns>
static void OutputSearchSuggest(IOrganizationService service, string searchTerm)
{
    Console.WriteLine("OutputSearchSuggest START\n");

    searchsuggestRequest request = new()
    {
        search = searchTerm,
        top = 3
    };

    var searchsuggestResponse = (searchsuggestResponse)service.Execute(request);

    SearchSuggestResults results = JsonConvert.DeserializeObject<SearchSuggestResults>(searchsuggestResponse.response);

    results.Value?.ForEach(suggestion =>
    {
        Console.WriteLine($"\tText:{suggestion.Text}");
        Console.WriteLine("\tDocument: ");
        foreach (string key in suggestion.Document.Keys)
        {
            Console.WriteLine($"\t\t{key}: {suggestion.Document[key]}");
        }
        Console.WriteLine();
    });

    Console.WriteLine("OutputSearchSuggest END\n");
}

Output

When you invoke the OutputSearchSuggest method with an authenticated instance of the ServiceClient class with the searchTerm set to "Cont":

OutputSearchSuggest(service: serviceClient, searchTerm: "Cont");

The output looks something like the following:

OutputSearchSuggest START

        Text:{crmhit}cont{/crmhit}act
        Document:
                @search.objectid: 9335eda1-ef69-ee11-9ae7-000d3a88a4a2
                @search.entityname: contact
                @search.objecttypecode: 2
                fullname: Yvonne McKay (sample)

        Text:{crmhit}cont{/crmhit}act
        Document:
                @search.objectid: 9535eda1-ef69-ee11-9ae7-000d3a88a4a2
                @search.entityname: contact
                @search.objecttypecode: 2
                fullname: Susanna Stubberod (sample)

        Text:{crmhit}cont{/crmhit}act
        Document:
                @search.objectid: 9735eda1-ef69-ee11-9ae7-000d3a88a4a2
                @search.entityname: contact
                @search.objecttypecode: 2
                fullname: Nancy Anderson (sample)

OutputSearchSuggest END

Supporting classes

The OutputSearchSuggest method depends on the following supporting classes to send the request and process the result.

searchsuggestRequest and searchsuggestResponse classes

These classes are generated using Power Platform CLI pac modelbuilder build command as described in Generate early-bound classes for the SDK for .NET.

ErrorDetail class

This class is the same ErrorDetail class used for the query example.

SuggestResults class

Used to deserialize the data from the searchsuggestResponse.response property

class SearchSuggestResults
{
   /// <summary>
   /// Provides error information from Azure Cognitive search.
   /// </summary>
   [JsonProperty(PropertyName = "Error")]
   public ErrorDetail? Error { get; set; }

   /// <summary>
   /// A collection of matching records.
   /// </summary>
   public List<SuggestResult>? Value { get; set; }

   /// <summary>
   /// The query context returned as part of response. This property is used for backend search, this is included for future feature releases, it is not currently used.
   /// </summary>
   public QueryContext? QueryContext { get; set; }
}
SuggestResult class

Result object for suggest results.

public sealed class SuggestResult
{
   /// <summary>
   /// Gets or sets the text.
   /// </summary>
   [JsonProperty(PropertyName = "text")]
   public string Text { get; set; }

   /// <summary>
   /// Gets or sets document.
   /// </summary>
   [JsonProperty(PropertyName = "document")]
   public Dictionary<string, object> Document { get; set; }
}
QueryContext class

This class is the same QueryContext class used for the query example.

See also

Search for Dataverse records
Dataverse Search query
Dataverse Search autocomplete
Dataverse Search statistics and status
Dataverse legacy search