Custom Configuration File Reference

This is the reference for config file definitions. It is useful for developing applications that has configurable components for the Vespa Container, where configuration for individual components may be provided by defining <config> elements within the component's scope in services.xml.

Config definition files

Config definition files are part of the source code of your application and have a .def suffix. Each file defines and documents the content and semantics of one configuration type. Vespa's builtin .def files are found in $VESPA_HOME/share/vespa/configdefinitions/.

Package

Package is a mandatory statement that is used to define the package for the java class generated to represent the file. For container component developers, it is recommended to use a separate package for each bundle that needs to export config classes, to avoid conflicts between bundles that contain configurable components. Package must be the first non-comment line, and can only contain lower-case characters and dots:

package=com.mydomain.mypackage

Parameter names

Config definition files contain lines on the form:

parameterName type [default=value] [range=[min,max]]

camelCase in parameter names is recommended for readability.

Parameter types

Supported types for variables in the .def file:

      foo enum {BAR, BAZ, QUUX} default=BAR

Structs

Structs are used to group a number of parameters that naturally belong together. A struct is declared by adding a '.' between the struct name and each member's name:

basicStruct.foo string
basicStruct.bar int

Arrays

Arrays are declared by appending square brackets to the parameter name. Arrays can either contain simple values, or have children. Children can be simple parameters and/or structs and/or other arrays. Arbitrarily complex structures can be built to any depth. Examples:

intArr[] int                        # Integer value array
row[].column[] int                  # Array of integer value arrays
complexArr[].foo string             # Complex array that contains
complexArr[].bar double             # … two simple parameters
complexArr[].coord.x int            # … and a struct called 'coord'
complexArr[].coord.y int
complexArr[].coord.depths[] double  # … that contains a double array

Note that arrays cannot have default values, even for simple value arrays. An array that has children cannot contain simple values, and vice versa. In the example above, intArr and row.column could not have children, while row and complexArr are not allowed to contain values.

Maps

Maps are declared by appending curly brackets to the parameter name. Arbitrarily complex structures are supported also here. Examples:

myMap{} int
complexMap{}.nestedMap{}.id int
complexMap{}.nestedMap{}.name string

Generic configuration in services.xml

services.xmlhas four types of elements:

Generic config elements can be added to most elements that lead to one or more services being created - i.e. service group elements and individual service elements. The config is then applied to all services created by that element and all descendant elements.

For example, by adding config for container, the config will be applied to all container components in that cluster. Config at a deeper level has priority, so this config can be overridden for individual components by setting the same config values in e.g. handler or server elements.

Given the following config definition, let's say its name is type-examples.def:

package=com.mydomain

stringVal string
myArray[].name string
myArray[].type enum {T1, T2, T3} default=T1
myArray[].intArr[] int
myMap{} string
basicStruct.foo string
basicStruct.bar int default=0 range=[-100,100]
boolVal bool
myFile path
myUrl url
myOptionalPath path optional

<config name="com.mydomain.type-examples">
  <stringVal>val</stringVal>
  <myArray>
    <item>
      <name>elem_0</name>
      <type>T2</type>
      <intArr>
        <item>0</item>
        <item>1</item>
      </intArr>
    </item>
    <item>
      <name>elem_1</name>
      <type>T3</type>
      <intArr>
        <item>0</item>
        <item>1</item>
      </intArr>
    </item>
  </myArray>
  <myMap>
    <item key="key1">val1</item>
    <item key="key2">val2</item>
  </myMap>
  <basicStruct>
    <foo>str</foo>
    <bar>3</bar>
  </basicStruct>
  <boolVal>true</boolVal>
  <myFile>components/file1.txt</myFile>
  <myUrl>https://docs.vespa.ai/en/reference/query-api-reference.html</myUrl>
</config>

Note that each '.' in the parameter's definition corresponds to a child element in the xml. It is not necessary to set values that already have a default in the .def file, if you want to keep the default value. Hence, in the example above, basicStruct.bar and myArray[].type could have been omitted in the xml without generating any errors when deploying the application.

Configuring arrays

Assigning values to arrays is done by using the <item> element. This ensures that the given config values do not overwrite any existing array elements from higher-level xml elements in services, or from Vespa itself.