• [+] expand all

Default JSON Result Format

The default JSON result format is used when presentation.format is unset or set to json. Results are rendered with one or two objects:

  • root: mandatory object with the tree of returned data
  • trace: optional object for metadata about query execution

Refer to the query API guide for result and tracing examples.

All object names are literal strings, the node root is the map key "root" in the return JSON object, in other words, only strings are used as map keys.

Element Parent Mandatory Type Description
root yes Map of string to object The root of the tree of returned data.
children root no Array of objects Array of JSON objects with the same structure as root.
fields root no Map of string to object
totalCount fields no Integer Number of hits.
coverage root no Map of string to string and number Metadata about how much of the total corpus has been scanned to return the given documents.
coverage coverage yes Integer Percentage of total corpus scanned.
documents coverage yes Long The number of documents scanned.
full coverage yes Boolean Whether the full corpus was scanned.
nodes coverage yes Integer The number of search instances used executing the query.
results coverage yes Integer The number of results merged creating the final rendered result.
resultsFull coverage yes Integer The number of full result sets merged.
degraded coverage no Map of string to object Indicator of match-phase degradation.
match-phase degraded no Boolean Indicator whether match-phase degradation has occurred.
timeout degraded no Boolean Indicator whether the query timed out before completion.
adaptive-timeout degraded no Boolean Indicator whether the query timed out with adaptive timeout before completion.
non-ideal-state degraded no Boolean Indicator whether the content cluster is in ideal state.
errors root no Array of objects

Array of error messages with the fields given below. Example.
code errors yes Integer Numeric identifier used by the container application. See error codes and ErrorMessage.java for a short description.
message errors no String Full description.
source errors no String Which data provider logged the error condition.
stackTrace errors no String Stack trace if an exception was involved.
summary errors yes String Short description.
transient errors no Boolean Whether the system is expected to recover from the faulty state on its own. If the flag is not present, this may or may not be the case, or the flag is not applicable.
fields root no Map of string to object
id root no String String or URI identifying the hit, document or other data type. The content of this field is not guaranteed to be meaningful, it is only used as a unique hit identifier for the current result set - refer to #22132 for details.
label root no String The label of a grouping list.
limits root no Object Used in grouping, the limits of a bucket in histogram style data.
from limits no String Lower bound of a bucket group.
to limits no String Upper bound of a bucket group.
relevance root yes Double Double value representing the rank score.
source root no String Which data provider created this node.
types root no Array of string Metadata about what kind of document or other kind of node in the result set this object is.
value root no String Used in grouping for value groups, the argument for the grouping data which is in the fields.
trace no Map of string to object Metadata about query execution.
children trace no Array of object Array of maps with exactly the same structure as trace itself.
timestamp trace no Long Number of milliseconds since the start of query execution this node was added to the trace.
message trace no String Descriptive text regarding this step of query execution.
timing no Map of string to object Query timing information, enabled by presentation.timing.
querytime timing no Double Query execution time, in seconds.
summaryfetchtime timing no Double Document summary fetch time, in seconds.
searchtime timing no Double ToDo: FIXME
summaryfeatures fields no String

Refer to summary-features and observing values used in ranking

matchfeatures fields no String

Refer to match-features and example use.

JSON Schema

Formal schema for the query API default result format:

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "title": "Result",
    "description": "Schema for Vespa results",
    "type": "object",


    "properties": {
        "root": {
            "type": "document_node",
            "required": true
        },
        "trace": {
            "type": "trace_node",
            "required": false
        }
    },

    "definitions": {
        "document_node": {
            "properties": {
                "children": {
                    "type": "array",
                    "items": {
                        "type": "document_node"
                    },
                    "required": false
                },
                "coverage": {
                    "type": "coverage",
                    "required": false
                },
                "errors": {
                    "type": "array",
                    "items": {
                        "type": "error"
                    },
                    "required": false
                },
                "fields": {
                    "type": "object",
                    "additionalProperties": true,
                    "required": false
                },
                "id": {
                    "type": "string",
                    "required": false
                },
                "relevance": {
                    "type": "number",
                    "required": true
                },
                "types": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    },
                    "required": false
                },
                "source": {
                    "type": "string",
                    "required": false
                },
                "value": {
                    "type": "string",
                    "required": false
                },
                "limits": {
                    "type": "object",
                    "required": false
                },
                "label": {
                    "type": "string",
                    "required": false
                }
            },
            "additionalProperties": true,
        },
        "trace_node": {
            "properties": {
                "children": {
                    "type": "array",
                    "items": {
                        "type": "trace_node"
                    },
                    "required": false
                },
                "timestamp": {
                    "type": "number",
                    "required": false
                },
                "message": {
                    "type": "string",
                    "required": false
                }
            }
        },
        "fields": {
            "properties": {
                "totalCount": {
                    "type": "number",
                    "required": true
                }
            }
        },
        "coverage": {
            "properties": {
                "coverage": {
                    "type": "number",
                    "required": true
                },
                "documents": {
                    "type": "number",
                    "required": true
                },
                "full": {
                    "type": "boolean",
                    "required": true
                },
                "nodes": {
                    "type": "number",
                    "required": true
                },
                "results": {
                    "type": "number",
                    "required": true
                },
                "resultsFull": {
                    "type": "number",
                    "required": true
                }
            }
        },
        "error": {
            "properties": {
                "code": {
                    "type": "number",
                    "required": true
                },
                "message": {
                    "type": "string",
                    "required": false
                },
                "source": {
                    "type": "string",
                    "required": false
                },
                "stackTrace": {
                    "type": "string",
                    "required": false
                },
                "summary": {
                    "type": "string",
                    "required": true
                },
                "transient": {
                    "type": "boolean",
                    "required": false
                }
            }
        }
    }
}