default-result-format.html

---
# Copyright Vespa.ai. All rights reserved.
title: "Default JSON Result Format"
redirect_from:
- /en/reference/default-result-format.html
---

<p>
  The default Vespa query response format is used when
  <a href="../api/query.html#presentation.format">presentation.format</a>
  is unset or set to <code>json</code>.
  An alternative binary <a href="https://cbor.io/">CBOR</a> format is available by setting
  <code>format=cbor</code> or using <code>Accept: application/cbor</code>.
  CBOR is a drop-in replacement - when deserialized, the result is identical to JSON.
  CBOR is both more compact and faster to generate, especially for numeric data such as tensors and embeddings.
  Results are rendered with one or more objects:
</p>
<ul>
  <li><code>root</code>: mandatory object with the tree of returned data</li>
  <li><code>timing</code>: optional object with query timing information</li>
  <li><code>trace</code>: optional object for metadata about query execution</li>
</ul>
<p>
  Refer to the <a href="../../querying/query-api.html#result-examples">query API guide</a> for result and tracing examples.
</p>
<p>
  All object names are literal strings,
  the node <code>root</code> is the map key "root" in the return JSON object,
  in other words, only strings are used as map keys.
</p>
<table class="table">
  <thead>
  <tr>
    <th>Element</th>
    <th>Parent</th>
    <th>Mandatory</th>
    <th>Type</th>
    <th>Description</th>
  </tr>
  </thead>
  <tbody>
  <tr>
    <td colspan="5"><h2 id="root-header">root</h2></td>
  </tr>
  <tr>
    <th>root</th>
    <td></td>
    <td>yes</td>
    <td>Map of string to object</td>
    <td><p id="root">The root of the tree of returned data.</p></td>
  </tr>
  <tr>
    <th>children</th>
    <td>root</td>
    <td>no</td>
    <td>Array of objects</td>
    <td><p id="children">Array of JSON objects with the same structure as <code>root</code>.</p></td>
  </tr>
  <tr>
    <th>fields</th>
    <td>root</td>
    <td>no</td>
    <td>Map of string to object</td>
    <td><p id="fields"></p></td>
  </tr>
  <tr>
    <th>totalCount</th>
    <td>fields</td>
    <td>no</td>
    <td>Integer</td>
	  <td>
      <p id="totalcount">Number of documents matching the query.
        Not accurate when using <em>nearestNeighbor</em>,
        <em>wand</em> or <em>weakAnd</em> query operators.</p>
      <p>
        The value is the number of hits after
        <a href="../schemas/schemas.html#rank-score-drop-limit">first-phase dropping</a>.
      </p>
    </td>
  </tr>
  <tr>
    <th>coverage</th>
    <td>root</td>
    <td>no</td>
    <td>Map of string to string and number</td>
    <td>
      <p id="coverage-map">
        Map of metadata about how much of the total corpus has been searched to return the given documents.
      </p>
    </td>
  </tr>
  <tr>
    <th>coverage</th>
    <td>coverage</td>
    <td>yes</td>
    <td>Integer</td>
    <td><p id="coverage">Percentage of total corpus searched (when lower than 100 this is an approximation and is a lower bound, as no info from nodes down is known)</p></td>
  </tr>
  <tr>
    <th>documents</th>
    <td>coverage</td>
    <td>yes</td>
    <td>Long</td>
    <td><p id="documents">The number of active documents searched.</p></td>
  </tr>
  <tr>
    <th>full</th>
    <td>coverage</td>
    <td>yes</td>
    <td>Boolean</td>
    <td><p id="full">Whether the full corpus was searched.</p></td>
  </tr>
  <tr>
    <th>nodes</th>
    <td>coverage</td>
    <td>yes</td>
    <td>Integer</td>
    <td><p id="nodes">The number of search nodes returning results.</p></td>
  </tr>
  <tr>
    <th>results</th>
    <td>coverage</td>
    <td>yes</td>
    <td>Integer</td>
    <td><p id="results">The number of results merged creating the final rendered result.</p></td>
  </tr>
  <tr>
    <th>resultsFull</th>
    <td>coverage</td>
    <td>yes</td>
    <td>Integer</td>
    <td><p id="resultsfull">The number of full result sets merged, e.g. when there are several sources/clusters for the results.</p></td>
  </tr>
  <tr>
    <th>degraded</th>
    <td>coverage</td>
    <td>no</td>
    <td>Map of string to object</td>
    <td><p id="degraded">Map of match-phase degradation elements.</p></td>
  </tr>
  <tr>
    <th>match-phase</th>
    <td>degraded</td>
    <td>no</td>
    <td>Boolean</td>
    <td>
      <p id="match-phase">
        Indicator whether <a href="../schemas/schemas.html#match-phase">match-phase degradation</a> has occurred.
      </p>
    </td>
  </tr>
  <tr>
    <th>timeout</th>
    <td>degraded</td>
    <td>no</td>
    <td>Boolean</td>
    <td>
      <p id="timeout">
        Indicator whether the query <a href="../api/query.html#timeout">timed out</a> before completion.
      </p>
    </td>
  </tr>
  <tr>
    <th>adaptive-timeout</th>
    <td>degraded</td>
    <td>no</td>
    <td>Boolean</td>
    <td>
      <p id="adaptive-timeout">
        Indicator whether the query timed out with
        <a href="../api/query.html#ranking.softtimeout.enable">adaptive timeout</a> before completion.
      </p>
    </td>
  </tr>
  <tr>
    <th>non-ideal-state</th>
    <td>degraded</td>
    <td>no</td>
    <td>Boolean</td>
    <td>
      <p id="non-ideal-state">
        Indicator whether the content cluster is in <a href="../../content/idealstate.html">ideal state</a>.
      </p>
    </td>
  </tr>
  <tr>
    <th>errors</th>
    <td>root</td>
    <td>no</td>
    <td>Array of objects</td>
    <td>
      <p id="error">
        Array of error messages with the fields given below.
        <a href="../../querying/query-api.html#error-result">Example</a>.
      </p>
    </td>
  </tr>
  <tr>
    <th>code</th>
    <td>errors</td>
    <td>yes</td>
    <td>Integer</td>
    <td>
      <p id="code">
        Numeric identifier used by the container application.
        See <a href="https://github.com/vespa-engine/vespa/blob/master/container-disc/src/main/java/com/yahoo/container/protect/Error.java">
        error codes</a> and
        <a href="https://github.com/vespa-engine/vespa/blob/master/container-search/src/main/java/com/yahoo/search/result/ErrorMessage.java">
        ErrorMessage.java</a> for a short description.
      </p>
    </td>
  </tr>
  <tr>
    <th>message</th>
    <td>errors</td>
    <td>no</td>
    <td>String</td>
    <td><p id="message">Full error message.</p></td>
  </tr>
  <tr>
    <th>source</th>
    <td>errors</td>
    <td>no</td>
    <td>String</td>
    <td><p id="error-source">Which <a href="../../querying/federation.html">data provider</a> logged the error condition.</p></td>
  </tr>
  <tr>
    <th>stackTrace</th>
    <td>errors</td>
    <td>no</td>
    <td>String</td>
    <td><p id="stacktrace">Stack trace if an exception was involved.</p></td>
  </tr>
  <tr>
    <th>summary</th>
    <td>errors</td>
    <td>yes</td>
    <td>String</td>
    <td><p id="summary">Short description of error.</p></td>
  </tr>
  <tr>
    <th>transient</th>
    <td>errors</td>
    <td>no</td>
    <td>Boolean</td>
    <td>
      <p id="transient">
        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.
      </p>
    </td>
  </tr>
  <tr>
    <th>fields</th>
    <td>root</td>
    <td>no</td>
    <td>Map of string to object</td>
    <td>
      <p id="fields-map">
        The named document (schema) <a href="../schemas/schemas.html#field">fields</a>.
        Fields without value are not rendered.
      </p>
      <p>
        In addition to the fields defined in the schema,
        the following might be returned:
      </p>
      <table>
        <thead>
        <tr>
          <th>Fieldname</th>
          <th>Description</th>
        </tr>
        </thead>
        <tbody>
        <tr>
          <td>sddocname</td>
          <td>
            <p id="sddocname">
              Schema name.
              Returned in the <a href="../../querying/document-summaries.html">default document summary</a>.
            </p>
          </td>
        </tr>
        <tr>
          <td>documentid</td>
          <td>
            <p id="documentid">
              Document ID.
              Returned in the <a href="../../querying/document-summaries.html">default document summary</a>.
            </p>
          </td>
        </tr>
        <tr>
          <td>summaryfeatures</td>
          <td>
            <p id="summaryfeatures">
              Refer to <a href="../schemas/schemas.html#summary-features">summary-features</a> and
              <a href="../../ranking/ranking-intro#observing-values-used-in-ranking">observing values used in ranking</a>.
            </p>
          </td>
        </tr>
        <tr>
          <td>matchfeatures</td>
          <td>
            <p id="matchfeatures">
              Refer to <a href="../schemas/schemas.html#match-features">match-features</a> and
              <a href="../../querying/nearest-neighbor-search-guide#strict-filters-and-distant-neighbors">example use</a>.
            </p>
          </td>
        </tr>
        </tbody>
      </table>
    </td>
  </tr>
  <tr>
    <th>id</th>
    <td>root</td>
    <td>no</td>
    <td>String</td>
    <td>
      <p id="id">String identifying the hit, document or other data type.
      For document hits, this is the full string document id if the hit is filled with a
      document summary from disk. If it is not filled or only filled with data from memory (attributes),
      it is an internally generated unique id on the form <code>index:[source]/[node-index]/[hex-gid]</code>.</p>
      <p>Also see the <a href="../../writing/document-v1-api-guide.html#troubleshooting">/document/v1/ guide</a>
      and <a href="https://stackoverflow.com/questions/74033383/receiving-responses-of-different-formats-for-the-same-query-in-vespa">
      receiving-responses-of-different-formats-for-the-same-query-in-vespa</a>.</p>
    </td>
  </tr>
  <tr>
    <th>label</th>
    <td>root</td>
    <td>no</td>
    <td>String</td>
    <td><p id="label">The label of a grouping list.</p></td>
  </tr>
  <tr>
    <th>limits</th>
    <td>root</td>
    <td>no</td>
    <td>Object</td>
    <td><p id="limits">Used in grouping, the limits of a bucket in histogram style data.</p></td>
  </tr>
  <tr>
    <th>from</th>
    <td>limits</td>
    <td>no</td>
    <td>String</td>
    <td><p id="from">Lower bound of a bucket group.</p></td>
  </tr>
  <tr>
    <th>to</th>
    <td>limits</td>
    <td>no</td>
    <td>String</td>
    <td><p id="to">Upper bound of a bucket group.</p></td>
  </tr>
  <tr>
    <th>relevance</th>
    <td>root</td>
    <td>yes</td>
    <td>Double</td>
    <td>
	  <p id="relevance">Double value representing the rank score.
      The rank score is returned from the <a href="../../ranking/ranking-intro.html">rank-profile</a>'s
      first, second, or <a href="../../ranking/phased-ranking.html#using-a-global-phase-expression">global</a> phase.
	  </p>
	</td>
  </tr>
  <tr>
    <th>source</th>
    <td>root</td>
    <td>no</td>
    <td>String</td>
    <td><p id="source">Which data provider created this node.</p></td>
  </tr>
  <tr>
    <th>types</th>
    <td>root</td>
    <td>no</td>
    <td>Array of string</td>
    <td>
      <p id="types">Metadata about what kind of document or other kind of node in the result set this object is.</p>
    </td>
  </tr>
  <tr>
    <th>value</th>
    <td>root</td>
    <td>no</td>
    <td>String</td>
    <td>
      <p id="value">Used in grouping for value groups, the argument for the grouping data which is in the fields.</p>
    </td>
  </tr>
  <tr>
    <td colspan="5"></td>
  </tr>
  <tr>
    <td colspan="5"><h2 id="timing-header">timing</h2></td>
  </tr>
  <tr>
    <th>timing</th>
    <td></td>
    <td>no</td>
    <td>Map of string to object</td>
    <td>
      <p id="timing">
        Query timing information,
        enabled by <a href="../api/query.html#presentation.timing">presentation.timing</a>.
        The <a href="../../performance/practical-search-performance-guide#basic-text-search-query-performance">query performance guide</a>
        is a useful resource to understand the values in its child elements.
      </p>
    </td>
  </tr>
  <tr>
    <th>querytime</th>
    <td>timing</td>
    <td>no</td>
    <td>Double</td>
    <td><p id="querytime">Time to execute the first protocol phase/matching phase, in seconds.</p></td>
  </tr>
  <tr>
    <th>summaryfetchtime</th>
    <td>timing</td>
    <td>no</td>
    <td>Double</td>
    <td>
      <p id="summaryfetchtime">
        <a href="../../querying/document-summaries.html">Document summary</a> fetch time, in seconds.
        This is the time to execute the summary fill protocol phase for the globally ordered top-k hits.
      </p>
    </td>
  </tr>
  <tr>
    <th>searchtime</th>
    <td>timing</td>
    <td>no</td>
    <td>Double</td>
    <td>
      <p id="searchtime">
        Approximately the sum of <code>querytime</code> and <code>summaryfetchtime</code>
        and is close to what a client will observe (except network latency).
        In seconds.
      </p>
    </td>
  </tr>
  <tr>
    <td colspan="5"></td>
  </tr>
  <tr>
    <td colspan="5"><h2 id="trace-heading">trace</h2>
      {% include note.html content="The tracing elements below is a subset of all elements.
      Refer to the <a href='../../performance/practical-search-performance-guide#advanced-query-tracing'>
      search performance guide</a> for examples." %}</td>
  </tr>
  <tr>
    <th>trace</th>
    <td></td>
    <td>no</td>
    <td>Map of string to object</td>
    <td><p id="trace">Metadata about query execution.</p></td>
  </tr>
  <tr>
    <th>children</th>
    <td>trace</td>
    <td>no</td>
    <td>Array of object</td>
    <td><p id="children-trace">Array of maps with exactly the same structure as <code>trace</code> itself.</p></td>
  </tr>
  <tr>
    <th>timestamp</th>
    <td>children</td>
    <td>no</td>
    <td>Long</td>
    <td>
      <p id="timestamp">Number of milliseconds since the start of query execution this node was added to the trace.</p>
    </td>
  </tr>
  <tr>
    <th>message</th>
    <td>children</td>
    <td>no</td>
    <td>String</td>
    <td><p id="message-trace">Descriptive trace text regarding this step of query execution.</p></td>
  </tr>
  <tr>
    <th>message</th>
    <td>children</td>
    <td>no</td>
    <td>Array of objects</td>
    <td><p id="message-trace-map">Array of messages</p></td>
  </tr>
  <tr>
    <th>start_time</th>
    <td>message</td>
    <td>no</td>
    <td>String</td>
    <td><p id="start-time">Timestamp, e.g. 2022-07-27 09:51:21.938 UTC</p></td><!-- ToDo: why not an ISO 8601 string -->
  </tr>
  <tr>
    <th>traces</th>
    <td>message or threads</td>
    <td>no</td>
    <td>Array of traces or objects</td>
    <td><p id="traces"></p></td>
  </tr>
  <tr>
    <th>distribution-key</th>
    <td>message</td>
    <td>no</td>
    <td>Integer</td>
    <td>
      <p id="distribution-key">
        The <a href="../applications/services/content.html#node">distribution key</a> of the content node creating this span.
      </p>
    </td>
  </tr>
  <tr>
    <th>duration_ms</th>
    <td>message</td>
    <td>no</td>
    <td>float</td>
    <td><p id="duration-ms">duration of span</p></td>
  </tr>
  <tr>
    <th>timestamp_ms</th>
    <td>traces</td>
    <td>no</td>
    <td>float</td>
    <td><p id="timestamp-ms">time since start of parent, see <code>start_time</code>.</p></td>
  </tr>
  <tr>
    <th>event</th>
    <td>traces</td>
    <td>no</td>
    <td>String</td>
    <td><p id="event">Description of span</p></td>
  </tr>
  <tr>
    <th>tag</th>
    <td>traces</td>
    <td>no</td>
    <td>String</td>
    <td><p id="tag">Name of span</p></td>
  </tr>
  <tr>
    <th>threads</th>
    <td>traces</td>
    <td>no</td>
    <td>Array of objects</td>
    <td><p id="threads">Array of object that again has traces elements.</p></td>
  </tr>
  </tbody>
</table>



<h2 id="json-schema">JSON Schema</h2>
<p>Formal schema for the query API default result format:</p>
<pre>{% highlight json %}
{
    "$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
                }
            }
        }
    }
}
{% endhighlight %}</pre>


<h2 id="appendix-legacy-vespa-7-json-rendering">Appendix: Legacy Vespa 7 JSON rendering</h2>
<p>
  There were some inconsistencies between search results and document rendering in Vespa 7, which are fixed in Vespa 8.
  This appendix describes the old behavior, what the changes are,
  and how to configure to select a specific rendering.
</p>


<h3 id="inconsistent-weightedset-rendering">Inconsistent weightedset rendering</h3>
<p>
  Fields with various weightedset types has a JSON input representation (for feeding) as a JSON object;
  for example <code>{"one":1, "two":2,"three":3}</code> for
  the value of a a <code>weightedset&lt;string&gt;</code> field.
  The same format is used when rendering a document (for example when visiting).
</p>
<p>
  In search results however, there are intermediate processing steps during which the
  field value is represented as an array of item/weight pairs,
  so in a search result the field value would render as
  <code>[ {"item":"one", "weight":1},
    {"item":"two", "weight":2},
    {"item":"three", "weight":3} ]</code>
</p>
<p>
  In Vespa 8, the default JSON renderer for search results outputs the same format
  as document rendering.  If you have code that depends on the old format you can
  turn off this by setting <code>renderer.json.jsonWsets=false</code>
  in the query (usually via a <a href="../../querying/query-profiles.html">query profile</a>).
</p>


<h3 id="inconsistent-map-rendering">Inconsistent map rendering</h3>
<p>
  Fields with various map types has a JSON input representation (for feeding) as a JSON object;
  for example <code>{"1001":1.0, "1002":2.0, "1003":3.0}</code> for
  the value of a a <code>map&lt;int,float&gt;</code> field.
  The same format is used when rendering a document (for example when visiting).
</p>
<p>
  In search results however, there are intermediate processing steps and the field value
  is represented as an array of key/value pairs,
  so in a search results the field value would (in some cases) render as
  <code>[ {"key":1001, "value":1.0},
    {"key":1002, "value":2.0},
    {"key":1003, "value":3.0} ]</code>
</p>
<p>
  In Vespa 8, the default JSON renderer for search results output the same format as document rendering.
  For code that depends on the old format one can
  turn off this by setting <code>renderer.json.jsonMaps=false</code>
  in the query (usually via a <a href="../../querying/query-profiles.html">query profile</a>).
</p>


<h3 id="geo-position-rendering">Geo position rendering</h3>
<p>
  Fields with the type <code>position</code> would in Vespa 7 be rendered using the internal fields "x" and "y".
  These are integers representing microdegrees,
  aka geographical degrees times 1 million, of longitude (for x) and latitude (for y).
  Also, any field <em>foo</em> of type <code>position</code> would trigger addition of
  two extra synthetic summary fields <em>foo.position</em> and <em>foo.distance</em> (see below for details).
</p>
<p>
  In Vespa 8, positions are rendered with two JSON fields "lat" and "lng",
  both having a floating-point value.
  The "lat" field is latitude (going from -90.0 at the South Pole to +90.0 at the North Pole).
  The "lng" field is longitude (going from -180.0 at the dateline seen as extreme west,
  via 0.0 at the Greenwich meridian, to +180.0 at the dateline again, now as extreme east).
  The field names are chosen so the format is the same as used in the Google "places" API.
</p>
<p>
  A closely related change is the removal of two synthetic summary fields
  which would be returned in search results.  For example with this in schema:
</p>
<pre>
field mainloc type position {
    indexing: attribute | summary
}
</pre>
<p>
  Vespa 7 would include the <em>mainloc</em> summary field,
  but also <em>mainloc.position</em> and <em>mainloc.distance</em>;
  the latter only when the query actually had a position to take the distance from.
</p>
<p>
  The first of these (<em>mainloc.position</em> in this case) was
  mainly useful for producing XML output in older Vespa versions,
  and now contains just the same information as the <em>mainloc</em> summary field.
  The second (<em>mainloc.distance</em> in this case) would return a distance in internal units,
  and can be replaced by a summary feature -
  here <code>distance(mainloc)</code> would give the same number,
  while <code>distance(mainloc).km</code> would be the recommended replacement with suitable code changes.
<p>


<h3 id="summary-features-wrapped-in-rankingexpression">Summary-features wrapped in "rankingExpression"</h3>
<p>
  In Vespa 7, if a rank profile wanted a function
  <code>foobar</code> returned in summary-features (or match-features),
  it would be rendered as <code>rankingExpression(foobar)</code> in the output.
</p>
<p>
  For programmatic use, the <code>FeatureData</code> class has extra checking to allow lookup with
  <code>getDouble("foobar")</code> or
  <code>getTensor("foobar")</code>,
  but now it's present and rendered with just the original name as specified.
</p>
<p>
  If applications needs the JSON rendering to look exactly as in Vespa 7, one can specify that in the rank profile.
  For example, with this in the schema:
</p>
<pre>
rank-profile whatever {
    function lengthScore() { expression: matchCount(title)/fieldLength(title) }
    summary-features {
        matchCount(title)
        lengthScore
        ...
</pre>
<p>could, in Vespa 7, yield JSON output containing:</p>
<pre>
    summaryfeatures: {
        matchCount(title): 1,
        rankingExpression(lengthScore): 0.25,
        ...
</pre>
<p>in Vespa 8, you instead get the expected:</p>
<pre>
    summaryfeatures: {
        matchCount(title): 1,
        lengthScore: 0.25,
        ...
</pre>
<p>But to get the old behavior one can specify:</p>
<pre>
rank-profile whatever {
    function lengthScore() { expression: matchCount(title)/fieldLength(title) }
    summary-features {
        matchCount(title)
			  rankingExpression(lengthScore)
        ...
</pre>
<p>which gives you the same output as before.</p>