JSON¶

The engine expects JSON to be sent via HTTP POST with the Content-Type header set to application/json. Both the request and response are dictionaries.

http://server:port/ws/query

For releases prior to 3.8.2, the URL was: http://server.port/json/query

Information about JSON can be found at http://json.org.

Top Level Request Fields¶

startIndex

The index of the item in the result set at which to begin the page.

Type: int

Default: 0

pageSize

The maximum number of items in the returned response result set. If the value is 0 then no results are returned at all, only summary information about the query is returned.

Type: int

Default: 0

items

Array of item ids over which to search.

Type: array

Default: all items

notItems

Array of item ids to be excluded from the search.

Type: array

Default: no items

criteria

Search criteria as a list of criterion.

Type: array of dictionaries

See: Search Criterion

facets

The facets criteria that specify on which buckets we want to calculate facets counts.

Type: dictionary

See: Facets Criterion for a detailed description of the facets API.

For a description of the facets response format, refer to facets Response.

drillDown

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.

Type: array of dictionaries

See: Drilldown Criterion for a detailed description of the drilldown API.

For a description of the drilldown response format, refer to drillDown.

sortBy

The sorting criteria that specify the order in which items appear in the query results.

Type: array of dictionaries

See: Sort By Criterion

groupBy

The groupBy criteria that specify how matching items are grouped in the query results.

Type: dictionary

See: Group By Criterion for a description of the groupBy request API.

For a description of the groupBy response, refer to Groups.

exactMatchesOnly

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.

Type: string or array of string

For a description of the properties response, refer to Properties.

New in version 2.8.3.

highlighting

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.

Type: dictionary

See: Highlighting Criterion for a description of the highlighting request API.

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.

Type: array of dictionary

See: indexValues Criterion for a description of the indexValues request API.

For a description of the indexValues response, refer to Index Values.

New in version 2.9.1.

values

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.

Type: string or array of string

See: Values Criterion for a description of the values request API.

For a description of the values response, refer to Values.

calculate

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.

Type: dictionary of calculate criteria

See: Calculate Criterion for a description of the calculate criterion request API.

For a description of the calculate response, refer to Calculate.

New in version 3.1.0.

explain

Setting this option with one or more directives causes the engine to return information about how each search criterion and indexed values contributed to the query result.

Transparensee Systems reserves the right to alter or remove this API in any way and at any time in the future. It provides this feature solely for debugging purposes.

Type: string

See: Explain for a detailed description of the explain API.

For a description of the explain response format, refer to Explain.

renderParameters

Setting this option causes the engine to return a URL-encoded query string that represents the query results and can be passed directly to a template for rendering of search results.

Type: boolean or dictionary.

See: Render Parameters for a detailed description of the renderParmeters API.

For a description of the renderParameters response format, refer to renderParmeters.

New in version 2.6.17.

Search Criterion¶

The following can be specified for each criterion:

dimension

Dimension to use.

Type: string

The following can be specified if the dimension includes nested element tags.

id

Single dimension element id or array of element ids for the dimension nodes you want to match against.

Note: Not applicable to text type dimensions.

Type: any or array of any

notId

Single id or array of ids for the dimension nodes you do not want to match against.

Type: any or array of any

value

Single value or array of values where the values can be strings, numbers, date/times or ranges of either.

When the value or range includes a time value, then the time value must be formatted using the same format as specified in the Time Type (Scalar) dimension declaration.

Ranges for integer, double and time type dimensions can be specified using Interval Notation.

Type: string, int, double, formatted date/time string, string or array of any

notValue

Single value or array of values that should be excluded from the criterion. Items will be culled from the query results.

Type: depends on the data type of the dimension

weight

Optional weight to apply to this criterion during the scoring phase. Setting a lower weight makes this criterion less important.

Type: double

Constraints: must be in the range [0,1]

Default: 1.0

cull

Explicitly remove items from the result set that have no relevance under this dimension.

For integer, double and time type dimensions, note that culling on these dimensions is performed on min and max, not on value.

Type: boolean

Default: false for tree, keyword and text dimensions, true for all others.

isolatedId

Optional isolation override for this criterion, used by the DrillDown and Facets APIs. Facet isolation only works for top-level AND criterion.

This defaults to the same value as the dimension property which enables isolation. To disable isolation, set this property to null or "".

When a valid isolatedId can be obtained for a criterion, then that criterion will be excluded from the query when generating drilldown or facet counts.

Type: string

Default: Value of dimension, set to null or "" to disable isolation

searchStyle

For keyword and text dimensions this key determines the style of search to perform. The values are startsWith, lastWordStartsWith or exact.

For text type dimensions, startsWith applies to any analyzed word in a query. lastWordStartsWith only applies starts with logic to the last word in a multi-word query when using the word query parser.

Type: string

Values: exact, startsWith, lastWordStartsWith (text type only)

Default: exact

searchStyle types

Type	Description
exact	Applies text analysis rules but does not perform “starts with” searches.
startsWith	Searches every analyzed term using “starts with”
lastWordStartsWith	Only performs “starts with” searches for the last word of the query. Text type dimensions only.

Sample criterion:

"criteria":
[
    {
    "dimension": "state_name",
    "value": "New",
    "searchStyle": "startsWith"
    }
]

minStartsWithLength

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.

Type: double

Default: use built-in relevance algorithms

Sample criterion:

"criteria":
[
    {
        "dimension": "genre",
        "id": "drama",
        "cull": true,
        "exactRelevance": 1.0
    }
]

fuzzyRelevance

Determines the relevance score override to apply to any fuzzy (not-exact) matches for this criterion. This field is often used in combination with exactRelevance and nullRelevance.

Type: double

Default: use built-in relevance algorithms

Sample criterion:

"criteria":
[
    {
        "dimension": "genre",
        "id": "drama",
        "cull": true,
        "exactRelevance": 1.0,
        "fuzzyRelevance": 0.5
    }
]

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.

Type: double

Default: not set

Sample criterion:

"criteria":
[
    {
        "dimension": "gender",
        "value": "M",
        "weight: 0.5,
        "cull": false,
        "exactMatch": true,
        "nullExactMatch": true,
        "exactRelevance": 1.0,
        "fuzzyRelevance": 0.5,
        "nullRelevance": 0.25
    }
]

didYouMean

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.

New in version 2.9.

"criteria":
[
    {
        "dimension": "birth_year",
        "min": 1945,
        "max": 2010,
        "value": "[,2010]"
    }
]

Birthdate is a time dimension defined as follows

<dimension id="birthdate" type="time" format="yyyy-MM-dd" />

"criteria":
[
    {
        "dimension": "birthdate",
        "min": "1945-01-01",
        "max": "1960-12-01"
        "value": "[\"1955-06-30\",\"1959-08-31\"]"
    }
]

"criteria":
[
  {
    "dimension": "location",
    "latitude": 41.3433,
    "longitude": -165.9899
  }
]

"criteria":
[
  {
    "dimension": "location",
    "latitude": 41.3433,
    "longitude": -165.9899,
    "distanceUnit": "miles"
    "isoRelevanceDistance": [0.25, 3, 10]
  }
]

"criteria":
[
  {
    "dimension": "location",
    "shapes":
      [
        {
          "latitude":  [34.7899,     45.6766,  33.6444,  44.5565],
          "longitude": [112.34566, 112.24566, 112.5677, 112.5689]
        }
      ]
  }
]

"criteria":
[
    {
        "dimension": "location",
        "latitude": 41.3433,
        "longitude": -165.9899,
        "exactDistance": 30
    }
]

{
  "builtin": "random",
  "seed": 123456789,
  "minRelevance": 0.0,
  "maxRelevance": 1.0
}

"criteria":
[
    {
        "dimension": "full_text",
        "value": "mandolin",
        "searchStyle": "startsWith",
        "minStartsWithLength": 3,
        "expandPhrases": true,
        "ignoreFieldLength": true
    }
]

"criteria":
[
    {
        "dimension": "description",
        "value": "dec",
        "searchStyle": "startsWith",
        "fields": "title,keywords",
        "fieldBoosts":
        {
            "title": 1.5,
            "keywords": 1.0
        }
    }
]

{
  "title": 10.5,
  "body": 0.5
}

Nested Queries¶

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.

Type: string

Sample nested query:

In this example, the query would be read as follows:

find all items where

Paid=1
AND Beds=2
AND (
      City_ID = 111714-60
    OR
    (
      Location.latitude = 37.040028
      AND
      Location.longitude = -76.360235
    )
  )
AND (
      Zip = 11174
      AND
      Neighborhood = Chelsea
    )

In JSON notation...

{
    "startIndex": 0,
    "pageSize": 10,
    "criteria": [
        {
            "dimension": "Paid",
            "value": 1,
            "weight": 1
        },
        {
            "dimension": "Beds",
            "value": 2,
            "weight": 1
        },

Nested query starts here in which ANY criterion may be met

{
    "operator": "or",
    "criteria": [
        {
            "dimension": "City_Id",
            "value": "111714-60",
            "cull": true,
            "weight": 1
        },
        {
            "dimension": "Location",
            "latitude": 37.040028,
            "longitude": -76.360235,
            "cullDistance": 10,
            "exactMatch": false,
            "weight": 1
        }
    ]
},

Another nested query starts here in which BOTH criterion must be met

        {
            "operator": "and",
            "criteria": [
                {
                    "dimension": "Zip",
                    "value": "11174",
                    "weight": 1
                },
                {
                    "dimension": "Neighborhood",
                    "value": "Chelsea",
                    "exactMatch": false,
                    "weight": 1
                }
            ]
        }
    ]
}

Facets Criterion¶

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.

For a description of the facets response format, refer to facets Response.

The following fields can be specified in the dictionary:

dimension

The dimension to use for the facet counts. If this field is omitted, then the dimension name is assumed to be the same as they key name.

Type: string

Default: The name of the key.

navigable

For tree type dimensions, determines whether automatic node navigation is applied.

Type: boolean

Default: true.

depth

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

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.

Type: string or array or string.

Values: countAsc, countDesc, declaredAsc, declaredDesc, idAsc, idDesc, labelAsc, labelDesc

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.

Type: boolean

Default: false

Sample criterion:

{
  "facets": {
    "category": {
      "minCount": 1,
      "topN": 20
    }
  }
}

Isolated example:

{
  "criteria": [
    {"dimension": "type", "id": "article"},
    {"dimension": "category", "isolatedId": "cat", "id": "765"}
  ]
  "facets": {
    "category": {
      "isolatedId": "cat",
      "includeLabel": true
    }
  }
}

Drilldown Criterion¶

This is a deprecated API that is replaced by the facets top-level request.

The following can be specified for each facets criterion. Note that facets have a cost query time. It is recommended to calculate facet counts only for values that are pertinent to the application.

For a description of the facets response format, refer to drillDown.

See also Querying with drill down counts.

dimension

The dimension over which we want drilldown information.

Type: string

ids

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.

Type: string

Default: Value of dimension, set to null or "" to disable isolation

Example:

{
  "drillDown": [
    {
      "dimension": "category"
    },
    {
      "dimension": "genre"
      "ids": ["a", "b", "c", "d", "e"]
    }
  ]
}

Isolated example:

{
  "criteria": [
    {"dimension": "type", "id": "article"},
    {"dimension": "category", "isolatedId": "cat", "id": "765"}
  ]
  "drillDown": [
    {
      "dimension": "category",
      "isolatedId": "cat
    }
  ]
}

Geographic Polygons¶

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.

latitude

The latitudes of a polygon.

Type: array of double

longitude

The longitudes of a polygon.

Type: array of double

Sample criterion:

"criteria":
[
  {
    "dimension": "location",
    "shapes":
      [
        {
          "latitude":  [34.7899,     45.6766,  33.6444,  44.5565],
          "longitude": [112.34566, 112.24566, 112.5677, 112.5689]
        },
        {
          "latitude":  [45.7899,     44.6766,  44.6444,  45.5565],
          "longitude": [112.34566, 112.24566, 112.5677, 112.5689]
        }
      ]
  }
]

Highlighting Criterion¶

The highlighting criterion specifies how to apply highlighting to matches against tree, text dimensions. The criterion works along 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.

If you only want to return highlighted values for specific changeset properties then you should specify the properties to return using the properties crtierion. 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.

Highlighting of text type dimensions is done inline with the output, effectively adding marker text around the match. Text type highlighting can be configured by specifying a template that determines formatting such as HTML.

The following fields can be specified:

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

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>”]

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.

Type: integer

Default: 100 characters

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)

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

excludeDimensions

When highlighting is enabled, all candidate dimension types used in the query will be included in the highlighting response if there was something to highlight.

To exclude one or more dimensions from the highlighting process, use this attribute. The values should be one or more dimension ids.

Type: string or array of string

Default: all dimensions are included

Sample query:

{
  "startIndex": 0,
  "pageSize": 10,
  "highlighting": {
    "fragmentType": "best",
    "maxFragments": 4,
    "delimiter": "...",
    "template": [ "<b>", "</b>" ],
    "fragmentSize": 100,
    "excludeDimensions": "job_title"
  },
  "criteria": [
    {
      "dimension": "fulltext",
      "value": "Tom Jones"
    }
  ]
}

DidYouMean Criterion¶

The didYouMean criterion specifies how to apply didYouMean to the enclosing search criterion against text dimensions.

For a description of the didYouMean response, refer to DidYouMean.

The following fields can be specified:

distanceAlgorithm

The Did You Mean processor can be customized to use generally recognized word distance algorithms to determine word similarities and mispellings.

For more information on the various word distance algorithms, refer to these URLs.

http://en.wikipedia.org/wiki/Levenshtein_distance

http://en.wikipedia.org/wiki/Jaro–Winkler_distance

http://en.wikipedia.org/wiki/Ngram

Type: string

Values: levenshtein | bigram | trigram | jarowinkler

Default: levenshtein

morePopular

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.

Type: boolean or dictionary

Default: false

See: Did You Mean? Highlighting Criterion for a description of the highlighting request API for Did You Mean?

escapeHtml

Sanitizes input from a user by stripping out HTML that poses a security vulnerability, namely: “<” becomes “&lt;”, “>” becomes “&gt;” and “&” becomes “&amp;”.

Type: dictionary

See: Did You Mean? Highlighting Criterion for a description of the highlighting request API for Did You Mean?

Sample query:

{
  "startIndex": 0,
  "pageSize": 10,
  "criteria": [
    {
      "dimension": "fulltext",
      "value": "Tom Jones",
      "maxSuggestions": 2,
      "didYouMean": {
          "morePopular": "false",
          "highlighting": {
              "template": [ "<i>", "</i>" ],
          }
      }
    }
  ]
}

Did You Mean? Highlighting Criterion¶

The highlighting criterion for Did You Mean? specifies how to format highlighting to the suggested terms in a user’s query..

template

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

Type: array of string

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

indexValues Criterion¶

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.

For a description of the indexValues response, refer to Index Values.

Note:

Only tree, mutex, ordered, keyword, integer, double, time, geoloc, text type dimensions are currently supported.

The following fields can be specified in the dimension dictionary:

dimension

The id of a dimension for which the indexed values are requested.

Type: string or array of string.

hitDetection

Determines whether or not match hit detection is enabled.

Type: boolean.

Default: false.

includeLabel

Determines whether or not the value of the dimension element name attribute is returned as well as the id. This feature makes it possible to translate coded values to readable forms for use in the UI.

Type: boolean.

Default: false.

Sample query:

{
  "indexValues": [
     {
       "dimension": "genres",
       "hitDetection": "true",
       "includeLabel": "true"
     }
  ]
}

Calculate Criterion¶

The calculate criterion determines which calculated values are returned in the query response.

For a description of the calculate response, refer to Calculate.

The key is a user-defined value that identifies the tag to use in the query response. The key specified in the calculate will appear in the query response.

The following fields can be specified in the user-defined key dictionary:

method

The name of the calculation method. Only value distance is currently supported. Distance supports calculated values for each item in the query result.

Type: string.

Values: distance

dimension

The dimension to use whose values contain the item’s location, e.g. latitude and longitude.

Type: string

distanceUnit

The unit of distance to use when creating the distance values.

Type: string

Values: miles | km

longitude

The longitude of the point against which to calculate the distance.

Type: double or array of double.

latitude

The latitude of the point against which to calculate the distance.

Type: double or array of double.

Sample query:

{
  "calculate":
     {
       "distanceFromSchool": {
          "method": "distance",
          "dimension": "house_location_geoloc",
          "distanceUnit": "km",
          "longitude": "-70.3",
          "latitude": "43.455"
     }
}

Values Criterion¶

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.

Type: string or array of string.

For a description of the values response, refer to Values.

Sample query:

{
  "values": [
    "genres",
    "ethnicity"
  ]
}

Sort By Criterion¶

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 displaying the explain distances used to order the results. Refer to Explain for more information.

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.

For example:

{
  "startIndex": 0,
  "pageSize": 20,
  "exactRelevance": 1.0,
  "sortBy":
    [
        {
          "builtin": "random",
          "seed": 123456789,
          "minRelevance": 0.0,
          "maxRelevance": 1.0
    }
  ]
}

Group By Criterion¶

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.

For a description of the groupBy response, refer to Groups.

See also: Group By Type.

dimension

The groupBy type dimension whose value we want to use for the grouping. Text dimensions may not be specified.

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, highlihting, indexValues).

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.

See: Highlighting Criterion for a description of the highlighting request API.

Type: dictionary

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.

Type: array of dictionary

See: indexValues Criterion for a description of the indexValues request API.

The indexValue response is nested in the groups response dictionary. For a description of the indexValues response, refer to Index Values.

legacyGroupBy

Determines whether the response should be returned in a pre-version 3.0 format or not.

Type: boolean

Default: true

For example:

  {
    "criteria": [
      {
        "dimension": "price",
        "value": 3
      }
    ],
    "groupBy": {
      "dimension": "shape-group"
    },
    "pageSize": 10,
    "startIndex": 0
  }

or

  {
    "criteria": [
      {
        "dimension": "price",
        "value": 3
      }
    ],
    "groupBy": {
      "dimension": "shape-group",
      "topN": 3
    },
    "pageSize": 10,
    "startIndex": 0
  }

Explain¶

Returns information about the contribution of each request criteria as it pertains to the entire query. The response returned by explain can be very long. For convenience, similar types of explain information can be requested using a composite value or a comma-delimited list of explain directives specifying which information to return.

Transparensee Systems reserves the right to alter or remove this API in any way and at any time in the future. It provides this feature soley for debugging purposes.

For a description of the explain response format, refer to Explain.

Default: none

To cherry-pick which explanations to return, create a space or comma-delimited string using one or more of the following case-insensitive explain directives:

To return all explanations:

{
  "startIndex": 0,
  "pageSize": 20,
  "explain": "all"
}

To cherry-pick explanations:

{
  "explain": "queryTime,partialRelevances"
}

To include all and cherry-pick what to remove, place a “-” before the parameter:

{
  "explain": "all -time"
}

or

{
  "explain": "all -time"
}

Render Parameters¶

If set as a boolean then this either enables or disables the output of render parameters in the results. Passing in an empty dictionary has the same effect as true.

renderParmeters is used primarily for integration with the Transparensee jQuery widget suite.

For a description of the renderParameters response format, refer to renderParmeters.

The following fields can be specified:

itemIdsDelimiter

The delimiter to use when concatenating the itemIds from the response into the itemIds URL query parameter value.

Type: string

Default: space

Sample queries:

{
  "renderParameters": true
}

{
  "renderParameters": {
    "itemIdsDelimiter": ","
  }
}

For a description of the renderParameters response, refer to renderParmeters.