• [+] 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 APIs.
  • 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 therefore accessed through generated config classes.

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.

Debugging Components

To debug a Searcher / Document Processor / Component running in the container, set up a remote debugging configuration in the IDEA - IntelliJ example:

  1. Run -> Edit Configurations...
  2. Click + to add a new configuration.
  3. Select the "Remote JVM Debug" option in the left-most pane.
  4. Set hostname to the host running the container, change the port if needed.
  5. Set the container's jvm options to the value in "Command line arguments for remote JVM":
    <container id="default" version="1.0">
            <jvm options="-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005" />
  6. Re-deploy the application, then restart Vespa on the node that runs the container. Make sure the port is published if using a Docker container, e.g.:
    $ docker run --detach --name vespa --hostname vespa-container \
      --publish --publish --publish \
  7. Start debugging! Check vespa.log for errors.

IntelliJ plugin

If using IntelliJ, install the Vespa IntelliJ plugin to simplify working with schema files:


  • To drop a schema with all documents, see drop schema.