Voltdb-cache

The voltdb-cache processor that caches VoltDB server responses based on input requests to reduce network calls. When called with the same input, returns the cached response instead of querying the server again.

A "double miss" occurs when a lookup request fails to find a value in both the cache and the underlying database. In this scenario, the requested key is neither cached nor persisted and therefore cannot be resolved by the system. Such requests are not processed further by the pipeline but may be routed to a dead-letter queue (DLQ) for handling.

User can relay on VoltSP standard configuration options to customise this processor.

As with the VoltDB flavored sinks this resource works with arrays of Object-s that correspond to stored procedure arguments. E.g. to invoke a stored procedure that has public long run(long id, int anotherId, String someString) method the Object[] should contain Long, Integer and String or compatible types as defined in the VoltDB documentation.

In case of the system error this resource will retry procedure execution with exponential backoff. The details of this behaviour are configurable using retry configuration.

The voltdb-cache operator requires VoltDBResource to be configured either in yaml or in java, see examples.

JAVAYAML

.processWith(VoltProcedureCacheConfigBuilder.builder()
    .withVoltClientResourceRef(value)
    .withProcedureName(value)
    .withSql(value)
    .withParamFunction(value)
    .withMaximumSize(value)
    .withExpireAfterWrite(value)
    .withRetry(builder -> builder
        .withRetries(value)
        .withBackoffDelay(value)
        .withMaxBackoffDelay(value)
    )
    .withExceptionHandler(value)
)

processor:
  voltdb-cache:
    voltClientResourceRef: value
    procedureName: value
    sql: value
    paramFunction: value
    maximumSize: value
    expireAfterWrite: value
    retry:
      retries: value
      backoffDelay: value
      maxBackoffDelay: value
    exceptionHandler: value

Java dependency management

Add this declaration to your dependency management system to access the configuration DSL for this plugin in Java.

MavenGradle

<dependency>
    <groupId>org.voltdb</groupId>
    <artifactId>volt-stream-plugin-volt-api</artifactId>
    <version>1.0-20250910-124207-release-1.5.3</version>
</dependency>

implementation group: 'org.voltdb', name: 'volt-stream-plugin-volt-api', version: '1.0-20250910-124207-release-1.5.3'

Properties

voltClientResourceRef

Name of the voltdb-client resource used to connect to VoltDB cluster Required.

Type: string

procedureName

Called stored procedure name Type: string

Default value: @AdHoc

sql

SQL query executed by @AdHoc procedure Type: string

paramFunction

Mapper from domain object to stored procedure or SQL query parameters Type: object

maximumSize

The maximum size of the cache Type: number

Default value: 100000

expireAfterWrite

Each entry should be automatically removed from the cache once a this duration has elapsed after the entry's creation, or the most recent replacement of its value.

Type: object

Default value: PT10M

retry

Configuration for retrying failed operations, including the number of retries and backoff delays.

Type: object

Fields of retry:

retry.retries

Number of retry attempts after a request failure. Type: number

Default value: 3

retry.backoffDelay

Initial delay before the first retry attempt. Type: object

Default value: PT0.2S

retry.maxBackoffDelay

Maximum delay between consecutive retry attempts. Type: object

Default value: PT3S

exceptionHandler

A custom exception handler enabling interception of all errors related to this processor. Type: object

Usage Examples

JAVAYAML

// if resource is configured in yaml
voltStreamBuilder.configureResource("primary-cluster", VoltDBResourceConfigBuilder.class);
// or
voltStreamBuilder.configureResource("primary-cluster",
         VoltDBResourceConfigBuilder.class,
         new Consumer<VoltDBResourceConfigBuilder>() {
             @Override
             public void consume(VoltDBResourceConfigBuilder configurator) {
                 configurator
                   .addToServers("localhost", 12122)
                   .withClientBuilder(vcb -> builder -> {
                       builder.withMaxOutstandingTransactions(42000);
                       builder.withMaxTransactionsPerSecond(23);
                       builder.withRequestTimeout(Duration.ofSeconds(5));
                       builder.withAuthBuilder(authBuilder -> authBuilder
                          .withUsername("admin")
                          .withPassword("admin123"));
                       builder.withSslBuilder(sslBuilder -> sslBuilder
                          .withTrustStoreFile("c:/Users32/trust.me")
                          .withTrustStorePassword("got2have"));
                       builder.withRetryBuilder(retryBuilder -> retryBuilder
                          .withRetries(4)
                          .withBackoffDelay(Duration.ofSeconds(2))
                          .withMaxBackoffDelay(Duration.ofSeconds(11)));
                   })
             }
         });

.processWith(VoltProcedureCacheConfigBuilder.builder()
   .withVoltClientResourceRef("primary-cluster")
   .withSql("SELECT * FROM events WHERE id=?")
   .withParamFunction(i -> new Object[]{i})
   .withMaximumSize(100000)
   .withExpireAfterWrite(Duration.ofMinutes(10))
   .withRetryBuilder(retryBuilder -> retryBuilder
             .withRetries(4)
             .withBackoffDelay(Duration.ofSeconds(2))
             .withMaxBackoffDelay(Duration.ofSeconds(11)))
)

```yaml resources: - name: primary-cluster voltdb-client: servers: localhost:12122 client: maxTransactionsPerSecond: 3000 maxOutstandingTransactions: 3000 requestTimeout: PT10S auth: user: Admin password: 2r2Ffafw3V trustStore: file: file.pem password: got2have

processor: voltdb-cache: resourceRef: primary-cluster procedureName: "getEvent" maximumSize: 100000 expireAfterWrite: PT10S server: %s ```