Skip to content

Commit 110c683

Browse files
JotschiJotschi
committed
Update docs, add jreleaser
1 parent 6f90531 commit 110c683

File tree

16 files changed

+250
-103
lines changed

16 files changed

+250
-103
lines changed

‎README.md

Lines changed: 75 additions & 58 deletions
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,7 @@ This project contains a java client for the [Qdrant vector database](https://qdr
3636
<dependency>
3737
<groupId>io.metaloom.qdrant</groupId>
3838
<artifactId>qdrant-java-grpc-client</artifactId>
39-
<version>0.0.1-SNAPSHOT</version>
39+
<version>0.9.0-SNAPSHOT</version>
4040
</dependency>
4141
```
4242

@@ -46,7 +46,7 @@ or for the HTTP client
4646
<dependency>
4747
<groupId>io.metaloom.qdrant</groupId>
4848
<artifactId>qdrant-java-http-client</artifactId>
49-
<version>0.0.1-SNAPSHOT</version>
49+
<version>0.9.0-SNAPSHOT</version>
5050
</dependency>
5151
```
5252

@@ -62,70 +62,87 @@ This client was build and tested for Qdrant server version `v0.11.7`. Minimum re
6262
## Usage - gRPC
6363

6464
```java
65-
QDrantGRPCClient client = QDrantGRPCClient.builder()
66-
.setHostname("localhost")
67-
.setPort(qdrant.grpcPort())
65+
try (QDrantGRPCClient client = QDrantGRPCClient.builder()
66+
.setHostname("localhost")
67+
.setPort(port)
68+
.build()) {
69+
70+
// Define the collection to store vectors
71+
VectorParams params = VectorParams.newBuilder()
72+
.setSize(4)
73+
.setDistance(Distance.Euclid)
6874
.build();
6975

70-
VectorParams params = VectorParams.newBuilder()
71-
.setSize(4)
72-
.setDistance(Distance.Euclid)
73-
.build();
74-
75-
// Create new collections - blocking
76-
client.createCollection("test1", params).blocking().getResult();
77-
// Or using Future API
78-
client.createCollection("test2", params).future().get().getResult();
79-
// Or using RxJava API
80-
client.createCollection("test3", params).rx().blockingGet().getResult();
81-
82-
83-
// Insert a new vector
84-
for (int i = 0; i < 10; i++) {
85-
Vector vector = ModelHelper.toVector(new float[] { 0.43f + i, 0.1f, 0.61f, 1.45f });
86-
PointStruct point = PointStruct.newBuilder()
87-
.putPayload("color", ModelHelper.toValue("blue"))
88-
.setId(ModelHelper.toPointId(42L + i))
89-
.setVectors(Vectors.newBuilder().setVector(vector))
90-
.build();
91-
System.out.println(client.upsertPoint("test1", point, true).blocking().getResult().getStatus());
76+
// Create new collections - blocking
77+
client.createCollection("test1", params).sync();
78+
// .. or via Future API
79+
client.createCollection("test2", params).async().get();
80+
// .. or via RxJava API
81+
client.createCollection("test3", params).rx().blockingGet();
82+
83+
// Insert a new vectors
84+
for (int i = 0; i < 10; i++) {
85+
86+
// Vector of the point
87+
float[] vector = new float[] { 0.43f + i, 0.1f, 0.61f, 1.45f - i };
88+
89+
// Payload of the point
90+
Map<String, Value> payload = new HashMap<>();
91+
payload.put("color", ModelHelper.value("blue"));
92+
93+
// Now construct the point
94+
PointStruct point = ModelHelper.point(42L + i, vector, payload);
95+
// .. and insert it
96+
client.upsertPoint("test1", point, true).sync();
97+
}
98+
99+
// Count points
100+
long nPoints = client.countPoints("test1", null, true).sync().getResult().getCount();
101+
102+
// Now run KNN search
103+
float[] searchVector = new float[] { 0.43f, 0.09f, 0.41f, 1.35f };
104+
List<ScoredPoint> searchResults = client.searchPoints("test1", searchVector, 2, null).sync().getResultList();
105+
for (ScoredPoint result : searchResults) {
106+
System.out.println("Found: [" + result.getId().getNum() + "] " + result.getScore());
107+
}
108+
109+
// Invoke backup via Snapshot API
110+
client.createSnapshot("test1").sync();
92111
}
93-
94-
// Count vectors
95-
client.countPoints("test1", null, true).blocking().getResult().getCount();
96112
```
97113

98114

99115
## Usage - HTTP
100116

101117
```java
102-
QDrantHttpClient client = QDrantHttpClient.builder()
118+
try (QDrantHttpClient client = QDrantHttpClient.builder()
103119
.setHostname("localhost")
104-
.setPort(qdrant.httpPort())
105-
.build();
106-
107-
// Create a collection
108-
CollectionCreateRequest req = new CollectionCreateRequest();
109-
req.setVectors("colors", 4, Distance.EUCLID);
110-
client.createCollection("the-collection-name", req).sync();
111-
112-
// Now add some points
113-
PointStruct p1 = PointStruct.of("colors", 0.42f, 0.33f, 42.15f, 68.72f)
114-
.setPayload("{\"name\": \"first\"}")
115-
.setId(1);
116-
PointStruct p2 = PointStruct.of("colors", 0.76f, 0.43f, 63.45f, 22.10f)
117-
.setPayload("{ \"color\": \"red\"}")
118-
.setId(2);
119-
PointStruct p3 = PointStruct.of("colors", 0.41f, 0.32f, 42.11f, 68.71f).setId(3);
120-
PointStruct p4 = PointStruct.of("colors", 0.12f, 0.23f, 12.46f, 47.17f).setId(4);
121-
122-
PointsListUpsertRequest pointsRequest = new PointsListUpsertRequest();
123-
pointsRequest.setPoints(p1, p2, p3, p4);
124-
client.upsertPoints("the-collection-name", pointsRequest, false).async().blockingGet();
125-
126-
// List the collections
127-
client.listCollections().async().blockingGet();
128-
129-
// Count the points in the collection
130-
client.countPoints("the-collection-name", new PointCountRequest().setExact(true)).sync();
120+
.setPort(port)
121+
.build()) {
122+
123+
// Create a collection
124+
CollectionCreateRequest req = new CollectionCreateRequest();
125+
req.setVectors("colors", 4, Distance.EUCLID);
126+
client.createCollection("the-collection-name", req).sync();
127+
128+
// Now add some points
129+
PointStruct p1 = PointStruct.of("colors", 0.42f, 0.33f, 42.15f, 68.72f)
130+
.setPayload("{\"name\": \"first\"}")
131+
.setId(1);
132+
PointStruct p2 = PointStruct.of("colors", 0.76f, 0.43f, 63.45f, 22.10f)
133+
.setPayload("{ \"color\": \"red\"}")
134+
.setId(2);
135+
PointStruct p3 = PointStruct.of("colors", 0.41f, 0.32f, 42.11f, 68.71f).setId(3);
136+
PointStruct p4 = PointStruct.of("colors", 0.12f, 0.23f, 12.46f, 47.17f).setId(4);
137+
138+
PointsListUpsertRequest pointsRequest = new PointsListUpsertRequest();
139+
pointsRequest.setPoints(p1, p2, p3, p4);
140+
client.upsertPoints("the-collection-name", pointsRequest, false).async().blockingGet();
141+
142+
// List the collections
143+
client.listCollections().async().blockingGet();
144+
145+
// Count the points in the collection
146+
client.countPoints("the-collection-name", new PointCountRequest().setExact(true)).sync();
147+
}
131148
```

‎common/pom.xml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@
99
<parent>
1010
<groupId>io.metaloom.qdrant</groupId>
1111
<artifactId>qdrant-java-client</artifactId>
12-
<version>0.0.1-SNAPSHOT</version>
12+
<version>0.9.0-SNAPSHOT</version>
1313
</parent>
1414

1515
<name>Qdrant Java Client :: common</name>

‎grpc/pom.xml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@
99
<parent>
1010
<groupId>io.metaloom.qdrant</groupId>
1111
<artifactId>qdrant-java-client</artifactId>
12-
<version>0.0.1-SNAPSHOT</version>
12+
<version>0.9.0-SNAPSHOT</version>
1313
</parent>
1414

1515
<name>Qdrant Java Client :: grpc</name>

‎grpc/src/main/java/io/metaloom/qdrant/client/grpc/GrpcUtil.java renamed to ‎grpc/src/main/java/io/metaloom/qdrant/client/grpc/InternalGrpcUtil.java

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,10 @@
99
import io.metaloom.qdrant.client.grpc.proto.RaftGrpc;
1010
import io.metaloom.qdrant.client.grpc.proto.SnapshotsGrpc;
1111

12-
public final class GrpcUtil {
12+
public final class InternalGrpcUtil {
13+
14+
private InternalGrpcUtil() {
15+
}
1316

1417
public static CollectionsGrpc.CollectionsBlockingStub collectionsStub(ClientSettings client) {
1518
return CollectionsGrpc.newBlockingStub(client.channel());

‎grpc/src/main/java/io/metaloom/qdrant/client/grpc/method/CollectionMethods.java

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
package io.metaloom.qdrant.client.grpc.method;
22

3-
import static io.metaloom.qdrant.client.grpc.GrpcUtil.collectionsAsyncStub;
4-
import static io.metaloom.qdrant.client.grpc.GrpcUtil.collectionsStub;
3+
import static io.metaloom.qdrant.client.grpc.InternalGrpcUtil.collectionsAsyncStub;
4+
import static io.metaloom.qdrant.client.grpc.InternalGrpcUtil.collectionsStub;
55

66
import java.util.List;
77
import java.util.Objects;

‎grpc/src/main/java/io/metaloom/qdrant/client/grpc/method/GrpcClientRequest.java

Lines changed: 16 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,19 +15,34 @@ public class GrpcClientRequest<T> {
1515
private final ClientSettings settings;
1616

1717
public GrpcClientRequest(ClientSettings settings, Supplier<T> blockingSupplier, Supplier<ListenableFuture<T>> asyncSupplier) {
18-
this.settings= settings;
18+
this.settings = settings;
1919
this.blocking = blockingSupplier;
2020
this.async = asyncSupplier;
2121
}
2222

23+
/**
24+
* Execute the request synchronously / blocking.
25+
*
26+
* @return
27+
*/
2328
public T sync() {
2429
return blocking.get();
2530
}
2631

32+
/**
33+
* Execute the request asynchronously.
34+
*
35+
* @return
36+
*/
2737
public ListenableFuture<T> async() {
2838
return async.get();
2939
}
3040

41+
/**
42+
* Execute the the request asynchronously via RxJava.
43+
*
44+
* @return
45+
*/
3146
public Maybe<T> rx() {
3247
return QDrantClientUtil.toMaybe(async(), settings);
3348
}

‎grpc/src/main/java/io/metaloom/qdrant/client/grpc/method/PointMethods.java

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
package io.metaloom.qdrant.client.grpc.method;
22

3-
import static io.metaloom.qdrant.client.grpc.GrpcUtil.pointsAsyncStub;
4-
import static io.metaloom.qdrant.client.grpc.GrpcUtil.pointsStub;
3+
import static io.metaloom.qdrant.client.grpc.InternalGrpcUtil.pointsAsyncStub;
4+
import static io.metaloom.qdrant.client.grpc.InternalGrpcUtil.pointsStub;
55

66
import java.util.Arrays;
77
import java.util.List;

‎grpc/src/main/java/io/metaloom/qdrant/client/grpc/method/SearchMethods.java

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
package io.metaloom.qdrant.client.grpc.method;
22

3-
import static io.metaloom.qdrant.client.grpc.GrpcUtil.pointsAsyncStub;
4-
import static io.metaloom.qdrant.client.grpc.GrpcUtil.pointsStub;
3+
import static io.metaloom.qdrant.client.grpc.InternalGrpcUtil.pointsAsyncStub;
4+
import static io.metaloom.qdrant.client.grpc.InternalGrpcUtil.pointsStub;
55

66
import java.util.ArrayList;
77
import java.util.List;

‎grpc/src/main/java/io/metaloom/qdrant/client/grpc/method/SnapshotMethods.java

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
package io.metaloom.qdrant.client.grpc.method;
22

3-
import static io.metaloom.qdrant.client.grpc.GrpcUtil.snapshotsAsyncStub;
4-
import static io.metaloom.qdrant.client.grpc.GrpcUtil.snapshotsStub;
3+
import static io.metaloom.qdrant.client.grpc.InternalGrpcUtil.snapshotsAsyncStub;
4+
import static io.metaloom.qdrant.client.grpc.InternalGrpcUtil.snapshotsStub;
55

66
import java.util.Objects;
77

‎grpc/src/main/java/io/metaloom/qdrant/client/util/ModelHelper.java

Lines changed: 38 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -55,37 +55,63 @@ public static PointId pointId(long id) {
5555
return PointId.newBuilder().setNum(id).build();
5656
}
5757

58+
/**
59+
* Construct a {@link PointId} from the provided uuid.
60+
*
61+
* @param uuid
62+
* @return
63+
*/
5864
public static PointId pointId(UUID uuid) {
5965
Objects.requireNonNull(uuid, "The provided uuid must not be null");
6066
return PointId.newBuilder().setUuid(uuid.toString()).build();
6167
}
6268

69+
/**
70+
* Construct a {@link PointId} from the provided uuid string.
71+
*
72+
* @param uuid
73+
* @return
74+
*/
6375
public static PointId pointId(String uuid) {
6476
Objects.requireNonNull(uuid, "The provided uuid must not be null");
6577
return PointId.newBuilder().setUuid(UUID.fromString(uuid).toString()).build();
6678
}
6779

80+
/**
81+
* Create a list of {@link PointId}d
82+
*
83+
* @param ids
84+
* @return
85+
*/
86+
public static List<PointId> pointIds(long... ids) {
87+
List<PointId> list = new ArrayList<>();
88+
for (long id : ids) {
89+
list.add(pointId(id));
90+
}
91+
return list;
92+
}
93+
6894
public static PointStruct point(String uuid, float[] vectorData, Map<String, Value> payload) {
69-
return toPointStruct(pointId(uuid), vectorData, payload);
95+
return point(pointId(uuid), vectorData, payload);
7096
}
7197

7298
public static PointStruct point(UUID uuid, float[] vectorData, Map<String, Value> payload) {
73-
return toPointStruct(pointId(uuid), vectorData, payload);
99+
return point(pointId(uuid), vectorData, payload);
74100
}
75101

76102
public static PointStruct point(long id, float[] vectorData, Map<String, Value> payload) {
77-
return toPointStruct(pointId(id), vectorData, payload);
78-
}
79-
80-
public static List<PointId> pointIds(long... ids) {
81-
List<PointId> list = new ArrayList<>();
82-
for (long id : ids) {
83-
list.add(pointId(id));
84-
}
85-
return list;
103+
return point(pointId(id), vectorData, payload);
86104
}
87105

88-
public static PointStruct toPointStruct(PointId id, float[] vectorData, Map<String, Value> payload) {
106+
/**
107+
* Construct a new {@link PointStruct} using the provided data.
108+
*
109+
* @param id
110+
* @param vectorData
111+
* @param payload
112+
* @return
113+
*/
114+
public static PointStruct point(PointId id, float[] vectorData, Map<String, Value> payload) {
89115
Objects.requireNonNull(id, "A pointId must be provided.");
90116
Vector vector = ModelHelper.vector(vectorData);
91117
Builder builder = PointStruct.newBuilder()

0 commit comments

Comments
 (0)