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 datatrace: optional object for meta data about query execution (see the Query API)
root is the map key "root" in the return JSON object,
in other words, only strings are used as map keys.
rootmandatory, map of string to object
The root of the tree of returned data.childrenoptional, array of objects
Array of JSON objects with exactly the same structure asroot.fieldsoptional, map of string to object
totalCount, optional, integer
Number of hits
coverageoptional, map of string to string and number
Metadata about how much of the total corpus has been scanned to return the given documents.coveragemandatory, integer
Percentage of total corpus scanned.documentsmandatory, long
The number of documents scanned.fullmandatory, boolean
Whether the full corpus was scanned.nodesmandatory, integer
The number of search instances used executing the query.resultsmandatory, integer
The number of results merged creating the final rendered result.resultsFullmandatory, integer
The number of full result sets merged.errorsoptional, array of objects
Array of error messages with the fields given below.codemandatory, integer
Numeric identifier used by the container application.messageoptional, string
Full description.sourceoptional, string
Which data provider logged the error condition.stackTraceoptional, string
Stack trace if an exception was involved.summarymandatory, string
Short description.transientoptional, 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.fieldsoptional, map of string to object
- The named document fields, this where fields of search documents go
- summaryfeatures
idoptional, string
String or URI identifying the hit, document or other data type.labeloptional, string
The label of a grouping list.limitsoptional, object
Used in grouping, the limits of a bucket in histogram style data.fromoptional, string
Lower bound of a bucket group.tooptional, string
Upper bound of a bucket group.relevancemandatory, double
Double value representing the rank score.sourceoptional, string
Which data provider created this node.typesoptional, array of string
Meta data about what kind of document or other kind of node in the result set this object is.valueoptional, string
Used in grouping for value groups, the argument for the grouping data which is in the fields.traceoptional, map of string to object
Meta data about query execution.childrenoptional, array of object
Array of maps with exactly the same structure astraceitself.timestampoptional, long
Number of milliseconds since the start of query execution this node was added to the trace.messageoptional, string
Descriptive text regarding this step of query execution.
JSON Schema
A formal schema for this JSON 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
}
}
}
}
}
Examples
An empty result:
{
"root": {
"fields": {
"totalCount": 0
},
"id": "toplevel",
"relevance": 1.0
}
}
An error result:
{
"root": {
"errors": [
{
"code": 1234,
"message": "top of the day",
"stackTrace": "java.lang.Throwable\n\tat com.yahoo.search.rendering.JsonRendererTestCase.testErrorWithStackTrace(JsonRendererTestCase.java:732)",
"summary": "hello"
}
],
"fields": {
"totalCount": 0
},
"id": "toplevel",
"relevance": 1.0
}
}
A simple search application, many undefined fields. Result for the query ยด
/search/?query=blues&hits=3&tracelevel=2
{
"trace": {
"children": [
{
"message": "No query profile is used"
},
{
"message": "Invoking chain 'vespa' [com.yahoo.prelude.statistics.StatisticsSearcher@native -> com.yahoo.prelude.querytransform.PhrasingSearcher@vespa -> ... -> federation@native]"
},
{
"children": [
{
"message": "Detected language: ENGLISH"
},
{
"message": "Language ENGLISH determined by the characters in the terms."
},
{
"message": "Query parsed to: select * from sources * where default contains \"blues\" limit 3;"
},
{
"message": "Child execution",
"children": [
{
"message": "Stemming: [select * from sources * where default contains ([{\"origin\": {\"original\": \"blues\", \"offset\": 0, \"length\": 5}, \"stem\": false}]\"blue\") limit 3;]"
},
{
"message": "Lowercasing: [select * from sources * where default contains ([{\"origin\": {\"original\": \"blues\", \"offset\": 0, \"length\": 5}, \"stem\": false, \"normalizeCase\": false}]\"blue\") limit 3;]"
},
{
"message": "sc0.num0 search to dispatch: query=[blue] timeout=5000ms offset=0 hits=3 grouping=0 : collapse=false restrict=[music]"
},
{
"message": "Current state of query tree: WORD[connectedItem=null connectivity=0.0 creator=ORIG explicitSignificance=false fromSegmented=false index=\"\" isRanked=true origin=\"(0 5)\" segmentIndex=0 significance=0.0 stemmed=true uniqueID=1 usePositionData=true weight=100 words=true]{\n \"blue\"\n}\n"
},
{
"message": "YQL+ representation: select * from sources * where default contains ([{\"origin\": {\"original\": \"blues\", \"offset\": 0, \"length\": 5}, \"stem\": false, \"normalizeCase\": false, \"id\": 1}]\"blue\") limit 3;"
},
{
"message": "sc0.num0 dispatch response: Result (3 of total 10 hits)"
},
{
"message": "sc0.num0 fill to dispatch: query=[blue] timeout=5000ms offset=0 hits=3 grouping=0 : collapse=false restrict=[music] summary=[null]"
},
{
"message": "Current state of query tree: WORD[connectedItem=null connectivity=0.0 creator=ORIG explicitSignificance=false fromSegmented=false index=\"\" isRanked=true origin=\"(0 5)\" segmentIndex=0 significance=0.0 stemmed=true uniqueID=1 usePositionData=true weight=100 words=true]{\n \"blue\"\n}\n"
},
{
"message": "YQL+ representation: select * from sources * where default contains ([{\"origin\": {\"original\": \"blues\", \"offset\": 0, \"length\": 5}, \"stem\": false, \"normalizeCase\": false, \"id\": 1}]\"blue\") limit 3;"
}
]
},
{
"message": "Child execution"
}
]
}
]
},
"root": {
"id": "toplevel",
"relevance": 1,
"fields": {
"totalCount": 10
},
"coverage": {
"coverage": 100,
"documents": 10,
"full": true,
"nodes": 1,
"results": 1,
"resultsFull": 1
},
"children": [
{
"id": "index:0/0/0/dfd9fcfa650b44545ef0b8b2",
"relevance": "-Infinity",
"source": "basicsearch",
"fields": {
"sddocname": "music",
"title": "Electric Blues",
"artist": "",
"song": "",
"bgndata": "",
"sales": "NaN",
"pto": -1,
"mid": 2,
"ew": "blues",
"surl": "http://shopping.yahoo.com/shop?d=hab&id=1807865261",
"userrate": "NaN",
"pid": "",
"weight": "NaN",
"url": "",
"isbn": "",
"fmt": "",
"albumid": "",
"disp_song": "",
"pfrom": "NaN",
"bgnpfrom": "NaN",
"categories": "Blues",
"data": "",
"numreview": "NaN",
"bgnsellers": 0,
"image": "",
"artistspid": "",
"newestedition": "NaN",
"bgnpto": "",
"year": "NaN",
"did": "NaN",
"scorekey": "NaN",
"cbid": "NaN",
"summaryfeatures": "",
"documentid": "id:test:music::http://shopping.yahoo.com/shop?d=hab&id=1807865261"
}
},
{
"id": "index:0/0/0/273d384dc214386c934d793f",
"relevance": "-Infinity",
"source": "basicsearch",
"fields": {
"sddocname": "music",
"title": "Delta Blues",
"artist": "",
"song": "",
"bgndata": "",
"sales": "NaN",
"pto": -1,
"mid": 2,
"ew": "blues",
"surl": "http://shopping.yahoo.com/shop?d=hab&id=1804905714",
"userrate": "NaN",
"pid": "",
"weight": "NaN",
"url": "",
"isbn": "",
"fmt": "",
"albumid": "",
"disp_song": "",
"pfrom": "NaN",
"bgnpfrom": "NaN",
"categories": "Blues",
"data": "",
"numreview": "NaN",
"bgnsellers": 0,
"image": "",
"artistspid": "",
"newestedition": "NaN",
"bgnpto": "",
"year": "NaN",
"did": "NaN",
"scorekey": "NaN",
"cbid": "NaN",
"summaryfeatures": "",
"documentid": "id:test:music::http://shopping.yahoo.com/shop?d=hab&id=1804905714"
}
},
{
"id": "index:0/0/0/b3c74a9bf3aea1e2260311c0",
"relevance": "-Infinity",
"source": "basicsearch",
"fields": {
"sddocname": "music",
"title": "Chicago Blues",
"artist": "",
"song": "",
"bgndata": "",
"sales": "NaN",
"pto": -1,
"mid": 2,
"ew": "blues",
"surl": "http://shopping.yahoo.com/shop?d=hab&id=1804905710",
"userrate": "NaN",
"pid": "",
"weight": "NaN",
"url": "",
"isbn": "",
"fmt": "",
"albumid": "",
"disp_song": "",
"pfrom": "NaN",
"bgnpfrom": "NaN",
"categories": "Blues",
"data": "",
"numreview": "NaN",
"bgnsellers": 0,
"image": "",
"artistspid": "",
"newestedition": "NaN",
"bgnpto": "",
"year": "NaN",
"did": "NaN",
"scorekey": "NaN",
"cbid": "NaN",
"summaryfeatures": "",
"documentid": "id:test:music::http://shopping.yahoo.com/shop?d=hab&id=1804905710"
}
}
]
}
}
Result for the grouping query
/search/?hits=0&yql=select * from sources * where sddocname contains purchase | all(group(customer) each(output(sum(price))));
{
"trace": {
"children": [
{
"children": [
{
"message": "Child execution"
}
]
}
]
},
"root": {
"id": "toplevel",
"relevance": 1,
"fields": {
"totalCount": 20
},
"coverage": {
"coverage": 100,
"documents": 20,
"full": true,
"nodes": 1,
"results": 1,
"resultsFull": 1
},
"children": [
{
"id": "group:root:0",
"relevance": 1,
"continuation": {
"this": ""
},
"children": [
{
"id": "grouplist:customer",
"relevance": 1,
"label": "customer",
"children": [
{
"id": "group:string:Jones",
"relevance": 9870,
"value": "Jones",
"fields": {
"sum(price)": 39816
}
},
{
"id": "group:string:Brown",
"relevance": 8000,
"value": "Brown",
"fields": {
"sum(price)": 20537
}
},
{
"id": "group:string:Smith",
"relevance": 6100,
"value": "Smith",
"fields": {
"sum(price)": 19484
}
}
]
}
]
}
]
}
}