Skip to content

Commit b7512cc

Browse files
denglimingclaude
andcommitted
RediSearch: vector fields, PARAMS, DIALECT and TIMEOUT
- VectorField declares FLAT / HNSW vector fields with TYPE, DIM, DISTANCE_METRIC and the algorithm attributes (INITIAL_CAP, BLOCK_SIZE, M, EF_CONSTRUCTION, EF_RUNTIME, EPSILON). Vectors encodes query and document vectors as little-endian FLOAT32 / FLOAT64 blobs. - Field gains WITHSUFFIXTRIE, INDEXEMPTY, INDEXMISSING and SORTABLE UNF. - SearchOptions and AggregateOptions accept PARAMS (byte[] blobs included), DIALECT and TIMEOUT, which KNN queries require. - Integration test covers an HNSW KNN search sorted by score, a FLAT index and a KNN aggregate. Co-Authored-By: Claude <noreply@anthropic.com>
1 parent cfd4073 commit b7512cc

14 files changed

Lines changed: 552 additions & 5 deletions

File tree

‎README.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -168,6 +168,22 @@ AggregateResult aggregate = rediSearch.aggregate("*", new AggregateOptions()
168168
List<Suggestion> suggestions = rediSearch.getSuggestion("pho", new SuggestionOptions().withScores());
169169
```
170170

171+
Vector similarity search: declare a `VectorField`, store vectors as little-endian blobs and query with a KNN clause
172+
bound through `PARAMS` (dialect 2):
173+
174+
```java
175+
rediSearch.createIndex(new Schema()
176+
.addField(new TextField("title"))
177+
.addField(new VectorField("embedding", VectorAlgorithm.HNSW, VectorType.FLOAT32, 768, DistanceMetric.COSINE)),
178+
new IndexOptions().definition(new IndexDefinition().setPrefixes(Arrays.asList("doc:"))));
179+
180+
SearchResult nearest = rediSearch.search("*=>[KNN 10 @embedding $vec AS score]", new SearchOptions()
181+
.param("vec", Vectors.toFloat32Bytes(queryEmbedding))
182+
.dialect(2)
183+
.returnFields("title", "score")
184+
.sort(new SortBy("score", SortOrder.ASC)));
185+
```
186+
171187
### RedisJSON
172188

173189
```java

‎redisearch/README.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -10,13 +10,13 @@ pipelining. Every method has an `*Async` twin.
1010

1111
| Redis command | Java API | Notes |
1212
| --- | --- | --- |
13-
| FT.CREATE | `RediSearch.createIndex()` | `VECTOR` fields, `PARAMS` and `DIALECT` not supported yet |
13+
| FT.CREATE | `RediSearch.createIndex()` | TEXT, TAG, NUMERIC, GEO and `VectorField` (FLAT / HNSW); `WITHSUFFIXTRIE`, `INDEXEMPTY`, `INDEXMISSING`, `SORTABLE UNF` |
1414
| FT.ALTER | `RediSearch.alterIndex()` | |
1515
| FT.DROPINDEX | — | not implemented; `dropIndex()` still sends the removed `FT.DROP` |
1616
| FT.INFO | `RediSearch.loadIndex()` | handles the deeper Redis 8 reply |
1717
| FT._LIST | `RediSearch.listIndexes()` | |
18-
| FT.SEARCH | `RediSearch.search()` | options via `SearchOptions` |
19-
| FT.AGGREGATE | `RediSearch.aggregate()` | options via `AggregateOptions`; `WITHCURSOR` not supported |
18+
| FT.SEARCH | `RediSearch.search()` | options via `SearchOptions`, including `PARAMS`, `DIALECT`, `TIMEOUT` for KNN queries |
19+
| FT.AGGREGATE | `RediSearch.aggregate()` | options via `AggregateOptions`, including `PARAMS`, `DIALECT`, `TIMEOUT`; `WITHCURSOR` not supported |
2020
| FT.CURSOR READ / DEL | — | not implemented |
2121
| FT.HYBRID | — | not implemented (Redis 8.4) |
2222
| FT.PROFILE | — | not implemented |

‎redisearch/src/main/java/io/github/dengliming/redismodule/redisearch/RediSearch.java‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,7 @@
3232
import io.github.dengliming.redismodule.redisearch.index.schema.Schema;
3333
import io.github.dengliming.redismodule.redisearch.index.schema.TagField;
3434
import io.github.dengliming.redismodule.redisearch.index.schema.TextField;
35+
import io.github.dengliming.redismodule.redisearch.index.schema.VectorField;
3536
import io.github.dengliming.redismodule.redisearch.protocol.Keywords;
3637
import io.github.dengliming.redismodule.redisearch.protocol.decoder.SearchResultDecoder;
3738
import io.github.dengliming.redismodule.redisearch.protocol.decoder.StringMapInfoDecoder;
@@ -165,12 +166,27 @@ private void appendFieldArgs(List<Object> args, Field field) {
165166
args.add(textField.getPhonetic().name());
166167
}
167168
break;
169+
case VECTOR:
170+
((VectorField) field).buildAttributes(args);
171+
break;
168172
default:
169173
break;
170174
}
171175

176+
if (field.isWithSuffixTrie()) {
177+
args.add(Keywords.WITHSUFFIXTRIE);
178+
}
179+
if (field.isIndexEmpty()) {
180+
args.add(Keywords.INDEXEMPTY);
181+
}
182+
if (field.isIndexMissing()) {
183+
args.add(Keywords.INDEXMISSING);
184+
}
172185
if (field.isSortable()) {
173186
args.add(Keywords.SORTABLE);
187+
if (field.isUnNormalizedForm()) {
188+
args.add(Keywords.UNF);
189+
}
174190
}
175191
if (field.isNoIndex()) {
176192
args.add(Keywords.NOINDEX);

‎redisearch/src/main/java/io/github/dengliming/redismodule/redisearch/aggregate/AggregateOptions.java‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,9 @@
1919
import io.github.dengliming.redismodule.redisearch.protocol.Keywords;
2020
import io.github.dengliming.redismodule.redisearch.search.Page;
2121

22+
import java.util.LinkedHashMap;
2223
import java.util.List;
24+
import java.util.Map;
2325

2426
/**
2527
* @author dengliming
@@ -33,6 +35,9 @@ public class AggregateOptions {
3335
private Apply[] applies;
3436
private Page[] limits;
3537
private Filter[] filters;
38+
private Map<String, Object> params;
39+
private Integer dialect;
40+
private Long timeout;
3641

3742
public AggregateOptions groups(Group... groups) {
3843
this.groups = groups;
@@ -69,6 +74,40 @@ public AggregateOptions limits(Page... pages) {
6974
return this;
7075
}
7176

77+
78+
/**
79+
* Binds a query parameter referenced as {@code $name} in the query (PARAMS). Vector blobs are passed as
80+
* {@code byte[]}, see {@link io.github.dengliming.redismodule.redisearch.search.Vectors}. Requires dialect 2+.
81+
*/
82+
public AggregateOptions param(String name, Object value) {
83+
if (params == null) {
84+
params = new LinkedHashMap<>();
85+
}
86+
params.put(name, value);
87+
return this;
88+
}
89+
90+
public AggregateOptions params(Map<String, Object> params) {
91+
params.forEach(this::param);
92+
return this;
93+
}
94+
95+
/**
96+
* Query dialect (DIALECT); vector queries and PARAMS need 2 or higher.
97+
*/
98+
public AggregateOptions dialect(int dialect) {
99+
this.dialect = dialect;
100+
return this;
101+
}
102+
103+
/**
104+
* Maximum processing time in milliseconds (TIMEOUT).
105+
*/
106+
public AggregateOptions timeout(long timeoutMillis) {
107+
this.timeout = timeoutMillis;
108+
return this;
109+
}
110+
72111
public void build(List<Object> args) {
73112
if (verbatim) {
74113
args.add(Keywords.VERBATIM);
@@ -108,5 +147,21 @@ public void build(List<Object> args) {
108147
filter.build(args);
109148
}
110149
}
150+
if (timeout != null) {
151+
args.add(Keywords.TIMEOUT);
152+
args.add(timeout);
153+
}
154+
if (params != null && !params.isEmpty()) {
155+
args.add(Keywords.PARAMS);
156+
args.add(params.size() * 2);
157+
params.forEach((name, value) -> {
158+
args.add(name);
159+
args.add(value);
160+
});
161+
}
162+
if (dialect != null) {
163+
args.add(Keywords.DIALECT);
164+
args.add(dialect);
165+
}
111166
}
112167
}
Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
/*
2+
* Copyright 2024 dengliming.
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* http://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
17+
package io.github.dengliming.redismodule.redisearch.index.schema;
18+
19+
/**
20+
* Distance metric of a {@link VectorField}.
21+
*/
22+
public enum DistanceMetric {
23+
/** Euclidean distance. */
24+
L2,
25+
/** Inner product. */
26+
IP,
27+
/** Cosine distance. */
28+
COSINE
29+
}

‎redisearch/src/main/java/io/github/dengliming/redismodule/redisearch/index/schema/Field.java‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,10 @@ public class Field {
2424
private String attribute;
2525
private boolean sortable;
2626
private boolean noIndex;
27+
private boolean unNormalizedForm;
28+
private boolean withSuffixTrie;
29+
private boolean indexEmpty;
30+
private boolean indexMissing;
2731
private FieldType fieldType;
2832

2933
public Field(String name, FieldType fieldType) {
@@ -41,6 +45,54 @@ public Field noIndex() {
4145
return this;
4246
}
4347

48+
/**
49+
* Keep the original letter case and accents of a SORTABLE field (SORTABLE UNF).
50+
*/
51+
public Field unNormalizedForm() {
52+
this.unNormalizedForm = true;
53+
return this;
54+
}
55+
56+
/**
57+
* Build a suffix trie for fast suffix and infix queries (WITHSUFFIXTRIE, TEXT and TAG fields).
58+
*/
59+
public Field withSuffixTrie() {
60+
this.withSuffixTrie = true;
61+
return this;
62+
}
63+
64+
/**
65+
* Index empty strings so that {@code @field:""} matches (INDEXEMPTY, RediSearch 2.10+).
66+
*/
67+
public Field indexEmpty() {
68+
this.indexEmpty = true;
69+
return this;
70+
}
71+
72+
/**
73+
* Index documents lacking the field so that {@code ismissing(@field)} matches (INDEXMISSING, RediSearch 2.10+).
74+
*/
75+
public Field indexMissing() {
76+
this.indexMissing = true;
77+
return this;
78+
}
79+
80+
public boolean isUnNormalizedForm() {
81+
return unNormalizedForm;
82+
}
83+
84+
public boolean isWithSuffixTrie() {
85+
return withSuffixTrie;
86+
}
87+
88+
public boolean isIndexEmpty() {
89+
return indexEmpty;
90+
}
91+
92+
public boolean isIndexMissing() {
93+
return indexMissing;
94+
}
95+
4496
public String getName() {
4597
return name;
4698
}

‎redisearch/src/main/java/io/github/dengliming/redismodule/redisearch/index/schema/FieldType.java‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,5 +23,7 @@ public enum FieldType {
2323
TAG,
2424
TEXT,
2525
GEO,
26-
NUMERIC;
26+
NUMERIC,
27+
/** Vector similarity field, see {@link VectorField}. */
28+
VECTOR;
2729
}
Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
/*
2+
* Copyright 2024 dengliming.
3+
*
4+
* Licensed under the Apache License, Version 2.0 (the "License");
5+
* you may not use this file except in compliance with the License.
6+
* You may obtain a copy of the License at
7+
*
8+
* http://www.apache.org/licenses/LICENSE-2.0
9+
*
10+
* Unless required by applicable law or agreed to in writing, software
11+
* distributed under the License is distributed on an "AS IS" BASIS,
12+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
* See the License for the specific language governing permissions and
14+
* limitations under the License.
15+
*/
16+
17+
package io.github.dengliming.redismodule.redisearch.index.schema;
18+
19+
/**
20+
* Indexing algorithm of a {@link VectorField}.
21+
*/
22+
public enum VectorAlgorithm {
23+
/** Brute force, exact results; best for small sets. */
24+
FLAT,
25+
/** Hierarchical Navigable Small World graph, approximate results; scales to large sets. */
26+
HNSW
27+
}

0 commit comments

Comments
 (0)