The Discovery Search Engine Query API is designed to provide developers with a simple
interface to query functionality. It can be accessed via HTTP with JSON.

A query against the Discovery Search Engine takes the search criteria and returns a
list of relevant item ids. The standard use of this method involves taking
these item ids and submitting simple queries to your existing data source
before displaying the results to the end user.

The query Request instructs the engine what to search, options to apply to the
search and what to return in the Response. Most of the request fields result in
changes to the server response. This section covers the request portion of a query.
For complete coverage of the response, refer to Query Response.

Note that the engine will perform type conversion in some simple cases,
meaning that you can pass in a string when an int or double is expected.

The drill down criteria that specify which buckets we want to perform drill
down on and thus obtain the faceted search counts. This is a deprecated API.
Use the new facets top-level request and response.

Setting this option causes the engine to only return items that are exact
matches. Fuzzy matches are automatically culled from the query results.

Type: boolean.

exactRelevance

Setting this option causes the engine to assign the specified relevance
to any exact matched item.

Type: double.

properties

Setting this field with one or more changeset property ids causes the engine
to return the associated stored property values for the named properties.
The property values are returned in an array with length equal to the number
of query results on the requested page and in the same order as the item ids
returned in the response.

The highlighting criteria that specify what type of highlighting to perform
and the changeset properties to return with highlighting applied. If highlighting
is used in combination with properties, then the highlighted results are
returned integrated with the properties response (see above) unless the
highlighting request merge field is set to none.

The highlighting response is returned with the properties response or highlighting
response. For a
description of the properties response, refer to Properties. For
a description of the highlighting response, refer to Highlighting.

New in version 2.8.3.

indexValues

Setting this field with one or more dimension ids causes the engine to return
the associated new-form indexed values for the specified dimensions. The index values are
returned in a dictionary with keys for each requested dimension id. The value of the
key contains the relevant index values data.

Setting this field with one or more dimension ids causes the engine to return
the associated legacy indexed values for the specified dimensions. The values are
returned in an array with length equal to the number of query results on the
requested page.

Setting this field with one or more dimension keys configured appropriately will
be used to return calculated values in the response. For example, in geoloc type
dimensions, the distance from the search centroid or polygon can be returned for use
in the presentation layer.

Minimum length of value that will be used when searchStyle is startsWith.
For text type dimensions, this setting avoids costly searches for any
word starting with less than the specified value

Type: int

Default: 3

exactRequires

When an array of values in a query, this key allows you to determine what
constitutes an exact match.

When exactRequires is all, then all values must be found in order for the item
to be considered an exact match, otherwise, any match to any value will be determine
if the item is exact or not.

Note: Text type dimensions also support exactRequires, however the feature applies
to the number of term matches in a phrase.

Type: string

Values: any | all

Default: any

exactMatch

This criterion field affects whether a result is considered an exact match or not.
Typically you’d set this to true to cause the engine to ignore this criterion
when it comes to the exact match calculation.

When used as part of a nested query, setting exactMatch to false means
that the nested criterion should participate in relevance calculations but should
never be considered an exact match.

Type: boolean

Default: not set

Warning: Setting this to false will cause all records to be considered
not exact matches.

nullExactMatch

Setting this field causes records that don’t have a valid value under this
dimension to be left in the result set. The value of this field determines
whether these records should be considered an exact match for this criterion
only. i.e. Setting this to true will only cause a record with no valid
value for this dimension to be considered an exact match if it is also
considered an exact match for all other dimensions. Setting it to false will
cause that record to not be an exact match, regardless of the other
criterion.

Type: boolean

Default: not set

exactRelevance

Determines the relevance score override to apply to any exact matches for this
criterion. This field is often used in combination with fuzzyRelevance and
nullRelevance.

Setting this field causes records that don’t have a valid value under this
dimension to be left in the result set. The value of this field determines
what the calculated relevance score for these records should be for this
criterion.

This field is often used in combination with exactRelevance and
fuzzyRelevance.

Disables or configures Did You Mean processing for the criterion. Did You Mean? is automatically
enabled if the dimension has been defined with the didYouMean attribute. To disable, set didYouMean to
false.. To configure the Did You Mean feature, create a dictionary as defined in DidYouMean Criterion.

Type: boolean or dictionary

Default: Defaults to the value of the didYouMean attribute of the text dimension
for the criterion.

The following can be specified if the dimension is geoloc. In general, if you use
latitude and longitude, then you are searching using a radius around
that point. Alternatively, you can specify one or more polygon shapes that
define the boundaries of the search.

When scoring matches against a specific point on the map, by default, the engine
will only score a match perfectly if the searched for and item coordinates match
exactly. As the item coordinates diverge from the searched point, their relevance
will be less than 1.0 where the end result is that no two items will have the same
relevance.

Using exactDistance will score all matches within the distance equally; however
a side effect of this option is that items nearest the center will not necessarily
appear as relevant, particularly when there are more items in the response than
fit on the current page.

isoRelevanceDistance allows for the creation of distances from the target
(the point identified with latitude and longitude) in which the relevance
is equal. The distances are expressed in distanceUnit units.

For example, defining a isoRelevanceDistance [0.5, 5, 10, 20] would mean that
the relevances of each item would be calculated by assuming
a point at each isoRelevanceDistance and using that relevance for any points
within the applicable relevance distance. Concretely, an item that is 7 miles
away from the target would be assigned a relevance value as if it were just 5
miles away (the best score for that range).

The score of the first element of the list defaults to 1.0. To change the maximum
relevance, use the existing exactRelevance query criterion key.

The default target is determined by latitude and longitude.

Note: This setting only affects the relevance of a match. It has no impact on
the exact or fuzzy status.

The shapes criteria that specify which polygons/shapes to use for
matching. Shapes can be used in place of specifying a single point using
latitude and longitude.

The coordinates for non-point shapes are presented using two parallel arrays, one
for latitude and one for longitude. The n th element of each array is combined
to create the coordinate, e.g. latLng1 = new Point(latitude[0], longitude[0]),
latLng2 = new Point(latitude[1], longitude[2]), etc.

When using the word query parser, this option allows the exact match flag
to be set based upon how many words in the query match an item.

When exactRequires is all, then all analyzed terms must be found in order for the item
to be considered an exact match.

Type: string

Values: any | all

Default: any

ignoreFieldLength

If this parameter is true, then matches against the dimension (or field)
will not be made less relevant as the text length of the field increases. The default behavior
will automatically reduce relevance of matches as the field length increases.

Note: ignoreFieldLength will only have effect if the dimension (or field) was
created with the ignoreFieldLength attribute set to true. Using this query parameter requires
that the dimension be correctly configured.

Type: boolean

Default: false

New in version 2.8.2.

ignoreInverseDocumentFrequency

If this parameter is true, then matches against the dimension (or field)
will not be boosted because the matched search terms are infrequent amongst
the values of the entire text dimension. The default behavior
will automatically boost relevance of matches just because of their uniqueness
amongst the entire set of values in the dimension index.

Nested queries are useful in grouping search criterion together such that the
matches against the criterion in the group are considered as a whole when applied
to the rest of the other top-level search criteria. A nested query can replace
an individual search criterion in a top-level query request.

When nesting search criterion in a nested query, the operator included in the
nested query criterion determines how each nested criterion relates to the other.
Only one operator can be used at one time for a nested query.

The overall score that the nested query contributes to the top-level query
score depends on the operator specified.

criteria

The criteria defines the criterion to include in the nested query.

Refer to Search Criterion for a detailed description of how to
create a top-level query criteria.

Type: array of search criteria

operator

The operator to use between each query criteria in the nested query.

The valid values are or and and. When using or, then if ANY of the
criteria in the nested query are exact matches, the entire nested query is considered
an exact match when scored with the parent query.

When using and, then only if ALL of the criteria in the nested query are exact
matches, is the nested query considered an exact match when scored with the parent query.

Relevance scoring of a nested query depends on the operator used. When or is
specified, the score of the best-matched nested search criterion is used.
When and is specified, the sum (average) of the relevance scores
from each nested query criterion is used.

The facets criterion determines which facet count values and data are returned in the
query response. Its primary use is for faceted or guided navigation.

The key is a user-defined value that specifies the tag to use to identify
in the response which facets data applies to which facets request. This allows
for creating multiple facet count requests over the same dimension. The key specified
in the calculate will appear in the query response.

This option is a map where the keys are the facet ids and the values describe how the facet is matched.
If you are converting an index time facet to query time you would use the id attribute of the element
as the key in the map and the value attribute as the value.

How many levels of children to include. Also works with rootId.
Ignored for keyword dimensions.

Type: integer

Default: 1

rootId

When provided, the rootId will be used as the root node rather
than the true root node of the tree.
Ignored for keyword dimensions.

Type: string

Default: empty string (the tree’s true root)

dataIds

Determines the dimension element ids for which facet data should be returned
independent from the data requested in any related criteria. The ids listed
here do not impact navigation or selections.

Type: array of string

Default: empty array (none).

navChildIds

Determines which ids appear in the childIds that may not have been in the childIds
list.

Type: string

Values: remove, inplace, begin and end

Default: inplace

navChildIds types

Type

Description

remove

Never include select or whose children are select in childIds response key.

inplace

Include in the childIds but maintain the specified sort order and TopN setting.

begin

Include the childIds but at the beginning of the list.

end

Include the childIds but at the end of the list.

countType

Determines which type of count should be returned in the response. There are basically
two types of counts: those that are calculated to include the dimension’s query criterion
and those that do not. For all counts, any query criterion for other dimensions are always
applied such that the counts reflect the result set after those criteria have been applied.

Type: string

Values: exact, exactDim, fuzzy, fuzzyDim

Default: exact

Count types

Type

Description

exact

The exact counts for the dimension.

fuzzy

The fuzzy counts for the dimension.

exactdim

Same as exact except that the counts include other criteria against the same dimension.
Deprecated, use isolatedId instead.

fuzzydim

Same as fuzzy except that the counts include other criteria against the same dimension.
Deprecated, use isolatedId instead.

isolatedId

Determines whether any search criterion should be excluded as part of determining the facet counts for this criterion.

Type: string

Default: Value of dimension or the name of the key for this facets criterion, set to null or "" to disable isolation

New in version 3.16.

sortBy

Determines how the order in which the childIds and navIds should be returned. When using a sort type that
does not impose a total ordering (countAsc, countDesc, labelAsc, labelDesc) a tie breaking sort
is automatically added which is idAsc for keyword dimensions and declaredAsc otherwise.

Default: declaredAsc for dimensions which declare their facets in the dimensions file, idAsc otherwise.

sortBy types

Type

Description

Example

countAsc

Ascending count

2, 4, 9

countDesc

Descending count

9, 4, 2

idAsc

Ascending facet id (not locale sensitive)

A, B, a, b

idDesc

Descending facet id (not locale sensitive)

b, a, B, A

declaredAsc

Ascending order that the elements were declared in the
dimensions file (ignored for keyword dimensions)

first, second, third

declaredDesc

Descending order that the elements were declared in the
dimensions file (ignored for keyword dimensions)

third, second, first

labelAsc

Ascending label where the label is the id for keyword
dimensions or the value of the name attribute on the
element in the dimensions file otherwise
(locale sensitive)
attribute on the element in the dimension file otherwise

A, a, B, b

labelDesc

Descending label where the label is the id for keyword
dimensions or the value of the name attribute on the
element in the dimensions file otherwise
(locale sensitive)
attribute on the element in the dimension file otherwise

B, b, A, a

minCount

The value to use to filter the counts such that only counts with value equal to
or greater than the value will be returned. For example, to only return non-zero
counts, minCount should be 1.

Applies only to childIds lists, not navigableIds.

Type: integer

Default: 0

topN

The value to use to limit the number of counts returned such that only the
facets with the greatest counts are returned. For example, to return the
top 5 facet counts in descending count order, topN should be 5.

Type: integer

Default: 100

includeLabel

Determines if the name attribute value of the dimension element should be returned.
The name attribute can be used to create labels in the UI.
Ignored for keyword dimensions.

Type: boolean

Default: true

includeBounds

When this option is enabled against scalar type dimensions, the response
will include bounds information related to the items in the identified buckets.

Ids of dimension elements we want drilldown information for. If this value
is not set then all immediate children of the dimension specifed dimension
ids will be used.

Type: array of string

depth

How many levels of children to include.

Type: integer

Default: 0

isolated

Whether to isolate the drilldown counts for this criterion from the main
search. Practically, this means that if the search contains a criterion over
the same dimension then the counts for anything not selected won’t all be
zero.

This option is deprecated, use isolatedId instead.

Type: boolean

Default: true

isolatedId

Determines whether any search criterion should be excluded as part of determining the drilldown counts for this criterion.
Only respected if isolated is set to true.

Geographic polygons are useful to create shapes on maps in which to automatically
match. Instead of using a distance from a point on a map, polygons can identify
points inside or outside of the polygon and correctly score matches differently
if the match falls outside of the polygon.

The query API supports multiple polygons. Each polygon shape is defined by matching
arrays of latitude and longitude points.

The coordinates for non-point shapes are presented using two parallel arrays, one
for latitude and one for longitude. The n th element of each array is combined
to create the coordinate, e.g. latLng1 = new Point(latitude[0], longitude[0]),
latLng2 = new Point(latitude[1], longitude[2]), etc.

Refer to the section on geoloc query criteria for more information on other
options related to geographical searches.

The highlighting criterion specifies how to apply highlighting to matches, it works
in tandom with the properties top-level request field in that highlighted results
will be applied to the requested property values when returned in the query response.

Only text and keyword dimensions support highlighting and it is applied to
just text dimensions by default unless you specify the includeDimensions option.

If you only want to return highlighted values for specific changeset properties
then you should specify the properties to return using the properties criterion.
If no properties were specified, then all properties for the matched items
will be returned with highlighting only applied to those properties that matched
the text dimension search criterion.

The highlighting response is integrated with the properties response unless
the request includes the merge field with value none. When merge is
set to none, the response will include a highlighting field that includes
only the properties that were actually highlighted. For a
description of the properties response, refer to Properties.
For a description of the highlighting response, refer to
Highlighting.

The following fields can be specified:

includeDimensions

Only candidate dimension types used in the query that are in this list will affect highlighting.
It’s value should be one or more dimension ids.

To preserve backward compatibility this option defaults to a list of all the current text dimension ids.

Type: string or array of string

Default: array of all current text dimensions ids

excludeDimensions

Candidate dimension types used in the query that are in this list will not affect highlighting.
It’s value should be one or more dimension ids.

Type: string or array of string

Default: null

merge

The highlighted properties are normally returned in the properties response. To
return just the highlighted properties, use the merge field.

Value none indicates to return the highlighed properties in the highlighting
response. Only the properties that were actually highlighted will be included.

Type: string

Values: none | properties

Default: properties

template

The formatting to apply around highlighted words and phrases. The template consists
of pre- and post tag strings.

Type: array of string

Default: [ “<b>”, “</b>”]

fragmentType

The engine’s highlighter can return the full changeset property value with
highlighting applied or it can return fragments of the original text. Fragments
are useful when using highlighted results from long text blocks in a search
results display where screen real estate is limited.

Value none indicates to not return fragments but apply highlighting to the
original property value. Value best indicates to return the best fragments that
matched the query. When using best, the maxFragments, delimiter and
fragmentSize determine how the fragments are composed.

Type: string

Values: none | best

Default: none

delimiter

The string used to connect fragments to each other, if more than one fragment
is found. This field only applies if the highlighting criteria specifies
fragmentType is best.

Type: string

Default: ... (elipsis)

maxFragments

The maximum number of fragments to return. This field only applies
if the highlighting criteria specifies fragmentType is best.

Type: integer

Default: 10 fragments

fragmentSize

The number of characters to return in each fragment. This field only applies
if the highlighting criteria specifies fragmentType is best.

Indicates that suggestions should be ranked using more popular (relevant) terms
that have been indexed.

Type: boolean

Default: true

maxSuggestions

The maximum number of query suggestions to return. There is a limit of 20 suggestions.

Type: integer

Default: 5 suggestions

userValue

By default, the Did You Mean? process will use the value field of the enclosing
search criterion to use to suggest alternative queries. If the value is computed
from the original user’s query text, then the original query text can be placed in
this field.

Type: string

highlighting

The highlighting criteria that specify what type of highlighting to perform
on the search terms that were replaced with suggestions. To disable highlighting,
set this field to false.

The indexValues criterion determines the dimensions whose indexed values should be
returned as part of the query response. Each dimension must be requested in its own dictionary.
Multiple dimension requests are specified by requesting an array of dimension dictionaries.

The values criterion determines the dimensions whose indexed values should be
returned as part of the query response. If the id of at least one dimension appears
in this parameter, then the response will include an array of indexed values for
the specified dimension. The array of values is in the same order as the query
result item ID array.

Note: Text dimension values are not returned.

The following fields can be specified:

dimension

The id of one or more dimensions for which the indexed values are requested.

The system uses the following logic to determine the default sort order for search results:

Exact matches before fuzzy matches

Descending order of relevance

Ascending order of item-id using alphanumeric ordering

To change the sort order in any way, include one or more sortBy criterion in the query request.

The order in which sortBy criterion appear is significant. For a single
sortBy criterion, either builtin or dimension must minimally be specified.

builtin

The type of builtin dynamic value to use for the sort.

Type: string

Values: exactMatch, relevance, id or random

dimension

The dimension whose value we want to use for a sort. Only one-dimensional
scalar dimensions (integer, long, double, and time), geoloc, and keyword dimensions
may be used for sorting.

Sorting is not supported with tree, mutex, ordered, or text dimensions.

If the dimension is a geoloc dimension,
then the sorting is based on the distance from the point specified by
the latitude and longitude properties described below.

Type: string

latitude

If a geoloc dimension is used, then this parameter specifies to use the latitude
value of geo point from which to compare the item results and sort by distance. The
longitude of the point is specified using``longitude``.

Type: string

longitude

If a geoloc dimension is used, then this parameter specifies to use the longitude
value of geo point from which to compare the item results and sort by distance. The
latitude of the point is specified using``latitude``.

Type: string

distanceUnit

Determines the distance unit used when calculating distances.

Type: string

Values: miles | km

Default: miles

New in version 2.8.4.

reverse

Each builtin sort has a default sort direction: ascending or descending. To
reverse the default sort direction, set this parameter to true. All default sort directions are
ascending with the exception of exactMatch (from Exact to Fuzzy) and relevance
(descending).

Type: boolean

seed

If builtin is random, then the seed is used to create the random sequence. This parameter is optional; however to
make paginating result sets consistent, seed should be specified.

Type: double

minRelevance

If builtin random, then this specifies the minimum relevance value to generate for the sort

Type: double

maxRelevance

If builtin random, then this specifies the maximum relevance value to generate for the sort

Type: double

NOTE: Builtin type random in combination with top-level parameter exactRelevance can be used to set a relevance
score for all exact matches in the query. This combines well with the random index so that you could randomize exact
matches only (as they’d all have the same relevance) but order close matches by relevance using just one query.

The system uses the following logic to determine special groupings for search results:

To use a groupBy dimension, create a dimension on the values that will be used
in a groupBy query. When the engine executes the query, it will group the results
by the values in the associated groupBy dimension id/value. This criterion will be
ignored if you do not provide any search criteria.

The groupBy type dimension whose value we want to use for the grouping.

Type: string

groups

Array of group ids used to limit the search.

Type: array

Default: all groups

notGroups

Array of group ids to be excluded from the search.

Type: array

Default: no groups

topN

Determines that the top N values of the groupBy dimension should be presented
in descending order. Specifying a value of 0 will not return any topN group-related
information (properties, highlighting, indexValues).

This option is capped at a maximum value of 100.
See max-groupby-topn to learn about relaxing this limit.

Type: int

Default: 0

properties

Setting this field with one or more changeset property ids causes the engine
to return the associated stored property values for the named properties for
the topN items in each groupBy group. The format and behavior of this field is the same
as for the top-level request.

Type: string or array of string

Default: no properties returned.

The properties response is nested in the groups response dictionary.
For a description of the properties response, refer to Properties.

highlighting

The highlighting criteria that specify what type of highlighting to perform
and the changeset properties to return with highlighting applied for
the topN items in each groupBy group. The format and behavior of this field is the same
as for the top-level request.

The highlighting response is nested in the groups response dictionary. For a
description of the highlighting response, refer to Highlighting.

indexValues

Setting this field with one or more dimension ids causes the engine to return
the associated new-form indexed values for the specified dimensions for
the topN items in each groupBy group. The index values are
returned in a dictionary with keys for each requested dimension id. The value of the
key contains the relevant index values data. The format and behavior of this field is the same
as for the top-level request.