編輯

共用方式為

Search for Dataverse records

  • 發行項

Dataverse search delivers fast and comprehensive search results across multiple tables, in a single list, sorted by relevance. It also provides capabilities to support suggestions and autocompletion experiences in apps.

Note

This documentation for developers will describe how to programmatically interact with the Dataverse Search APIs.

See the following topics for information about the user experience and how to configure Dataverse Search for your environment:

How to use

Developers can use the search APIs three different ways:

  • The Dataverse SDK for .NET
  • The Web API /api/data/v9.x endpoint
  • The native search /api/search/v2.0/ endpoint

Search operations are defined as Dataverse messages using Custom APIs. For .NET projects, you can use the SDK for .NET.

There are currently no classes included in the SDK to use these operations. For .NET Framework projects, you can use the Power Platform CLI pac modelbuilder build to generate *Request and *Response classes for these messages just as you would for any custom action.

You can also use the OrganizationRequest and OrganizationResponse classes.

More information:

Search operations

Search provides three operations to support a user interface that enables searching for data.

SDK Message Name
Web API Action
Search 2.0 Endpoint		 Description
searchquery
searchquery Action
/api/search/v2.0/query		 Returns a search results page.
See Dataverse Search query
searchsuggest
searchsuggest Action
/api/search/v2.0/suggest		 Provide suggestions as the user enters text into a form field.
See Dataverse Search suggest
searchautocomplete
searchautocomplete Action
/api/search/v2.0/autocomplete		 Provide autocompletion of input as the user enters text into a form field.
See Dataverse Search autocomplete

There are also two operations you can use to understand whether search is enabled and how it's configured.

SDK Message Name
Web API Function
Search 2.0 Endpoint		 Description
searchstatistics
searchstatistics Function
/api/search/v2.0/statistics		 Provides organization storage size and document count.
See Dataverse Search statistics
searchstatus
searchstatus Function
/api/search/v2.0/status		 Search status of an Organization.
See Dataverse Search Status

If you have used Insomnia with Dataverse Web API, you know how useful it's to try using the APIs. We have some instructions about setting up a Insomnia environment to authenticate with the Dataverse Web API here: Use Insomnia with Dataverse Web API

You can use the same instructions with the search operations using Web API functions and actions. If you want to use the native search 2.0 endpoint, change these two environment variables:

Variable Web API Value Search 2.0 Endpoint value
version 9.2 2.0
webapiurl {{url}}/api/data/v{{version}}/ {{url}}/api/search/v{{version}}/

Detect if search is enabled

Dataverse search is enabled by default for production environments, but it's an opt-out feature so it could be turned off even in a production environment. If you're using an environment other than a production environment, an administrator must enable it. Learn how to enable search in the admin center.

Error when search not enabled

If you use the query, suggest, or autocomplete operations when the environment isn't enabled you'll get these errors:

ErrorCode: -2147185397 Message: Dataverse Search feature is disabled for this organization.

You can detect whether the search service is enabled by checking the settings in the organization table or by using the Dataverse Search Status operation.

Check Organization table

The Organization table contains a single row of data that controls how the organization is configured. The IsExternalSearchIndexEnabled boolean column tells you whether search is enabled for the organization.

This function returns the IsExternalSearchIndexEnabled property value for the organization.

static bool IsExternalSearchIndexEnabled(IOrganizationService service) {

    QueryExpression query = new QueryExpression("organization") { 
        ColumnSet = new ColumnSet("isexternalsearchindexenabled")
    };

    EntityCollection organizations = service.RetrieveMultiple(query);
    return (bool)organizations.Entities.FirstOrDefault()["isexternalsearchindexenabled"];
}

More information: Build queries with QueryExpression

Which tables and columns are enabled for search is controlled by data in Dataverse.

Enable Tables

Only those tables where the EntityMetadata.CanEnableSyncToExternalSearchIndex.Value property and EntityMetadata.ChangeTrackingEnabled property are true can be enabled for Dataverse search. If the CanEnableSyncToExternalSearchIndex.CanBeChanged value is false, you can't change the value. More information: Managed properties

To enable a table for Dataverse Search, set the EntityMetadata.SyncToExternalSearchIndex property to true.

You can check the values for a table with the SDK or Web API using the table logical name. Replace account in the following queries with the logical name of the table you want to check.

static void RetrieveSearchSettingsForTable(IOrganizationService service, string logicalName = "account") {

    RetrieveMetadataChangesRequest request = new RetrieveMetadataChangesRequest() { 
            Query = new EntityQueryExpression() { 
                Properties = new MetadataPropertiesExpression(
                    "CanEnableSyncToExternalSearchIndex", 
                    "SyncToExternalSearchIndex")
            }
    };
    request.Query.Criteria.Conditions.Add(
        new MetadataConditionExpression(
            propertyName: "LogicalName", 
            conditionOperator: MetadataConditionOperator.Equals, 
            value: logicalName));

    var response = (RetrieveMetadataChangesResponse)service.Execute(request);

    EntityMetadata table = response.EntityMetadata.FirstOrDefault();

    Console.WriteLine($"CanEnableSyncToExternalSearchIndex: {table.CanEnableSyncToExternalSearchIndex.Value}");
    Console.WriteLine($"SyncToExternalSearchIndex: {table.SyncToExternalSearchIndex}");
}

Output

CanEnableSyncToExternalSearchIndex: True
SyncToExternalSearchIndex: True

More information:

More information:

Enable Columns

The columns that are searchable for the table are determined by whether they're included in the Quick Find view for each table. You can query the definition of the view in the View (SavedQuery) table and update it programmatically.

More information:

Service Protection Limits

The common Dataverse Service protection API limits will never be approached because Dataverse search applies a lower limit. The way you manage them is the same.

Dataverse search allows a user to send one request per second, and each organization is limited to 150 requests per minute. If you exceed this limit, a 429 Too Many Requests error is returned. If a 429 error is returned, you should wait until the period defined in the Retry-After response header value has passed before sending more requests. The value represents the number of seconds to wait.

See also

Dataverse Search query
Dataverse Search suggest
Dataverse Search autocomplete
Dataverse Search statistics and status
Dataverse legacy search
Configure Dataverse search for your environment