Maps

LittleHorse provides a native MAP variable type that stores strongly-typed key/value pairs.

Use MAP when you want compile-time and runtime guarantees that every key and value in your map conforms to a specific type. This is in contrast to JSON_OBJ, which is schema-less and performs no type validation on its contents.

info

Map support was added in LittleHorse 1.2. Only the Java SDK supports declareMap() as of this release. Support for other SDKs is planned for future releases.

Contrast with JSON_OBJ

Feature	MAP	JSON_OBJ
Key type enforcement	Yes — must be a primitive type	No
Value type enforcement	Yes — enforced at ingress	No
Use case	Strongly-typed key/value data	Arbitrary JSON objects

Supported Key and Value Types

Keys must resolve to a primitive type (e.g., STR, INT, DOUBLE, BOOL). The server enforces this constraint at ingress.

Values can be any TypeDefinition:

• Primitives: INT, DOUBLE, STR, BOOL, BYTES, etc.
• Complex types: STRUCT (backed by a registered StructDef)
• Typed collections: ARRAY

note

MAP variables cannot contain JSON_OBJ or JSON_ARR values. Those types do not have a defined schema for validation and would defeat the purpose of using a strongly-typed map.

In Practice

To use a MAP variable in LittleHorse:

1. Declare a MAP variable in your WfSpec using declareMap().
2. Produce and consume maps in your task workers.
3. Use mutation operations to manipulate map contents.

Declaring a MAP Variable

Use the declareMap method on WorkflowThread to create a typed map variable. You specify both the key type and value type as Java classes.

Signature:

WfRunVariable declareMap(String name, Class<?> keyType, Class<?> valueType)

Both type parameters must be Java types that the LittleHorse type system can resolve to a supported TypeDefinition.

Java

import io.littlehorse.sdk.wfsdk.WfRunVariable;
import io.littlehorse.sdk.wfsdk.WorkflowThread;

public void wfLogic(WorkflowThread wf) {
    // String keys, Long values
    WfRunVariable myMap = wf.declareMap("my-map", String.class, Long.class);

    // String keys, array-of-Long values
    WfRunVariable myMapOfArrays = wf.declareMap("map-of-arrays", String.class, Long[].class);
}

Mutation Operations

The MAP type supports the following mutation operation:

Operation	Description
ASSIGN	Replace the entire map with a new value
EXTEND	Merge two maps; existing keys in LHS are overwritten by RHS values
REMOVE_KEY	Remove an entry by key (RHS must be compatible with the key type)

Additional mutation operations (such as per-key insert or removal) are planned for future releases.

Java

import io.littlehorse.sdk.wfsdk.NodeOutput;
import io.littlehorse.sdk.wfsdk.WfRunVariable;
import io.littlehorse.sdk.wfsdk.WorkflowThread;

public void wfLogic(WorkflowThread wf) {
    WfRunVariable myMap = wf.declareMap("my-map", String.class, Long.class);

    // Assign the result of a task to the map
    NodeOutput produced = wf.execute("produce-map");
    myMap.assign(produced);
}

Further Resources

• Variables Concepts — overview of all variable types in LittleHorse.
• Arrays — the related strongly-typed ordered collection type.
• StructDefs and Structs — strongly-typed objects with an evolveable schema.