• [+] expand all

Developer Guide

Vespa Overview

Application packages can contain Java components to be run in container clusters. The most common component types are:

  • Searchers, which can modify or build the query, modify the result, implement workflows issuing multiple queries etc.
  • Document processors that can modify incoming write operations.
  • Handlers that can implement custom web service API's.
  • Renderers that are used to define custom result formats.

Components are constructed by dependency injection and are reloaded safely on deployment without restarts. See the container documentation for more details.

See the sample applications in getting started, to find examples of applications containing Java components. Also see troubleshooting.

Developing Components

The development cycle consists of creating the component, deploying the application package to Vespa, writing tests, and iterating. These steps refer to files in album-recommendation-java:


All the Vespa sample applications use the bundle plugin to build the components.


A key Vespa feature is code and configuration consistency, deployed using an application package. This ensures that code and configuration is in sync, and loaded atomically when deployed. This is done by generating config classes from config definition files. In Vespa and application code, configuration is hence accessed through generated config classes - read more in the Cloud Configuration System.

The Maven target generate-sources (invoked by mvn install) uses metal-names.def to generate target/generated-sources/vespa-configgen-plugin/com/mydomain/example/MetalNamesConfig.java.

After generating config classes, they will resolve in tools like IntelliJ IDEA.


Examples unit tests are found in MetalSearcherTest.java. testAddedOrTerm1 and testAddedOrTerm2 illustrates two ways of doing the same test:

Read more in unit testing.


To connect a debugger, use Java Debug Wire Protocol (JDWP) - instructions.

IntelliJ plugin

If you use IntelliJ, you can install the Vespa IntelliJ plugin to simplify working with schema files.