API Extensions

Bi-metric Scores

If bi-metric scoring is enabled, all the result item API object gets extended by a bi-metric score map, containing scores for each individual scoring concept, and a total bi-metric score (name: bimetricScore).

They can be used by a UI to give more detailed feedback on how results match the request. Furthermore, it is possible that way to adjust the concept weighting and recalculate bi-metric scores on the fly.

Score Thresholding

If bi-metric scoring is enabled, Search additionally provides a suggested score threshold in the search results object. This value is a best-effort estimate, aiming to provide a threshold for eliminating possibly bad results for automatic work-flows. Like any search engine, Search provides a ranking of results based on the query, but usually no cut-off threshold for possibly bad results. With bi-metric scoring enabled, Search has more and better features to compute a suitable threshold based on the given query and result set.

A threshold is only provided, if the search request meets the following criteria: - The query contains a minimal number of important Match concepts, like a jobtitle, a work field, or skills. - The query needs to contain at least 2 non-required query parts on different fields. - The request does not contain a sorting, so that results are sorted by relevance. - The request does not contain any page offset (searchAfter / resultOffset fields).

The threshold can be used by the integrating application to filter out results having a score (not a bi-metric score) below the threshold. Search will not do the actual filtering itself.

Example

{
  "matchSize": 441,
  "hasMoreResults": true,
  "resultItems": [...],
  "queryParts": [...],
  "newQueryParts": [...],
  "isOrCombined": false,
  "facetCounts": [...],
  "synonyms": { "skill:java": [...] },
  "searchEngine": "internal",
  "suggestedScoreThreshold": 0.28,
  "warning": [...],
  "queryContext": {...},
  "searchAfter": [...]  
}

Sorting and Pagination

Search supports sorting on bi-metric scores with a few important limitations:

• Only the first page of search results can be sorted by bi-metric scores. Search requests with resultOffset > 0 or a searchAfter vector, will have assigned bi-metric scores, but are sorted by TK scores only.
• Sorting can be applied in ascending or descending order on any of the concept scores or the bi-metric total score. The resultSorting needs to refer to that concept using the field attribute. The concept name needs to get prefixed by _bimetric.. E.g. "field": "_bimetric.JOB_TITLE" or "field": "_bimetric.BIMETRIC_SCORE".

Example

{
  "sorting": {
    "field":"_bimetric.BIMETRIC_SCORE",
    "order":"DESCENDING"
  }
}