services.xml - 'routing'

This is the reference documentation for all elements in the routing section of services.xml.

routing [version]
    routingtable [protocol, verify]
        route [name, hops]
        hop [name, selector, ignore-result]
            recipient [session]
    services [protocol]
        service [name]

routing

Contained in services. The container element for all configuration related to routing. Attributes:

  • version (required): Must be set to "1.0" in this Vespa-version
Optional subelements: Example:
<routing version="1.0">
  <routingtable protocol="document">
    <route name="route1" hops="hop1 hop2" />
    <route name="route2" hops="hop3 hop4 hop5" />
    <hop name="hop1" selector="docproc/cluster.foo/docproc/*/feed-processor">
      <recipient session="docproc/cluster.foo/docproc/*/feed-processor" />
    </hop>
    <hop name="hop2" selector="search/cluster.bar/[SearchGroup]/[SearchRow]/[SearchColumn]/feed-destination">
      <recipient session="search/cluster.bar/g0/c0/r0/feed-destination" />
      <recipient session="search/cluster.bar/g0/c1/r0/feed-destination" />
      <recipient session="search/cluster.bar/g0/c0/r1/feed-destination" />
      <recipient session="search/cluster.bar/g0/c1/r1/feed-destination" />
      <recipient session="search/cluster.bar/g1/c0/r0/feed-destination" />
      <recipient session="search/cluster.bar/g1/c1/r0/feed-destination" />
      <recipient session="search/cluster.bar/g1/c0/r1/feed-destination" />
      <recipient session="search/cluster.bar/g1/c1/r1/feed-destination" />
    </hop>
  </routingtable>
  <services protocol="document">
    <service name="foo/bar" />
  </services>
</routing>

routingtable

Contained in routing. Specifies a routing table for a specific protocol. Attributes:

  • protocol (required): Configure which protocol to use. Only the protocol document is defined, so if you define a routing table for an unsupported protocol, the application will just log an INFO entry that contains the name of that protocol.
  • verify (optional): Boolean. ToDo: document this
Optional subelements: Example:
<routing version="1.0">
  <routingtable protocol="document">
    <route name="route1" hops="hop1 hop2" />
    <hop name="hop1" selector="docproc/cluster.foo/docproc/*/feed-processor">
      <recipient session="docproc/cluster.foo/docproc/*/feed-processor" />
    </hop>
  </routingtable>
</routing>

route

Contained in routingtable. Specifies a route for a message to its destination through a set of intermediate hops. If at least one hop in a route does not exist, the application will fail to start and issue an error that contains the name of that hop. Attributes:

  • name (required): Route name.
  • hops (required): A whitespace-separated list of hop names, where each name must be a valid hop.
Subelements: none

Example:

<routing version="1.0">
  <routingtable protocol="document">
    <route name="route1" hops="hop1 hop2" />
    <route name="route2" hops="hop3 hop4 hop5" />
  </routingtable>
</routing>

hop

Contained in routingtable. Specifies a single hop that can be used to construct one or more routes. A hop must have a name that is unique within the routing table to which it belongs. A hop contains a selector string and a list of recipient sessions. Attributes:

  • name (required): Hop name.
  • selector (required): Selector string.
  • ignore-result (optional): If set to true, specifies that the result of routing through that hop should be ignored.
Optional subelements: Example:
<routing version="1.0">
  <routingtable protocol="document">
    <hop name="hop1" selector="docproc/cluster.foo/docproc/*/feed-processor">
      <recipient session="docproc/cluster.foo/docproc/*/feed-processor" />
    </hop>
  </routingtable>
</routing>

recipient

Contained in hop. Specifies a recipient session of a hop. Attributes:

  • session (required): This attribute must correspond to a running instance of a service that can be routed to. All session identifiers consist of a location part and a name. A search node is always given a session name on the form search/cluster.name/g#/r#/c#/feed-destination, whereas a document processor service is always named docproc/cluster.name/docproc/#/feed-processor.
Subelements: none

Example:

<routing version="1.0">
  <routingtable protocol="document">
    <hop name="search/cluster.music" selector="search/cluster.music/[SearchGroup]/[SearchRow]/[SearchColumn]/feed-destination">
      <recipient session="search/cluster.music/g0/c0/r0/feed-destination" />
      <recipient session="search/cluster.music/g0/c0/r1/feed-destination" />
      <recipient session="search/cluster.music/g1/c0/r0/feed-destination" />
      <recipient session="search/cluster.music/g1/c0/r1/feed-destination" />
    </hop>
  </routingtable>
</routing>

services

Contained in routing. Specifies a set of services available for a specific protocol. At the moment the only supported protocol is document. The services specified are used by the route verification step to allow hops and routes to reference services known to exist, but that can not be derived from services.xml. Attributes:

  • protocol (required): Configure which protocol to use. Only the protocol document is defined.
Optional subelements: Example:
<routing version="1.0">
  <services protocol="document">
    <service name="foo/bar" />
  </services>
</routing>

service

Contained in services. Specifies a single known service that can not be derived from the services.xml. Attributes:

  • name (required): The name of the service.
Subelements: none

Example:

<routing version="1.0">
  <services protocol="document">
    <service name="foo/bar" />
  </services>
</routing>