Response Object Schema

Response Object Schema


The status object returns the number of successful and failed pindex queries. This information is useful as you can choose to use partial results depending on your application use case. For example, you may prefer to show an incomplete list of hits for a catalog search than return an error message if some pindexes are unresponsive.

We recommend that you check the status object for failures rather than rely on the HTTP response codes alone. For example,FTS returns an HTTP 200 response in case of pindex failures or timeouts (not consistency timeouts). This is done so that you can choose to accept partial results in an application. However, this also means FTS returns an HTTP 200 response even when ALL pindexes fail.

Refer to the following table for more information about the possible status messages.
Table 1. Response Object Status Values
Status Description
HTTP 400 Returned when an error is detected when validating the inputs. The text error message accompanying the status describes the problem.
HTTP 412 Returned when the consistency requirements are not satisfied within the specified timeout. The JSON structure accompanying the status provides information about the current consistency levels.
HTTP 200 Returned when an error is detected during query execution. The errors may be contained in the JSON section named "status".
The total field returns an integer representing the total number of pindexes queried. This value varies depending on how your index is configured, the platform you're running on, and whether you are querying an index or an index alias. Each index has a setting for number of vBuckets per pindex. For example, when running on a cluster with 1024 vBuckets and with an index setting of 171 vBuckets per pindex, the total number of pindexes is 6. When you query an index alias, total is the sum of all the pindexes in each index that is included in the definition of the index alias.
This field returns the total number of pindexes successfully queried. This integer value can range from 0 to the total number of pindexes.
Example Status: Successful
 "status": {
     "total": 6,
     "failed": 0,
     "successful": 6
This field returns the total number of pindexes with failed queries. This integer value can range from 0 to the total number of pindexes. If the number is greater than 0, the response object contains an errors array.
This returns an array of error messages as reported by individual pindexes. This array only appears if the field "failed" is greater than 0.
Example Status: Failure
"status": {
        "IndexClient -":"context deadline exceeded",
         "IndexClient -":"context deadline exceeded",

Understanding the Query Response Status

This section explains the contents of a typical query response status.


The request object stores a copy of the query that was executed and other details from the request that generated this response object, for example the number of results requested (size), the offset, highlighting, and so on.

Represents the actual query that was executed.
Represents the number of results requested. The default size is 10. If the size is set to 0, the query returns the count of matches with no other results.
Results of a query are returned in the descending score order. This field specifies the offset, starting at 0 (default) for the first match, to return the results.
This object indicates whether highlighting was requested. The highlight object contains two fields:
  • style - Optional field that specifies the name of the highlighter, which can be "html", "ansi", or a custom highlighter.
  • fields - Specifies an array of field names to which highlighting is restricted.
This object contains an array of field names which must be loaded and returned with the query response. If you store a field and want it returned with the result, you must name the field here. The field names are specified as string values. While there is no field name pattern matching available, you can use an asterisk "*" to specify that all the fields must be loaded and returned with the response.
This object indicates whether faceting was requested and when requested, returns the facets. The section on Search Facets provides more information on the possible values of the facet request.
"facets": {
    "type": {
        "size": 5,
        "field": "type"
This Boolean field when set to true prints a verbose response with full scoring information.


Hits returns an array containing the matches for the executed query. The length of the array is equal to or less than the size specified in the request.

The unique ID of the pindex. The index name always begins with a string.
The document ID that matched.
The document score.
This object contains field names where matches were found. The "Locations" object depends on the term vectors being stored; if term vectors are not stored, locations are not returned in the result object.

{Field Name}

Lists the field names where the match was found. These fields are scoped so that "description: american" searches for "american" scoped to the "description" field. In the example below, there are two fields named "description" and "name".

{Term Found}

A name value pair whose name is the name of the term that was found and whose value is an array on objects representing the vector information that describes the position of the matched term in the field. This value is only present if the term vectors are calculated. For each match, the object contains the position (pos), start, end, and array positions (array_positions).

Sample Locations Fragment
"locations": {
    "reviews.content": {
        "light": [
                "pos": 277,
                "start": 1451,
                "end": 1456,
                "array_positions": [
               "pos": 247,
               "start": 1321,
               "end": 1326,
               "array_positions": [
These objects, also known as snippets, contain field names that contain an array of one or more text strings. The text strings contain the " <mark>" tags surrounding the term that was matched in order to render highlighting.
This object returns the value of the field that was matched. However, unlike the Fragments field, this does not have any tags to render highlighting.
This field contains an array of one or more values that were used to sort the search results. Documents that don't have a value in the index for a particular field used in sorting will return a series of non-printable Unicode characters: \ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd\ufffd.


Facets return an object that contains aggregated information about the documents that match a query. There are three types of queries: Numeric Range Facet, DateTime Range Facets, and Terms Facets. For more information on facets, see Search Facets.


Total hits represents the total number of matches for this result. It can be any integer starting from 0.


Max score represents the highest score of all documents for this query.


Time taken to complete the query.
"total_hits": 56,
"max_score": 0.8041158525040355,  
"took": 1449005,