List values of a field

This is for:

Developer
In this article

The REST Search API allows you to list the different values associated with a specific field of an index. This is used, among other things, to perform queries from within a facet, displaying only the facet values that match the query.

You may want to retrieve all file types that are stored in an index. To do so, you must specify sysfiletype as the field parameter value in the URL. You can also limit the number of results by using the maximumNumberOfValues parameter :

/rest/search/values?field=@sysfiletype&maximumNumberOfValues=100

Response

{
  "values" : [ {
    "value" : "html",
    "lookupValue" : "html",
    "numberOfResults" : 315
  }, {
    "value" : "doc",
    "lookupValue" : "doc",
    "numberOfResults" : 103
  }, {
    "value" : "SPDocumentLibraryList",
    "lookupValue" : "SPDocumentLibraryList",
    "numberOfResults" : 60
  }, {
    "value" : "xml",
    "lookupValue" : "xml",
    "numberOfResults" : 53
  }, {
    "value" : "txt",
    "lookupValue" : "txt",
    "numberOfResults" : 46
  }, {
    "value" : "SPUserProfile",
    "lookupValue" : "SPUserProfile",
    "numberOfResults" : 29
  }, {
    "value" : "SPSite",
    "lookupValue" : "SPSite",
    "numberOfResults" : 24
  }, {
    "value" : "pdf",
    "lookupValue" : "pdf",
    "numberOfResults" : 18
  }, {
    "value" : "SPCustomList",
    "lookupValue" : "SPCustomList",
    "numberOfResults" : 15
  }, {
    "value" : "SPLinkList",
    "lookupValue" : "SPLinkList",
    "numberOfResults" : 10
  } ]
}

Parameters

The following list contains all parameters available when listing the values of a field using the REST Search API.

field

field : string

Specifies the field of the request. The target field must be facetable, otherwise the request will fail (see Add or edit a field).

lookupField

lookupField : string

Specifies the name of an additional field whose value should be included. This field value should have a 1:1 relationship with the values of the field specified using field. Default null.

ignoreAccents

ignoreAccents : Boolean

Specifies if the accents should be ignored. Default true.

sortCriteria

sortCriteria : string

Specifies the sort criteria to be used. Default occurrences.

The following table lists available sort criteria (the values are case-insensitive).

Criterion Description
Occurrences Sort by number of occurrences, with values having the highest number appearing first.
nosort Don’t sort the values. The values will be returned in a random order.

maximumNumberOfValues

maximumNumberOfValues: number

Specifies the maximum number of values to be returned by the query. Default 10.

queryOverride

queryOverride: string

Specifies a different query expression to be used. By default, the query expression being executed is used. Default null.

constantQueryOverride

constantQueryOverride: string

Specifies a different constant query expression (cq) to be used. By default, the constant part of the query expression being executed is used. Default null.

Nested queries should never be in the constant query expression, as they prevent caching and will slow down all queries.

pattern

pattern: string

See the following section.

patternType

patternType: string

See the following section.

patternType

Specifies the type of pattern that’s being used to list field values.

The available values for a pattern type are:

  • Wildcards: The pattern is a wildcard expression (ex: abc*def matches all values starting with abc and ending with def).
  • RegularExpression: The pattern is a regular expression.

  • EditDistance: Uses an Edit Distance algorithm to match the closest values from the specified pattern (see Edit Distance in Wikipedia).
  • Phonetic: Uses the phonetic algorithm to match values that sound the same.

catalogId

catalogId: string

The unique identifier of the commerce catalog to query.

filter

filter: string

A mandatory query expression to apply if the commerce request affects the query.

operation

operation: string

The way the commerce request should affect query results.

Allowed values are:

  • selectCatalogObjects
  • excludeCatalogObjects