Query Response Properties

This article provides reference documentation for the JSON body of a successful query response.

Full reference documentation for accessible Search API endpoints is also available (see Search API - Reference Documentation).

RestQueryResponse

totalCount (Integer)

The total number of items matching the query for the current user (security trimming applied).

Note: When logging a Search usage analytics event for a query, the numberOfResults field of that event should be set to the totalCount value of the query (for reporting purposes).

Sample value: 250

totalCountFiltered (Integer)

The total number of items matching the query for the current user (security trimming applied) after duplicate filtering has been applied (see the duplicateFiltering query parameter).

Sample value: 245

duration (Integer)

The requestDuration added to the computing time (in milliseconds) that was required by the Search API.

Sample value: 1235

indexDuration (Integer)

The time (in milliseconds) that was required by the index to find the query items.

Sample value: 1175

requestDuration (Integer)

The indexDuration added to the time (in milliseconds) that was required to establish a connection between the Search API server and the index server.

Sample value: 1181

searchUid (String)

The query UUID. Each query sent to the Search API has its own randomly generated searchUid.

Note: When logging a Search or Custom usage analytics event for a query, or a Click usage analytics event for an opened query result item, the searchQueryUid field of that event should be set to the searchUid value of the query response.

Sample value: a0e4773c-39c3-423c-90cd-c03a640ecde5

pipeline (String)

The name of the query pipeline that processed the query (see the pipeline query parameter).

Sample value: CustomerQueryPipeline

apiVersion (Integer)

The version of the Search API that sent the query.

Sample value: 2

exception (RestException, Optional)

The exception object that was returned by the index, if any.

isFallbackToAdmin (boolean, Optional)

Whether the admin session ID was allowed and used by the Coveo for Salesforce search engine. The value will be set to true when it is the case, and might be absent or set to false otherwise.

Sample value: true

warnings (Array of strings, Optional)

The errors that did not make the query fail, but should be addressed. They might be security issues, deprecated behaviors, or any other kind of concern.

Sample value: 1000 left queries before license limit

errors (Array of strings, Optional)

The errors that critically changed the query behaviour. These should be addressed right away to prevent future errors.

Sample value: The organization has no registered endpoints

index (String)

The identifier of the index mirror against which the query was executed (see the indexToken query parameter).

Sample value: mycoveocloudv2organizationid-cqjd206sta1xb9qyxfhhnsu294-Indexer-2-9rbfxhp1n07cth80ckzeh3zotc

indexToken (String)

The Base64 encoded identifier of the index mirror against which the query was executed (see the indexToken query parameter).

Sample value: bXljb3Zlb2Nsb3VkdjJvcmdhbml6YXRpb25pZC1jcWpkMjA2c3RhMXhiOXF5eGZoaG5zdTI5NC1JbmRleGVyLTItOXJiZnhocDFuMDdjdGg4MGNremVoM3pvdGM=

triggers (Array of RestTriggerResponse)

The actions to perform by the client based on the Trigger statements defined in query pipelines (see the pipeline query parameter).

Note:

A Trigger statement must have a condition. Otherwise, the Search API ignores it and does not include it in the triggers array of the query response (see Managing Query Pipeline Triggers).

termsToHighlight (Object)

The terms to highlight in each query result item. Includes all basic query expression keywords, as well as any word stemmed from a basic query expression keyword (see the q query parameter), unless this keyword was preceded by the no stemming Coveo Cloud query syntax operator (+).

Sample value: {"coveo": [], "cloud": ["clouds"], "v2": [], "platform": ["platforms"]}

phrasesToHighlight (Object)

The phrases to highlight in each query result item. This property is populated when the basic query expression (see the q query parameter) contains one or several exact phrase match requests (terms between double quote characters).

Sample value: {"cloud v2": {"cloud": [], "v2": []}},

queryCorrections (Array of RestQueryCorrection)

The query corrections suggested by the index, if the enableDidYouMean query parameter was set to true.

refinedKeywords (Array of Strings)

The refined keywords used by the Coveo ML automatic relevance tuning model.

Sample value: ["v2", "platform", "cloud", "coveo"]

groupByResults (Array of RestGroupByResult)

The Group By results returned by the query. These results are included in the order they were requested in the groupBy query parameter.

categoryFacets (Array of RestCategoryFacet)

Hierarchical data results corresponding the to hierarchical data in the query.

results (Array of RestQueryResult)

The items returned for the query.

RestQueryResponse Sub-Models

This section provides reference documentation for the RestException, RestTriggerResponse, RestQueryCorrection, RestWordCorrection, RestGroupByResult, RestGroupByValue, RestCategoryFacet, RestQueryResult, and RestHighlightResponse query submodels.

RestException

code (String)

Exception code returned by the index.

This value is an exception code that can be generated by the index under certain circumstances, such as when a query is invalid, etc.

Sample value: 408

context (string, Optional)

Context value related to the exception.code.

This value holds additional context about the exception that was raised in the index during query execution. If no exception was raised, this value won’t be present.

Sample value: NoEndpointsException

RestTriggerResponse

type (String)

The type of Coveo Cloud query pipeline Trigger statement (see Managing Query Pipeline Triggers).

Sample value: notify

content (Object)

The content of the Coveo Cloud query pipeline Trigger statement.

The content type will be a string for any type of Trigger except execute, in which case, content type will be an object with the following properties:

  • name (string): the name of the function to execute (e.g., myFunction).
  • params (array): the arguments to pass to the function (e.g., [1, \"foo\"].

Sample value: Customer query executed.

RestQueryCorrection

correctedQuery (String)

The resulting query expression correction suggestion.

Sample value: The search box

wordCorrections (Array of RestWordCorrection)

The word correction suggestions.

RestWordCorrection

offset (Integer)

The offset (in number of characters) of the corrected word, from the beginning of the resulting query expression correction suggestion.

Sample value: 4

length (Integer)

The length (in number of characters) of the corrected word.

Sample value: 5

originalWord (String)

The original, un-corrected word.

Sample value: saerch

correctedWord (String)

The suggested word correction.

Sample value: search

RestGroupByResult

field (String)

The field on which the Group By operation was executed.

Sample value: @author

values (Array of RestGroupByValue)

The resulting Group By values.

globalComputedFieldResults (Array of Numbers)

The global computed fields that were processed by the index.

Sample value: [0]

RestGroupByValue

value (String)

The Group By value name.

Sample value: Bob Jones

numberOfResults (Integer)

The number of query result items having this field value.

Sample value: 42

score (Integer)

The Group By value score, computed from the numberOfResults value as well as from the position of the items having this value in the ranked query result set.

Sample value: 0

valueType (String)

The type of Group By value.

Sample value: Standard

computedFieldResults (Array of Numbers)

The results of the computed fields (see the computedFields Group By parameter).

Sample value: 243.72

RestCategoryFacet

field (String)

The name of the field in which to look for hierarchical values.

Note: You must ensure that the Multi-value facet option is enabled for this field in your index (see Add or Edit Fields).

Example: @categories

path (Array of strings, Optional)

The retrieved sequence of hierarchical field values.

Sample value: ["Doors", "Metal"]

maximumNumberOfValues (integer, Optional)

The maximum number of values to return.

Default: 10

injectionDepth (integer, Optional)

The maximum number of query result items to scan.

Note: Specifying a high injectionDepth value can negatively impact query performance.

Default: 1000

delimitingCharacter (string, Optional)

The character to use to split field values into a hierarchical sequence.

Example:

For a multi-value field containing the following values:

c; c>folder2; c>folder2>folder3;

The delimiting character is >.

Default: |

Sample value: >

RestQueryResult

This section describes the members of the structure holding information about a single result. Results are returned in an array through the results member of the top-level response.

title (String)

The item title.

Note: When logging a Click usage analytics event for an opened query result item, the documentTitle field of that event should be set to the title value of the opened query result item.

Sample value: Differences between Coveo Cloud V2 and V1

uri (String)

The item URI.

Notes:

  • Avoid using the uri value to create hyperlinks to the item. Use the ClickUri value instead.
  • When logging a Click usage analytics event for an opened query result item, the documentUrl field of that event should be set to the uri value of the opened query result item.

Sample value: https://example.com/Root:0/topic:898/post:2

printableUri (String)

The human readable item URI.

Note: Avoid using the printableUri value to create hyperlinks to the item. Use the ClickUri value instead.

Sample value: https://example.com/topic:898/post:2

clickUri (String)

The hyperlinkable item URI.

Notes:

  • Use the clickUri value when you want to create hyperlinks to the item, rather than the uri or printableUri value.
  • The clickUri value is not necessarily unique for each item.

Sample value: https://example.com/t/1/898/2

uniqueId (String)

The unique item identifier. You should consider the uniqueId value as an opaque string.

Sample value: 84.72597$https://example.com/Root:0/Topic:898/Post:2

excerpt (String)

The contextual excerpt generated for the item (see the excerptLength query parameter).

Sample value: ... the new Coveo Cloud V2 and Coveo Cloud V1 ... the main differences between the two Coveo Cloud versions ...

firstSentences (String)

The first sentences retrieved from the item (see the retrieveFirstSentences query parameter).

Sample value: Hello, I know Coveo currently hosts organizations in two independent cloud platforms, the new Coveo Cloud V2 and Coveo Cloud V1, the original Coveo offering in the cloud. I would like to learn the main differences between the two Coveo Cloud versions ...

summary (String)

The item summary (see the summaryLength query parameter).

Sample value: Document

flags (String)

The flags that are set on the item by the index. Distinct values are separated by semicolons.

Sample value: HasHtmlVersion;HasMobileHtmlVersion

hasHtmlVersion (Boolean)

Whether the index contains an HTML version of this item.

Sample value: true

hasMobileHtmlVersion (Boolean)

Whether the index contains a mobile HTML version of this item.

Sample value: false

score (Integer)

The total ranking score computed for the item (see the sortCriteria and rankingFunctions query parameters).

Sample value: 1626

percentScore (Number)

The item ranking score expressed as a percentage (see the sortCriteria and rankingFunctions query parameters).

Sample value: 90.7539

rankingInfo (String)

The raw debug information generated by the index to detail how the item was ranked. This property is null unless the debug query parameter is set to true.

Example: Document weights:\nTitle: 0; Quality: 180; Date: 596; Adjacency: 0; Source: 500; Custom: 350; Collaborative rating: 0; QRE: 0; Ranking functions: 0; \n\nTotal weight: 1626

rating (Number)

The item rating (see the enableCollaborativeRating query parameter).

Note: Unless collaborative rating is enabled for your index, the value of this property is always 3.

Sample value: 3

isTopResult (Boolean)

Whether the item score was boosted by a featured result rule in the query pipeline.

Sample value: false

isRecommendation (Boolean)

Whether the item score was boosted as a Coveo ML recommendation.

Sample value: false

rankingModifier (string, Optional)

If applicable, represents the type of ranking modification that was applied to this result.

Note: When logging a Click usage analytics event for an opened query result item, the rankingModifier field of that event should be set to the rankingModifier value of the opened query result item, if available.

Sample value: TopResult

parentResult (Object)

A reference to the parent of this item, if result folding was applied (see the filterField query parameter). The query results contained in this field will have both their parent and child results set to null.

Sample value: {}

childResults (Array of Objects)

An array of references to the children of this item, if result folding was applied (see the filterField query parameter). The query results contained in this field will have both their parent and child results set to null.

Sample value: [{}]

totalNumberOfChildResults (Integer)

The total number of children available in the index for this item, if result folding was applied (see the filterField query parameter).

Sample value: 0

absentTerms (Array of Strings)

The basic query expression terms which this query result item does not match.

Note:

This property is populated by terms from the query pipeline-processed q value (not from the original q value).

Sample value: ["platform", "native", "solution"]

raw (Object)

The values of the fields which were retrieved for this item (see the fieldsToInclude and fieldsToExclude query parameters).

Sample value: {"clickableuri": "https://example.com/t/1/898/2", "author": "Anonymous", "date": 1502796809427, "filetype": "forumpost", "language":["English"], "conversationid": 898, "messageid": 2, "childid": 2, "adjustednumberoflikes": 46}

titleHighlights (Array of RestHighlightResponse)

The length and offset of each word to highlight in the item title string.

firstSentencesHighlights (Array of RestHighlightResponse)

The length and offset of each word to highlight in the item firstSentences string.

excerptHighlights (Array of RestHighlightResponse)

The length and offset of each word to highlight in the item excerpt string.

printableUriHighlights (Array of RestHighlightResponse)

The length and offset of each word to highlight in the item printableUri string.

summaryHighlights (Array of RestHighlightResponse)

The length and offset of each word to highlight in the item summary string.

RestHighlightResponse

length (Integer)

The length (in number of characters) of the word to highlight.

Sample value: 5

offset (Integer)

The 0-based index position of the first character of the word to highlight in the string.

Sample value: 15

Recommended Articles