List values of a field

This is for:

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 :



  "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
  } ]


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


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 : 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 : Boolean

Specifies if the accents should be ignored. Default true.


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: number

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


queryOverride: string

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


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: string

See the following section.


patternType: string

See the following section.


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: string

The unique identifier of the commerce catalog to query.


filter: string

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


operation: string

The way the commerce request should affect query results.

Allowed values are:

  • selectCatalogObjects
  • excludeCatalogObjects