Skip to content
Valkey Glide

Modules API

Valkey Modules offers a way to extend the general Valkey commands and functionality, and (starting in release 1.2) Valkey GLIDE offers a simple Modules API client interface to interact with common Modules API. See Modules Introduction on how to load modules into your Valkey service.

General Usage

Section titled “General Usage”

Valkey Module commands are available through static calls that wrap the custom command.
The APIs definitions are strictly owned by the Module creator, so there will be some slight variation between Module behaviour. Visit the module API pages to learn more about the behaviour of individual APIs.

Some example Module APIs include:

Use INFO MODULES or MODULE LIST command to see the status of all loaded modules.

Examples

Section titled “Examples”

Once the module is loaded into the server, the following examples demonstrate basic behaviour for calling module commands:

JSON Module Example

Section titled “JSON Module Example”
import glide.api.commands.servermodules.Json;


try (GlideClient glideClient = GlideClient.createClient(config).get()) {
    String key = "testKey";
    String path = "$";
    String jsonValue = "{\"a\": 1.0, \"b\": 2}";


    CompletableFuture<String> setResponseFuture = Json.set(glideClient, key, path, jsonValue);
    String setResponse = setResponseFuture.get(); // "OK"
    assert setResponse.equals("OK");


    CompletableFuture<String> getResponseFuture = Json.get(client, key).get();
    String getResponseFuture = setResponseFuture.get(); // jsonValue
    assert value.equals("{\"a\": 1.0, \"b\": 2}");
}

Vector Search Module Example

Section titled “Vector Search Module Example”
import glide.api.commands.servermodules.FT;
import glide.api.models.commands.FT.FTCreateOptions.FieldInfo;
import glide.api.models.commands.FT.FTCreateOptions;
import glide.api.models.commands.FT.FTCreateOptions.*;
import glide.api.models.commands.FT.FTSearchOptions;


try (GlideClient glideClient = GlideClient.createClient(config).get()) {


    // FT.Create a Hash index with Hash values and FT.Search those values
    String prefix = "{hash}:";
    String index = prefix + "index";
    FieldInfo[] fields = new FieldInfo[] {
        new FieldInfo("vec", "VEC", VectorFieldHnsw.builder(DistanceMetric.L2, 2).build())
    };
    FTCreateOptions.builder().dataType(DataType.HASH).prefixes(new String[] {prefix}).build();
    FT.create(client, index, fields, FTCreateOptions).get(); // returns "OK"


    Map hash0 = Map.of("vec", new byte[] {
        (byte) 0, (byte) 0, (byte) 0, (byte) 0, (byte) 0, (byte) 0, (byte) 0, (byte) 0
    });
    client.hset(prefix + "0", hash0).get();


    Map hash1 = Map.of("vec", new byte[] {
        (byte) 0, (byte) 0, (byte) 0, (byte) 0,
        (byte) 0, (byte) 0, (byte) 0x80, (byte) 0xBF
    });
    client.hset(prefix + "1", hash1).get();


    Thread.sleep(1000); // let server digest the data and update index


    FTSearchOptions searchOptions = FTSearchOptions.builder()
        .params(Map.of("query_vec", (byte) 0, (byte) 0, (byte) 0, (byte) 0, (byte) 0, (byte) 0, (byte) 0, (byte) 0)))
        .build();
    String query = "*=>[KNN 2 @VEC $query_vec]";
    Object[] ftsearchResponse = FT.search(client, index, query, searchOptions).get();
    assert ftsearchResponse[0] == 2L;
    // ftsearchResponse[1] contains a map with "{hash}:0" and "{hash}:1" vector search results
}