Search across entity data using relevance search

Note

Effective November 2020:

  • Common Data Service has been renamed to Microsoft Dataverse. Learn more
  • Some terminology in Microsoft Dataverse has been updated. For example, entity is now table and field is now column. Learn more

This article will be updated soon to reflect the latest terminology.

Relevance search delivers fast and comprehensive search results across multiple entities, in a single list, sorted by relevance. Relevance search must be enabled in your target environment by an administrator before you can use the feature. More information: Using relevance search to search for records

To begin using relevance search, your application simply issues an HTTP POST request (presently Web API only) to start a relevance search. When searching data, specify optional query parameters to set criteria for how the environment data is to be searched.

There are three relevance search methods that can be used in the Power Apps web application UI:

  • Search: Provides a search results page.

  • Suggestions: Provides suggestions as the user enters text into a form field.

  • Autocomplete: Provides autocompletion of input as the user enters text into a form field.

The following sections describe how to access the abovementioned search capabilities from application code.

The minimum syntax of a relevance search HTTP request is as shown below.

POST [Organization URI]/api/search/v1.0/query
{  
  “search”: “<search term>”
}

The search parameter value contains the term to be searched for and has a 100-character limit.

A successful search response returns an HTTP status of 200 and consists of:

  • value: a list of entities. By default, 50 results are returned. This also includes search highlights, which indicate matches to the search parameter value contained within the crmhit tag of the response.

  • totalrecordcount: The total count of results (of type long). A value of −1 is returned if returntotalrecordcount is set to false (default).

  • facets: The facet results.

In addition, you can add one or more query parameters to customize how the search is to be done and which results are returned. The supported query parameters are indicated in the following section.

Query parameters

The following query parameters are supported for relevance search.

entities=[list<string>] (optional)

The default entity list searches across all relevance search–configured entities and fields. The default list is configured by your administrator when relevance search is enabled.

facets=[list<string>] (optional)

Facets support the ability to drill down into data results after they've been retrieved.

POST [Organization URI]/api/search/v1.0/query
{  
  “search”: ”maria”,

  “facets”: ["@search.entityname,count:100",  
    "account.primarycontactid,count:100",  
    "ownerid,count:100",  
    "modifiedon,values:2019-04-27T00:00:00|2020-03-27T00:00:00|2020-04-20T00:00:00|2020-04-27T00:00:00",
    "createdon,values:2019-04-27T00:00:00|2020-03-27T00:00:00|2020-04-20T00:00:00|2020-04-27T00:00:00"]
}

filter=[string] (optional)

Filters are applied while searching data and are specified in standard OData syntax.

POST [Organization URI]/api/search/v1.0/query
{  
  “search”: ”maria”,

  “filter”: "account:modifiedon ge 2020-04-27T00:00:00,
    activities: regardingobjecttypecode eq 'account', annotation:objecttypecode eq 'account',
    incident: (prioritycode eq 1 or prioritycode eq 2)"
}

returntotalrecordcount = true | false (optional)

Specify true to return the total record count; otherwise false. The default is false.

skip=[int] (optional)

Specifies the number of search results to skip.

top=[int] (optional)

Specifies the number of search results to retrieve. The default is 50, and the maximum value is 100.

orderby=[list<string>] (optional)

A list of comma-separated clauses where each clause consists of an attribute name followed by 'asc' (ascending, which is the default) or 'desc' (descending). This list specifies how to order the results in order of precedence. By default, results are listed in descending order of relevance score (@search.score). For results with identical scores, the ordering will be random.

For a set of results that contain multiple entity types, the list of clauses for orderby must be globally applicable (for example, modifiedon, createdon, @search.score). Note that specifying the orderby parameter overrides the default. For example, to get results ranked (in order of precedence) by relevance, followed by the most recently modified records listed higher:

“orderby”: [“@search.score desc", "modifiedon desc”]

If the query request includes a filter for a specific entity type, orderby can optionally specify entity-specific attributes.

searchmode= any | all (optional)

Specifies whether any or all the search terms must be matched to count the document as a match. The default is 'any'.

Note

The searchMode parameter on a query request controls whether a term with the NOT operator is AND'ed or OR'ed with other terms in the query (assuming there is no + or | operator on the other terms).

Using searchMode=any increases the recall of queries by including more results, and by default will be interpreted as "OR NOT". For example, "wifi -luxury" will match documents that either contain the term "wifi" or those that don't contain the term "luxury".

Using searchMode=all increases the precision of queries by including fewer results, and by default will be interpreted as "AND NOT". For example, "wifi -luxury" will match documents that contain the term "wifi" and don't contain the term "luxury".

searchtype= simple | full (optional)

The search type specifies the syntax of a search query. Using 'simple' selects simple query syntax and 'full' selects Lucene query syntax. The default is 'simple'.

The simple query syntax supports the following functionality:

Functionality Description
Boolean operators AND operator; denoted by +
OR operator; denoted by |
NOT operator; denoted by -
Precedence operators A search term "hotel+(wifi | luxury)" will search for results containing the term "hotel" and either "wifi" or "luxury" (or both).
Wildcards Trailing wildcard are supported. For example, "Alp*" searches for "alpine".
Exact matches A query enclosed in quotation marks " ".

The Lucene query syntax supports the following functionality:

Functionality Description
Boolean operators Provides an expanded set compared to simple query syntax.
AND operator; denoted by AND, &&, +
OR operator; denoted by OR, ||
NOT operator; denoted by NOT, !, –
Precedence operators The same functionality as simple query syntax.
Wildcards In addition to a trailing wildcard, also supports a leading wildcard.
Trailing wildcard – "alp*"
Leading wildcard - "*ine"
Fuzzy search Supports queries misspelled by up to two characters.
"Uniersty~" will return "University"
"Blue~1" will return "glue", "blues"
Term boosting Weighs specific terms in a query differently.
"Rock^2 electronic" will return results where the matches to "rock" are more important than matches to "electronic".
Proximity search Returns results where terms are within x words of each other, for more contextual results.
For example, "airport hotel"~5 returns results where "airport" and "hotel" are within five words of each other, thus boosting the chances of finding a hotel located close to an airport.
Regular expression (regex) search For example, /[mh]otel/ matches "motel" or "hotel".

Below is an example of a basic search request and response.

Request

POST [Organization URI]/api/search/v1.0/query
{  
  “search”: ”maria”,

  “facets”: ["@search.entityname,count:100",  
    "account.primarycontactid,count:100",  
    "ownerid,count:100",  
    "modifiedon,values:2019-04-27T00:00:00|2020-03-27T00:00:00|2020-04-20T00:00:00|2020-04-27T00:00:00",
    "createdon,values:2019-04-27T00:00:00|2020-03-27T00:00:00|2020-04-20T00:00:00|2020-04-27T00:00:00"]
}

Response

{
    "value": [
        {
            "@search.score": 0.4547767,
            "@search.highlights": {
                "emailaddress1": [
                    "{crmhit}maria{/crmhit}@contoso.com"
                ],
                "firstname": [
                    "{crmhit}Maria{/crmhit}"
                ],
                "fullname": [
                    "{crmhit}Maria{/crmhit} Sullivan"
                ]
            },
            "@search.entityname": "contact",
            "@search.objectid": "16ffc791-d06d-4d8c-84ad-89a8978e14f3",
            "key": "5d3d6f6b-a721-4108-ad95-fe25eebbc277contact2",
            "ownerid": "bb2500d1-5e6d-4953-8389-bfedf57e3857",
            "owneridname": "Corey Gray",
            "@search.ownerid.logicalname": "systemuser",
            "owningbusinessunit": "e854b0d3-3441-418d-854f-b7d11bb17f1b",
            "owningbusinessunitname": "",
            "@search.owningbusinessunit.logicalname": "businessunit",
            "sharedtoprincipalid": [],
            "@search.objecttypecode": 2,
            "fullname": "Maria Sullivan",
            "versionnumber": 1622564,
            "statecode@stringcollection": [
                "Active"
            ],
            "statecode": 0,
            "statuscode@stringcollection": [
                "Active"
            ],
            "statuscode": 1,
            "entityimage_url": **null**,
            "lastsyncdate": "/Date(1602289865930)/",
            "createdon": "10/9/2020 5:27 PM",
            "modifiedon": "10/9/2020 5:27 PM",
            "documentbody": **null**,
            "body": **null**,
            "filebody": **null**,
            "emailaddress1": "maria@contoso.com",
            "address1_city": **“Seattle”**,
            "address1_telephone1": **“206-400-0200”**,
            "parentcustomerid": **null**,
            "parentcustomeridname": **null**,
            "telephone1": **“206-400-0300”**
        }
    ],
    "facets": {
        "account.primarycontactid": [],
        "ownerid": [
            {
                "Type": "Value",
                "Value": "31ca7d4b-701c-4ea9-8714-a89a5172106e",
                "OptionalValue": "Corey Gray",
                "Count": 1
            }
        ],
        "@search.entityname": [
            {
                "Type": "Value",
                "Value": "contact",
                "Count": 1
            }
        ],
        "modifiedon": [
            {
                "Type": "Range",
                "To": "4/27/2019 12:00 AM",
                "Count": 0
            },
            {
                "Type": "Range",
                "From": "4/27/2019 12:00 AM",
                "To": "3/27/2020 12:00 AM",
                "Count": 0
            },
            {
                "Type": "Range",
                "From": "3/27/2020 12:00 AM",
                "To": "4/20/2020 12:00 AM",
                "Count": 0
            },
            {
                "Type": "Range",
                "From": "4/20/2020 12:00 AM",
                "To": "4/27/2020 12:00 AM",
                "Count": 0
            },
            {
                "Type": "Range",
                "From": "4/27/2020 12:00 AM",
                "Count": 1
            }
        ],
        "createdon": [
            {
                "Type": "Range",
                "To": "4/27/2019 12:00 AM",
                "Count": 0
            },
            {
                "Type": "Range",
                "From": "4/27/2019 12:00 AM",
                "To": "3/27/2020 12:00 AM",
                "Count": 0
            },
            {
                "Type": "Range",
                "From": "3/27/2020 12:00 AM",
                "To": "4/20/2020 12:00 AM",
                "Count": 0
            },
            {
                "Type": "Range",
                "From": "4/20/2020 12:00 AM",
                "To": "4/27/2020 12:00 AM",
                "Count": 0
            },
            {
                "Type": "Range",
                "From": "4/27/2020 12:00 AM",
                "Count": 1
            }
        ]
    },
    "totalrecordcount": -1
}

Suggestions

Suggestions provide a list of matches to the specified search parameter value, based on an entity record's primary field. This is different from a regular search request because a suggestion search only searches through an entity record's primary field, while search requests search through all relevance search–enabled entity fields.

The minimum syntax of a suggestion search HTTP request is as shown below.

POST [Organization URI]/api/search/v1.0/suggest
{
  “search”: “<text-fragment>”
}

The search parameter value provides a text string for the search to match and has a three-character minimum length.

A successful search response returns an HTTP status of 200 and contains "value", which is a list consisting of text or a document where the text is the suggestion with highlights, and the document is a dictionary <string,object> of the suggestion result. By default, five results are returned. Suggestion highlights indicate matches to the search parameter value and are contained within the crmhit tag in the response.

In addition, you can add one or more query parameters to customize how the suggestion search is to be done and which results are returned. The supported query parameters are indicated in the following section.

Query parameters

usefuzzy=true | false (optional)

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

top=[int] (optional)

Number of suggestions to retrieve. The default is 5.

orderby=[List<string>] (optional)

A list of comma-separated clauses where each clause consists of an attribute name followed by 'asc' (ascending) or 'desc' (descending). This list specifies how to order the results in order of precedence. By default, results are listed in descending order of relevance score (@search.score). For results with identical scores, the ordering will be random.

For a set of results that contain multiple entity types, the list of clauses for orderby must be globally applicable (for example, modifiedon, createdon, @search.score). Note that specifying the orderby parameter overrides the default. For example, to get results ranked (in order of precedence) by relevance, followed by the most recently modified records listed higher:

“orderby”: [“@search.score desc", "modifiedon desc”]

If the query request includes a filter for a specific entity type, orderby can optionally specify entity-specific attributes.

entities=[list<string>] (optional)

The default is searching across all relevance search–configured entities.

filter=[string] (optional)

Filters are applied while searching data and are specified in standard OData syntax.

Request

POST [Organization URI]/api/search/v1.0/suggest
{  
  “search”: ”mar”,

  “filter”: "account:modifiedon ge 2020-04-27T00:00:00,
    activities:regardingobjecttypecode eq 'account', annotation:objecttypecode eq 'account'"
}

The following is an example of a basic suggestion search request.

Request

POST [Organization URI]/api/search/v1.0/suggest
{  
  “search”: ”mar”
}

Response

{
    "value": [
        {
            "text": "{crmhit}Mar{/crmhit}ia Sullivan",
            "document": {
                "@search.objectid": "52a33850-8f0a-eb11-a813-000d3a8ab142",
                "@search.entityname": "contact",
                "@search.objecttypecode": 2,
                "fullname": "Maria Sullivan",
                "entityimage_url": **null**,
                "emailaddress1": "maria@contoso.com",
                "address1_city": **null**,
                "address1_telephone1": **null**,
                "parentcustomerid": **null**,
                "parentcustomeridname": **null**,
                "telephone1": **null**
            }
        }
    ]
}

Autocomplete

Provides autocompletion of user input. Autocomplete is based on an entity record's primary field.

The minimum syntax of a relevance search HTTP request is as follows.

POST [Organization URI]/api/search/v1.0/autocomplete
{  
  “search”: ”<text-fragment>”
}

A successful search response returns an HTTP status of 200 and consists of "value", which is a string.

In addition, you can add one or more query parameters to customize how the search is to be done and which results are returned. The supported query parameters are indicated in the following section.

Query parameters

usefuzzy=true | false (optional)

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

entities=[list<string>] (optional)

The default scope is searching across all relevance search–configured entities and fields.

filter=[string] (optional)

Filters are applied while searching data and are specified in standard OData syntax.

Request

POST [Organization URI]/api/search/v1.0/autocomplete
{  
  “search”: ”mar”,

  “filter”: "account:modifiedon ge 2020-04-27T00:00:00,
    activities:regardingobjecttypecode eq 'account', annotation:objecttypecode eq 'account'"
}

The following is an example of a basic autocomplete request.

Request

POST [Organization URI]/api/search/v1.0/autocomplete
{  
  “search”: ”mar”
}

Response

{
  "value": "{crmhit}maria{/crmhit}"
}

See also

Configure Relevance Search to improve search results and performance
Compare search options in Microsoft Dataverse
Retrieve related entity records with a query
Query Data using the Web API