Edit

Dataverse Search autocomplete

  • Article

Autocomplete API lets consumers send a partial search query term to Dataverse search and get back the search term that is potential user intent.

Use this API to support a richer search box experience. As the user enters each character of their search term, call autocomplete and populate the search box's query with the autocomplete result to provide type-ahead word completion. For example: typing in set autocompletes to settings:

Example showing auto-complete with the word 'settings'

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. Search Term search parameter
entities string The default scope is searching across all search–configured entities and fields. entities parameter
filter string Filter criteria to reduce results returned. filter parameter
fuzzy bool Fuzzy search to aid with misspellings. The default is false. fuzzy parameter

Parameters

This section contains details about the parameters in the table above.

search parameter

Type: string
Optional: false

Search term must be at least one character long and has a 100 character limit.

entities parameter

Type: string
Optional: True

The default scope is searching across all search–configured entities and fields. This parameter uses the same Query SearchEntity type used by the query API.

filter parameter

Type: string
Optional: True

Filter criteria to reduce results returned. This parameter uses the same string values as Query filter parameter.

fuzzy parameter

Type: bool
Optional: True

Fuzzy search to aid with misspellings. The default is false.

When set to true, this API finds suggestions even if there's a substituted or missing character in the search text. The edit distance is 1 per query string. If the query string is multiple terms, there can only be one missing, extra, substituted, or transposed character in the entire string. Enabling fuzzy match can be a better experience in some scenarios, it does come at a performance cost, as fuzzy suggestion searches are slower and consume more resources.

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 string The text.
QueryContext QueryContext This property is used for backend search. It's included for future feature releases and is currently not used.

Response types

The response returns the following types:

ErrorDetail

This type is the same ErrorDetail returned by the query API.

QueryContext

This type is the same QueryContext returned by the query API.

Examples

The following examples show how to use the autocomplete operation. These examples return autocomplete results for the account table name field.

This example is from the SDK for .NET search operations sample on GitHub. The static OutputAutoComplete method accepts a value for the search parameter.

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

    searchautocompleteRequest request = new()
    {
        search = searchTerm,
        filter = null,
        fuzzy = true,
        entities = JsonConvert.SerializeObject(new List<SearchEntity>()
            {
                new SearchEntity()
                {
                    Name = "account",
                    SelectColumns = new List<string>() { "name", "createdon" },
                    SearchColumns = new List<string>() { "name" },
                }
            }
        )
    };

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

    SearchAutoCompleteResults results = JsonConvert.DeserializeObject<SearchAutoCompleteResults>(searchautocompleteResponse.response);

    Console.WriteLine($"\tSearch: {request.search}");
    Console.WriteLine($"\tValue: {results.Value}");

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

Output

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

OutputAutoComplete(service: serviceClient, searchTerm: "Con");

The output looks something like the following:

OutputAutoComplete START

        Search: Con
        Value: {crmhit}contoso{/crmhit}

OutputAutoComplete END

Supporting classes

The OutputAutoComplete method depends on the following supporting classes to send the request and process the result:

searchautocompleteRequest and searchautocompleteResponse 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.

SearchEntity class

This class is the same SearchEntity class used for the query example. In this case, you use it to set the searchautocompleteRequest.entities property.

SearchAutoCompleteResults class

Use to deserialize JSON data from the searchautocompleteResponse.response string property.

class SearchAutoCompleteResults
{
   /// <summary>
   /// The Azure Cognitive error detail returned as part of response.
   /// </summary>
   public ErrorDetail? Error {  get; set; }

   /// <summary>
   /// The text
   /// </summary>
   public string? Value { get; set; }

   /// <summary>
   /// This request is used for backend search, this is included for future feature releases, it is not currently used.
   /// </summary>
   public QueryContext? QueryContext { get; set; }
}
ErrorDetail class

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

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 suggest
Dataverse Search statistics and status
Dataverse legacy search