Search API

This is the Vespa Search API guide - refer to the search API reference for details.


The host:port endpoint is the Search Container. The general form of a search GET-request is:

The general form of search request with JSON-queries is:
  param1 : value1,
  param2 : value2,
The format is based on the search API reference, and has been converted from the flat dot notation to a nested JSON-structure.
  • The request-method must be POST and the Content-Type must be "application/json".
  • Feel free to use the GUI for building queries at http://localhost:8080/querybuilder/ (with Vespa running) which can help you build queries, with e.g. autocompletion of YQL, pasting of already built queries and conversion of JSON- to URL-queries
  "yql" : "select * from sources * where default contains \"bad\";",
  "offset" : 5,
  "ranking" : {
    "matchPhase" : {
      "ascending" : true,
      "maxHits" : 15
  "presentation" : {
    "bolding" : false,
    "format" : "json"
The only mandatory parameter is yql.

Use GET or POST - Parameters can either be sent as GET-parameters or posted as JSON, these are equivalent:

$ curl -H "Content-Type: application/json" \
    --data '{"yql" : "select * from sources * where default contains \"bad\";"}' \

$ curl http://localhost:8080/search/?yql=select+%2A+from+sources+%2A+where+default+contains+%22bad%22%3B
Note: It is possible to write security filters that block GET and POST requests differently. This can block POSTed queries.

The Search Container uses Jetty for HTTP. Configure the http server - e.g. set requestHeaderSize to configure URL length (including headers):

<container version="1.0">
    <server port="8080" id="myserver">
      <config name="jdisc.http.connector">
HTTP keepalive is supported.

Values must be encoded according to standard URL encoding. Thus, space is encoded as +, + as %2b and so on - see RFC 2396.

HTTP status codes are found in the search API reference. Also see Stack Overflow question.


The query string contains the specification of which results the search should return, typically some words which should be present in matching documents. Queries are formulated in YQL. Note: Also find the legacy simple query language reference.

If Vespa cannot generate a valid search expression from the query string, it will issue the error message Null query. To troubleshoot, add &tracelevel=2 to the request. A missing yql parameter will also lead to this error message.

Examples: refer to YQL, grouping and the sorting reference.

Below is a list of query parameters to control aspects of queries - refer to the search API reference for the full list.

ranking Unless ordering is specified, results are ranked using the default rank profile nativerank. Vespa has a rich ranking framework, read more in ranking. Control result ranking using rank profiles
searchChain Use search chains to implement query processing. Set &tracelevel=2 to inspect the search chain components. Refer to chained components
sources An application can have multiple content clusters - Vespa searches in all by default. Federation controls how to query the clusters, sources names the clusters
pos.ll Specify position using latitude and longitude to implement geo search
queryProfile Use query profiles to store query parameters in configuration. This makes query strings shorter, and makes it easy to modify queries by modifying configuration only. Use cases are setting query properties for different markets, parameters that do not change, and so on. Query profiles can be nested, versioned and use inheritance
tracelevel Set to a positive integer to see query tracing. Higher numbers produce more tracing output. Also see below


All fields are returned in results by default. To specify a subset of fields, use document summaries. When searching text, having a static abstract of the document in a field, or using a dynamic summary can both improve the visual relevance of the search, as well as cut bandwidth used.

The default output format is JSON, find details in the reference.

Read more on request-response processing - use this to write code to manipulate results.

Query tracing

Use query tracing to debug query execution. Enable by using tracelevel=1 (or higher). Add trace.timestamps=true for timing info for every searcher invoked. Example:


    trace: {
        children: [
            message: "No query profile is used"
            message: "Resolved properties: tracelevel=6 (value from request) yql=select * from sources * where default contains "hi"; (value from request) trace.timestamps=true (value from request) "
            message: "Invoking chain 'vespa' [ -> -> ... -> federation@native]"
            children: [
                timestamp: 0,
                message: "Invoke searcher ' in native'"
                timestamp: 14,
                message: " in native Dependencies{provides=[StatisticsSearcher,], before=[rawQuery], after=[]}"
In own code, use Query.trace to add trace output.