• [+] expand all

Developer Guide

For Big Data Serving, writing custom code in plugins is often required - in Vespa, such plugins (called Components) are run in the Stateless Java Container Cluster:

  • Query Processors implemented as Searchers enables query enrichment, rewrites and external data lookup as part of query processing.
  • Document processors is similar and operates on incoming documents in an asynchronuous environment for high throughput.
  • Handlers and renderers are Other Components that lets application owners build rich APIs, see the Vespa Container.

Find sample applications for all component types in Getting Started, also see Troubleshooting.

Developing Plugins

The development cycle is normally create a plugin (based on the sample applications), deploy it to Vespa, write tests, iterate. 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 testing.


Add testing to automate deployments:

  • System Tests for functional tests - a system test is an integration test that tests the application API endpoints
  • Staging Tests to validate the instance before and after the code/config change, i.e. two test runs with potentially different tests
  • Production Tests to validate a production instance before upgrading the next instance
System and Staging tests require a (downscaled) full instance, whereas Production tests evaluates user-defined production metrics. Vespa Cloud has automated this - find examples in Read more in automated deployments.

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