Search API

The Search API (/search/) provides HTTP access to query Vespa and retrieve documents. It supports the powerful YQL query language, ranking, grouping, and various result presentation formats.

Base URL

http://<host>:8080/search/

Quick Start

curl "http://localhost:8080/search/?yql=select+*+from+music+where+true"

Query Methods

The Search API supports both GET and POST methods:

GET
POST

Parameters in URL query string:

curl "http://localhost:8080/search/?yql=select+*+from+music+where+artist+contains+'waits'&hits=10"

Parameters in JSON body:

curl -X POST http://localhost:8080/search/ \
  -H "Content-Type: application/json" \
  -d '{
    "yql": "select * from music where artist contains \"waits\"",
    "hits": 10
  }'

Core Parameters

Query

yql

string

required

YQL query string. The primary way to query Vespa.Example: select * from music where artist contains "waits"

query

string

Simple query string (alternative to YQL for basic queries)Example: artist:waits

searchChain

string

default:"default"

Search chain to execute. Use vespa for fallback chain.

Result Control

hits

integer

default:"10"

Number of hits to return (maximum configurable per deployment)

offset

integer

default:"0"

Number of hits to skip (for pagination)

timeout

string

default:"based on query"

Query timeout (e.g., 5s, 500ms)

format

string

default:"json"

Response format: json or cbor

presentation.format

string

default:"json"

Legacy parameter for format

Ranking

ranking.profile

string

default:"default"

Rank profile to use for scoring resultsExample: ranking.profile=bm25

ranking.features.query(tensor)

string

Query tensor for rankingExample: ranking.features.query(embedding)=[1,2,3]

ranking.softtimeout.enable

boolean

default:"true"

Enable soft timeout (return partial results if timeout is near)

ranking.softtimeout.factor

number

default:"0.5"

Fraction of timeout when soft timeout triggers (0.0-1.0)

Field Filtering

presentation.summary

string

default:"default"

Document summary class to use (controls which fields are returned)

summary

string

Alias for presentation.summary

Tracing and Debugging

tracelevel

integer

default:"0"

Trace level 0-9 for query execution details

trace.timestamps

boolean

default:"false"

Include timestamps in trace output

trace.timingDetails

boolean

default:"false"

Include detailed timing information

explainlevel

integer

default:"0"

Explain level for ranking (0-3)

YQL Queries

YQL (Vespa Query Language) is the primary query language:

Basic Query

select * from music where artist contains "waits"

Field Selection

select artist, title, year from music where artist contains "waits"

Multiple Conditions

select * from music where artist contains "waits" and year > 1980

Full-Text Search

select * from music where userQuery()

userQuery() parses the query parameter for user-friendly search.

Ordering

select * from music where true order by year desc

Limiting Results

select * from music where true limit 20

Grouping and Aggregation

select * from music where true | 
all(group(artist) max(5) each(output(count())))

Response Format

Successful Response

{
  "root": {
    "id": "toplevel",
    "relevance": 1.0,
    "fields": {
      "totalCount": 100
    },
    "coverage": {
      "coverage": 100,
      "documents": 1000,
      "full": true,
      "nodes": 2,
      "results": 1,
      "resultsFull": 1
    },
    "children": [
      {
        "id": "id:mynamespace:music::1",
        "relevance": 0.95,
        "source": "music",
        "fields": {
          "artist": "Tom Waits",
          "title": "Downtown Train",
          "year": 1985
        }
      },
      {
        "id": "id:mynamespace:music::2",
        "relevance": 0.87,
        "source": "music",
        "fields": {
          "artist": "Tom Waits",
          "title": "Rain Dogs",
          "year": 1985
        }
      }
    ]
  }
}

root

object

Root result object

root.fields.totalCount

integer

Total number of hits matching the query

root.coverage

object

Coverage information about the search

root.coverage.coverage

integer

Percentage of corpus searched (0-100)

root.coverage.documents

integer

Total documents searched

root.coverage.full

boolean

Whether full coverage was achieved

root.children

array

Array of hit documents

root.children[].id

string

Document ID

root.children[].relevance

number

Relevance score for this hit

root.children[].fields

object

Document fields

Error Response

{
  "root": {
    "id": "toplevel",
    "relevance": 1.0,
    "fields": {
      "totalCount": 0
    },
    "errors": [
      {
        "code": 4,
        "summary": "Invalid query parameter",
        "message": "Could not parse query: Syntax error at position 5"
      }
    ]
  }
}

root.errors

array

Array of error objects

root.errors[].code

integer

Error code

root.errors[].summary

string

Brief error description

root.errors[].message

string

Detailed error message

Advanced Features

Grouping and Aggregation

Group results and compute aggregates:

curl "http://localhost:8080/search/?yql=select+*+from+music+where+true+%7C+all(group(artist)+max(5)+each(output(count())))"

Grouping syntax:

select * from music where true | 
all(group(artist) max(5) each(output(count())))

Common aggregation functions:

count() - Count documents
sum(field) - Sum numeric field
avg(field) - Average of field
max(field) - Maximum value
min(field) - Minimum value

Semantic Search with Embeddings

Query with tensor (embedding) similarity:

curl "http://localhost:8080/search/?" \
  --data-urlencode 'yql=select * from music where {targetHits:10}nearestNeighbor(embedding, query_embedding)' \
  --data-urlencode 'ranking.features.query(query_embedding)=[0.1, 0.2, 0.3, ...]'

Faceting

Get facet counts for categorical fields:

select * from music where userQuery() | 
all(group(genre) each(output(count())))

Pagination

Paginate through results:

# Page 1
curl "http://localhost:8080/search/?yql=select+*+from+music+where+true&hits=10&offset=0"

# Page 2
curl "http://localhost:8080/search/?yql=select+*+from+music+where+true&hits=10&offset=10"

# Page 3
curl "http://localhost:8080/search/?yql=select+*+from+music+where+true&hits=10&offset=20"

Deep pagination (high offset values) can be expensive. Consider using searchAfter for better performance.

Geographic Search

Query documents near a location:

curl "http://localhost:8080/search/?" \
  --data-urlencode 'yql=select * from restaurant where geoLocation(location, 40.7128, -74.0060, "10km")'

Highlighting

Highlight matching terms in results:

bolding

boolean

default:"true"

Enable term highlighting

dynteaser

boolean

default:"false"

Generate dynamic teasers

Highlights are wrapped in <hi> tags:

{
  "fields": {
    "title": "<hi>Downtown</hi> Train by Tom Waits"
  }
}

Query Profiles

Use predefined query profiles:

queryProfile

string

Query profile name to use

curl "http://localhost:8080/search/?yql=...&queryProfile=music-search"

Collapsing (Deduplication)

Collapse similar results:

collapse.field

string

Field to collapse on

collapse.size

integer

default:"1"

Number of hits to keep per collapse value

curl "http://localhost:8080/search/?yql=...&collapse.field=artist&collapse.size=1"

Streaming Search

For latency-critical queries with guaranteed freshness:

curl "http://localhost:8080/search/?streaming.selection=music.user_id=123&yql=select+*+from+music+where+true"

streaming.selection

string

Selection expression for streaming mode

Performance Optimization

Result Caching

nocache

boolean

default:"false"

Disable result cache for this query

nocachewrite

boolean

default:"false"

Don’t write results to cache

Timeout Control

# Set total timeout
curl "http://localhost:8080/search/?yql=...&timeout=3s"

# Enable soft timeout for partial results
curl "http://localhost:8080/search/?yql=...&ranking.softtimeout.enable=true&ranking.softtimeout.factor=0.7"

Field Sets

Retrieve only necessary fields:

select artist, title from music where artist contains "waits"

Or use document summaries:

curl "http://localhost:8080/search/?yql=...&summary=minimal"

HTTP Status Codes

Status	Description
200 OK	Query executed successfully
400 Bad Request	Invalid query syntax or parameters
500 Internal Server Error	Server error during query execution
504 Gateway Timeout	Query exceeded timeout

Even with errors, the Search API typically returns 200 OK with errors in the JSON response body.

Examples

curl "http://localhost:8080/search/?" \
  --data-urlencode 'yql=select * from music where artist contains "waits"' \
  --data-urlencode 'hits=10'

HTTP APIs

Java APIs

Client Libraries

Base URL

Quick Start

Query Methods

Core Parameters

Query

Result Control

Ranking

Field Filtering

Tracing and Debugging

YQL Queries

Basic Query

Field Selection

Multiple Conditions

Full-Text Search

Ordering

Limiting Results

Grouping and Aggregation

Response Format

Successful Response

Error Response

Advanced Features

Grouping and Aggregation

Semantic Search with Embeddings

Faceting

Geographic Search

Highlighting

Query Profiles

Collapsing (Deduplication)

Streaming Search

Performance Optimization

Result Caching

Timeout Control

Field Sets

HTTP Status Codes

Examples

Build docs developers (and LLMs) love

HTTP APIs

Java APIs

Client Libraries

​Base URL

​Quick Start

​Query Methods

​Core Parameters

​Query

​Result Control

​Ranking

​Field Filtering

​Tracing and Debugging

​YQL Queries

​Basic Query

​Field Selection

​Multiple Conditions

​Full-Text Search

​Ordering

​Limiting Results

​Grouping and Aggregation

​Response Format

​Successful Response

​Error Response

​Advanced Features

​Grouping and Aggregation

​Semantic Search with Embeddings

​Faceting

​Pagination

​Geographic Search

​Highlighting

​Query Profiles

​Collapsing (Deduplication)

​Streaming Search

​Performance Optimization

​Result Caching

​Timeout Control

​Field Sets

​HTTP Status Codes

​Examples

​Related Documentation

Build docs developers (and LLMs) love

Base URL

Quick Start

Query Methods

Core Parameters

Query

Result Control

Ranking

Field Filtering

Tracing and Debugging

YQL Queries

Basic Query

Field Selection

Multiple Conditions

Full-Text Search

Ordering

Limiting Results

Grouping and Aggregation

Response Format

Successful Response

Error Response

Advanced Features

Grouping and Aggregation

Semantic Search with Embeddings

Faceting

Pagination

Geographic Search

Highlighting

Query Profiles

Collapsing (Deduplication)

Streaming Search

Performance Optimization

Result Caching

Timeout Control

Field Sets

HTTP Status Codes

Examples

Related Documentation