Redis Search

import redis.clients.jedis.RedisClient;

RedisClient jedis = RedisClient.create("localhost", 6379);
// or, URI form (used in QueryFtExample.java, QueryEmExample.java, etc.):
RedisClient jedis2 = RedisClient.create("redis://localhost:6379");

try (RedisClient jedis = RedisClient.create("redis://localhost:6379")) {
    // FT.* calls here
}

import redis.clients.jedis.RedisClient;
import redis.clients.jedis.exceptions.JedisDataException;
import redis.clients.jedis.json.Path2;
import redis.clients.jedis.search.*;                 // Query, SearchResult, Document,
                                                     // FTCreateParams, FTSearchParams,
                                                     // IndexDataType, RediSearchUtil
import redis.clients.jedis.search.schemafields.*;    // TextField, TagField, NumericField,
                                                     // GeoField, GeoShapeField, VectorField
import redis.clients.jedis.search.aggr.*;            // AggregationBuilder, AggregationResult,
                                                     // Reducers, SortedField, Row, Group
import redis.clients.jedis.args.SortingOrder;        // ASC / DESC

import redis.clients.jedis.search.Combiners;
import redis.clients.jedis.search.Scorers;
import redis.clients.jedis.search.hybrid.FTHybridParams;
import redis.clients.jedis.search.hybrid.FTHybridSearchParams;
import redis.clients.jedis.search.hybrid.FTHybridVectorParams;
import redis.clients.jedis.search.hybrid.FTHybridPostProcessingParams;
import redis.clients.jedis.search.hybrid.HybridResult;

FT.CREATE idx:bicycle ON HASH PREFIX 1 bicycle:
    SCHEMA
        model        TEXT WEIGHT 2.0
        description  TEXT
        brand        TAG
        condition    TAG
        price        NUMERIC SORTABLE
        store_location GEO

// STEP_START create_index_hash
SchemaField[] schema = {
    TextField.of("model").weight(2.0),
    TextField.of("description"),
    TagField.of("brand"),
    TagField.of("condition"),
    NumericField.of("price").sortable(),
    GeoField.of("store_location")
};

jedis.ftCreate("idx:bicycle",
    FTCreateParams.createParams()
        .on(IndexDataType.HASH)
        .addPrefix("bicycle:"),
    schema
);
// STEP_END

FT.CREATE idx:bicycle ON JSON PREFIX 1 bicycle:
    SCHEMA
        $.brand        AS brand        TEXT
        $.model        AS model        TEXT
        $.description  AS description  TEXT
        $.price        AS price        NUMERIC
        $.condition    AS condition    TAG

// STEP_START create_index_json
SchemaField[] schema = {
    TextField.of("$.brand").as("brand"),
    TextField.of("$.model").as("model"),
    TextField.of("$.description").as("description"),
    NumericField.of("$.price").as("price"),
    TagField.of("$.condition").as("condition")
};

jedis.ftCreate("idx:bicycle",
    FTCreateParams.createParams()
        .on(IndexDataType.JSON)
        .addPrefix("bicycle:"),
    schema
);
// STEP_END

// String-only — convenient for simple queries.
SearchResult res = jedis.ftSearch("idx:bicycle", "@condition:{new}");

// String + FTSearchParams — the full surface (filters, dialect, sort, return fields, paging).
SearchResult res2 = jedis.ftSearch("idx:bicycle",
    "@condition:{new}",
    FTSearchParams.searchParams()
        .returnFields("brand", "model", "price")
        .sortBy("price", SortingOrder.ASC)
        .limit(0, 10)
        .dialect(2)
);

// Legacy: Query object (still supported; FTSearchParams is the modern path).
Query q = new Query("@condition:{new}").returnFields("brand").dialect(2);
SearchResult res3 = jedis.ftSearch("idx:bicycle", q);

// STEP_START em1 — numeric exact match via range with equal bounds
SearchResult res1 = jedis.ftSearch("idx:bicycle", "@price:[270 270]");
// Equivalent via FILTER (no inline range):
SearchResult res2 = jedis.ftSearch("idx:bicycle", "*",
    FTSearchParams.searchParams().filter("price", 270, 270));

// STEP_START em2 — tag exact match
SearchResult res3 = jedis.ftSearch("idx:bicycle", "@condition:{new}");

// STEP_START em4 — exact phrase in TEXT
SearchResult res5 = jedis.ftSearch("idx:bicycle", "@description:\"rough terrain\"");

// STEP_START range1 — inclusive
SearchResult res1 = jedis.ftSearch("idx:bicycle", "@price:[500 1000]",
    FTSearchParams.searchParams().returnFields("price").dialect(2));

// STEP_START range3 — exclusive lower, unbounded upper, via FTSearchParams.filter
SearchResult res3 = jedis.ftSearch("idx:bicycle", "*",
    FTSearchParams.searchParams()
        .returnFields("price")
        .filter("price", 1000, true, Double.POSITIVE_INFINITY, false)
        .dialect(2));

// STEP_START range4 — sorted + paged
SearchResult res4 = jedis.ftSearch("idx:bicycle", "@price:[-inf 2000]",
    FTSearchParams.searchParams()
        .returnFields("price")
        .sortBy("price", SortingOrder.ASC)
        .limit(0, 5)
        .dialect(2));

// STEP_START ft1 — field-scoped term
SearchResult res1 = jedis.ftSearch("idx:bicycle", "@description: kids");

// STEP_START ft2 — prefix
SearchResult res2 = jedis.ftSearch("idx:bicycle", "@model: ka*");

// STEP_START ft3 — suffix (requires WITHSUFFIXTRIE at index time for efficiency)
SearchResult res3 = jedis.ftSearch("idx:bicycle", "@brand: *bikes");

// STEP_START ft4 — fuzzy (Levenshtein distance 1)
SearchResult res4 = jedis.ftSearch("idx:bicycle", "%optamized%");

// STEP_START ft5 — fuzzy distance 2 (double % per side)
SearchResult res5 = jedis.ftSearch("idx:bicycle", "%%optamised%%");

// STEP_START geo1 — radius query, parameterised
SearchResult res1 = jedis.ftSearch("idx:bicycle",
    "@store_location:[$lon $lat $radius $units]",
    FTSearchParams.searchParams()
        .addParam("lon", -0.1778)
        .addParam("lat", 51.5524)
        .addParam("radius", 20)
        .addParam("units", "mi")
        .dialect(2));

// STEP_START geo2 — GEOSHAPE CONTAINS (requires DIALECT 3)
SearchResult res2 = jedis.ftSearch("idx:bicycle",
    "@pickup_zone:[CONTAINS $bike]",
    FTSearchParams.searchParams()
        .addParam("bike", "POINT(-0.1278 51.5074)")
        .dialect(3));

// STEP_START geo3 — GEOSHAPE WITHIN polygon
SearchResult res3 = jedis.ftSearch("idx:bicycle",
    "@pickup_zone:[WITHIN $europe]",
    FTSearchParams.searchParams()
        .addParam("europe", "POLYGON((-25 35, 40 35, 40 70, -25 70, -25 35))")
        .dialect(3));

res.getTotalResults();              // server-reported match count (long)
res.getDocuments();                 // List<Document>

for (Document doc : res.getDocuments()) {
    doc.getId();                    // "bicycle:0"
    doc.getScore();                 // double, when .withScores() was set
    doc.getString("brand");         // typed field access
    doc.get("price");               // raw Object value
    doc.hasProperty("price");       // existence check
}

// STEP_START agg1 — LOAD + APPLY (no grouping)
AggregationResult res1 = jedis.ftAggregate("idx:bicycle",
    new AggregationBuilder("@condition:{new}")
        .load("__key", "price")
        .apply("@price - (@price * 0.1)", "discounted")
        .dialect(2));
// Rows: {__key=bicycle:0, discounted=243, price=270}, ...

// STEP_START agg2 — APPLY + GROUPBY + REDUCE
AggregationResult res2 = jedis.ftAggregate("idx:bicycle",
    new AggregationBuilder("*")
        .load("price")
        .apply("@price<1000", "price_category")
        .groupBy("@condition", Reducers.sum("@price_category").as("num_affordable"))
        .dialect(2));

// STEP_START agg3 — synthesised group key via APPLY
AggregationResult res3 = jedis.ftAggregate("idx:bicycle",
    new AggregationBuilder("*")
        .apply("'bicycle'", "type")
        .groupBy("@type", Reducers.count().as("num_total"))
        .dialect(2));
// Rows: {type=bicycle, num_total=10}

// STEP_START agg4 — GROUPBY + TOLIST
AggregationResult res4 = jedis.ftAggregate("idx:bicycle",
    new AggregationBuilder("*")
        .load("__key")
        .groupBy("@condition", Reducers.to_list("__key").as("bicycles"))
        .dialect(2));

Row r = res2.getRows().get(0);
r.getString("condition");       // "new"
r.getLong("num_affordable");    // 3
r.getDouble("avg_price");       // when applicable
r.get("bicycles");              // raw value for TOLIST (ArrayList<String>)

FT.AGGREGATE idx:bicycle "*"
    GROUPBY 1 @brand REDUCE COUNT 0 AS n
    WITHCURSOR COUNT 1000 MAXIDLE 30000
    DIALECT 2

FT.CURSOR READ idx:bicycle <cursor_id> COUNT 1000
FT.CURSOR DEL  idx:bicycle <cursor_id>

// STEP_START aggregate_cursor_open
AggregationBuilder ab = new AggregationBuilder("*")
    .groupBy("@brand", Reducers.count().as("n"))
    .sortBy(10, SortedField.desc("@n"))
    .cursor(1000, 30000)            // COUNT 1000, MAXIDLE 30000 ms
    .dialect(2);

AggregationResult page = jedis.ftAggregate("idx:bicycle", ab);
long cursorId = page.getCursorId();
// STEP_END

// STEP_START aggregate_cursor_read
while (cursorId != 0) {             // 0 signals exhausted server-side cursor
    page = jedis.ftCursorRead("idx:bicycle", cursorId, 1000);
    cursorId = page.getCursorId();
    process(page.getRows());
}
// STEP_END

// STEP_START aggregate_cursor_del
jedis.ftCursorDel("idx:bicycle", cursorId);
// STEP_END

FtAggregateIteration it = jedis.ftAggregateIteration("idx:bicycle", ab);
while (!it.isIterationCompleted()) {
    AggregationResult batch = it.nextBatch();
    process(batch.getRows());
}

FT.CREATE idx:bicycle ON JSON PREFIX 1 bicycle: SCHEMA
    ...
    $.description_embeddings AS vector VECTOR FLAT 6
        TYPE FLOAT32 DIM 1536 DISTANCE_METRIC COSINE

// STEP_START create_vector_index
import redis.clients.jedis.search.schemafields.VectorField;
import redis.clients.jedis.search.schemafields.VectorField.VectorAlgorithm;

int VECTOR_DIMENSION = 1536;        // match your embedding model

Map<String, Object> vectorAttrs = new HashMap<>();
vectorAttrs.put("TYPE", "FLOAT32");
vectorAttrs.put("DIM", VECTOR_DIMENSION);
vectorAttrs.put("DISTANCE_METRIC", "COSINE");

SchemaField[] schema = {
    TextField.of("$.model").noStem().as("model"),
    TextField.of("$.brand").noStem().as("brand"),
    NumericField.of("$.price").as("price"),
    TagField.of("$.type").as("type"),
    VectorField.builder()
        .fieldName("$.description_embeddings")
        .algorithm(VectorAlgorithm.FLAT)        // or HNSW for ANN
        .attributes(vectorAttrs)
        .build()
        .as("vector")
};

jedis.ftCreate("idx:bicycle",
    FTCreateParams.createParams()
        .on(IndexDataType.JSON)
        .addPrefix("bicycle:"),
    schema);
// STEP_END

import redis.clients.jedis.search.RediSearchUtil;

byte[] queryBytes = RediSearchUtil.toByteArray(embedding);   // dim 1536 float[]

static byte[] floatArrayToByteArray(float[] floats) {
    ByteBuffer buf = ByteBuffer.allocate(floats.length * 4).order(ByteOrder.LITTLE_ENDIAN);
    for (float f : floats) buf.putFloat(f);
    return buf.array();
}

// STEP_START vector_knn
FTSearchParams searchParams = FTSearchParams.searchParams()
    .addParam("query_vector", queryBytes)
    .sortBy("vector_score", SortingOrder.ASC)
    .returnFields("vector_score", "brand", "model", "description")
    .dialect(2);

SearchResult res = jedis.ftSearch("idx:bicycle",
    "(*)=>[KNN 3 @vector $query_vector AS vector_score]",
    searchParams);
// STEP_END

// STEP_START vector_prefilter  (pre-Redis-8.4 hybrid pattern — for native blended ranking see §11)
SearchResult res = jedis.ftSearch("idx:bicycle",
    "(@price:[500 1000] -@condition:{new})=>[KNN 3 @vector $query_vector AS vector_score]",
    FTSearchParams.searchParams()
        .addParam("query_vector", queryBytes)
        .sortBy("vector_score", SortingOrder.ASC)
        .returnFields("vector_score", "brand", "model", "price")
        .dialect(2));
// STEP_END

// STEP_START vector_range
SearchResult res = jedis.ftSearch("idx:bicycle",
    "@vector:[VECTOR_RANGE $range $query_vector]=>{$YIELD_DISTANCE_AS: vector_score}",
    FTSearchParams.searchParams()
        .addParam("range", 0.55)
        .addParam("query_vector", queryBytes)
        .sortBy("vector_score", SortingOrder.ASC)
        .returnFields("vector_score", "brand", "model", "description")
        .limit(0, 4)
        .dialect(2));
// STEP_END

jedis.ftSearch("idx:bicycle",
    "*=>[KNN 10 @vector $query_vector EF_RUNTIME 200 AS score]",
    FTSearchParams.searchParams().addParam("query_vector", queryBytes).dialect(2));

// STEP_START run_hybrid_query_native
import redis.clients.jedis.search.Combiners;
import redis.clients.jedis.search.Scorers;
import redis.clients.jedis.search.hybrid.*;
import redis.clients.jedis.search.aggr.Group;
import redis.clients.jedis.search.aggr.Reducers;
import redis.clients.jedis.search.aggr.SortedField;
import redis.clients.jedis.search.Apply;
import redis.clients.jedis.search.Filter;
import redis.clients.jedis.search.Limit;

FTHybridPostProcessingParams postProcessing = FTHybridPostProcessingParams.builder()
    .load("price", "brand", "@category")
    .groupBy(new Group("@brand")
        .reduce(Reducers.sum("@price").as("sum"))
        .reduce(Reducers.count().as("count")))
    .apply(Apply.of("@sum * 0.9", "discounted_price"))
    .sortBy(SortedField.asc("@sum"), SortedField.desc("@count"))
    .filter(Filter.of("@sum > 700"))
    .limit(Limit.of(0, 20))
    .build();

FTHybridParams hybridArgs = FTHybridParams.builder()
    .search(FTHybridSearchParams.builder()
        .query("@category:{electronics} smartphone camera")
        .scorer(Scorers.bm25std())
        .scoreAlias("text_score")
        .build())
    .vectorSearch(FTHybridVectorParams.builder()
        .field("@image_embedding")
        .vector("vector")                          // param name, bound below
        .method(FTHybridVectorParams.Knn.of(20).efRuntime(150))
        .filter("(@brand:{apple|samsung|google}) (@price:[500 1500])")
        .scoreAlias("vector_score")
        .build())
    .combine(Combiners.linear().alpha(0.7).beta(0.3).window(25))   // or Combiners.rrf().window(60)
    .postProcessing(postProcessing)
    .param("vector", queryBytes)
    .build();

HybridResult reply = jedis.ftHybrid("idx:products", hybridArgs);

reply.getTotalResults();
reply.getDocuments();             // List<Document>
reply.getExecutionTime();         // server-side timing (double, ms)
reply.getWarnings();
// STEP_END

import redis.clients.jedis.search.SearchProtocol.SearchCommand;
import redis.clients.jedis.util.SafeEncoder;

byte[] queryBytes = RediSearchUtil.toByteArray(embedding);   // FLOAT32 little-endian

// UnifiedJedis (parent of RedisClient / JedisPooled) exposes sendCommand(ProtocolCommand, byte[]...).
Object raw = ((UnifiedJedis) jedis).sendCommand(
    SearchCommand.HYBRID,
    SafeEncoder.encode("idx:products"),
    SafeEncoder.encode("SEARCH"),      SafeEncoder.encode("laptop"),
    SafeEncoder.encode("VSIM"),        SafeEncoder.encode("@description_vector"),
                                       SafeEncoder.encode("$query_vec"),
    SafeEncoder.encode("KNN"),         SafeEncoder.encode("2"),
                                       SafeEncoder.encode("K"), SafeEncoder.encode("10"),
    SafeEncoder.encode("COMBINE"),     SafeEncoder.encode("RRF"),
                                       SafeEncoder.encode("2"),
                                       SafeEncoder.encode("WINDOW"), SafeEncoder.encode("100"),
    SafeEncoder.encode("PARAMS"),      SafeEncoder.encode("2"),
                                       SafeEncoder.encode("query_vec"),
                                       queryBytes,                              // raw vector — DO NOT round-trip through String
    SafeEncoder.encode("DIALECT"),     SafeEncoder.encode("2")
);

// Pass either a Query object or a raw query string.
String plan = jedis.ftExplain("idx:bicycle",
    new Query("(@brand:{Velorim}) @price:[100 500]").dialect(2));
System.out.println(plan);
// INTERSECT {
//   TAG:@brand { Velorim }
//   NUMERIC {100.000000 <= @price <= 500.000000}
// }

import redis.clients.jedis.search.FTProfileParams;
import redis.clients.jedis.search.ProfilingInfo;

Map.Entry<SearchResult, ProfilingInfo> reply = jedis.ftProfileSearch("idx:bicycle",
    FTProfileParams.profileParams(),
    "@brand:{Velorim}",
    FTSearchParams.searchParams().dialect(2));

SearchResult result = reply.getKey();
Object profile = reply.getValue().getProfilingInfo();   // shape depends on protocol (RESP2/RESP3)

Map.Entry<AggregationResult, ProfilingInfo> aggReply = jedis.ftProfileAggregate("idx:bicycle",
    FTProfileParams.profileParams(),
    new AggregationBuilder("*").groupBy("@brand", Reducers.count().as("n")).dialect(2));

Map<String, Object> info = jedis.ftInfo("idx:bicycle");
info.get("index_name");                  // "idx:bicycle"
info.get("num_docs");                    // server-stringified counts; cast as needed
info.get("hash_indexing_failures");      // non-zero = silent dropouts (schema mismatch)
info.get("attributes");                  // List of per-field detail maps
info.get("inverted_sz_mb");              // memory footprint
info.get("indexing");                    // 1 while background scan runs
info.get("percent_indexed");             // 0.0 – 1.0

jedis.ftAlter("idx:bicycle",
    TagField.of("availability"),
    TextField.of("name").weight(0.5));

jedis.ftAliasAdd("idx:bicycle:active", "idx:bicycle_v2");
jedis.ftAliasUpdate("idx:bicycle:active", "idx:bicycle_v2");    // repoint
jedis.ftAliasDel("idx:bicycle:active");

// Keep documents, drop only the index
jedis.ftDropIndex("idx:bicycle");

// Drop index AND delete every indexed document (destructive)
jedis.ftDropIndexDD("idx:bicycle");

Set<String> all = jedis.ftList();

// LEGACY — Schema class, do not use in new code.
Schema sc = new Schema()
    .addSortableTextField("name", 1.0)
    .addSortableNumericField("count")
    .addTagField("tags");
jedis.ftCreate(INDEX, IndexOptions.defaultOptions(), sc);

// MODERN — SchemaField[] + FTCreateParams.
SchemaField[] schema = {
    TextField.of("name").weight(1.0).sortable(),
    NumericField.of("count").sortable(),
    TagField.of("tags")
};
jedis.ftCreate(INDEX, FTCreateParams.createParams(), schema);