Skip to content

qdrant/java-client

Repository files navigation

Qdrant   Java

Java library for the Qdrant vector search engine.

Javadoc Tests Apache 2.0 License Discord Roadmap 2024

Qdrant Java Client

Java client library with handy utility methods and overloads for interfacing with Qdrant.

📥 Installation

Important

Requires Java 8 or above.

To install the library, add the following lines to your build config file.

Maven

<dependency>
  <groupId>io.qdrant</groupId>
  <artifactId>client</artifactId>
  <version>1.12.0</version>
</dependency>

SBT

libraryDependencies += "io.qdrant" % "client" % "1.12.0"

Gradle

implementation 'io.qdrant:client:1.11.0'

Note

Please make sure to include all necessary dependencies listed here in your project.

📖 Documentation

🔌 Getting started

Creating a client

A client can be instantiated with

QdrantClient client = 
  new QdrantClient(QdrantGrpcClient.newBuilder("localhost").build());

which creates a client that will connect to Qdrant on https://localhost:6334.

Internally, the high-level client uses a low-level gRPC client to interact with Qdrant. Additional constructor overloads provide more control over how the gRPC client is configured. The following example configures a client to use TLS, validating the certificate using the root CA to verify the server's identity instead of the system's default, and also configures API key authentication:

ManagedChannel channel = Grpc.newChannelBuilder(
  "localhost:6334",
  TlsChannelCredentials.newBuilder()
    .trustManager(new File("ssl/ca.crt"))
    .build())
.build();

QdrantClient client = new QdrantClient(
  QdrantGrpcClient.newBuilder(channel)
    .withApiKey("<apikey>")
    .build());

The client implements AutoCloseable, though a client will typically be created once and used for the lifetime of the application. When a client is constructed by passing a ManagedChannel, the client does not shut down the channel on close by default. The client can be configured to shut down the channel on closing with

ManagedChannel channel = Grpc.newChannelBuilder(
  "localhost:6334", 
  TlsChannelCredentials.create())
.build();

QdrantClient client = new QdrantClient(
  QdrantGrpcClient.newBuilder(channel, true)
    .withApiKey("<apikey>")
    .build());

All client methods return ListenableFuture<T>.

Working with collections

Once a client has been created, create a new collection

client.createCollectionAsync("{collection_name}",
  VectorParams.newBuilder()
    .setDistance(Distance.Cosine)
    .setSize(4)
    .build())
  .get();

Insert vectors into a collection

// import static convenience methods
import static io.qdrant.client.PointIdFactory.id;
import static io.qdrant.client.ValueFactory.value;
import static io.qdrant.client.VectorsFactory.vectors;

List<PointStruct> points =
    List.of(
        PointStruct.newBuilder()
            .setId(id(1))
            .setVectors(vectors(0.32f, 0.52f, 0.21f, 0.52f))
            .putAllPayload(
                Map.of(
                    "color", value("red"),
                    "rand_number", value(32)))
            .build(),
        PointStruct.newBuilder()
            .setId(id(2))
            .setVectors(vectors(0.42f, 0.52f, 0.67f, 0.632f))
            .putAllPayload(
                Map.of(
                    "color", value("black"),
                    "rand_number", value(53),
                    "extra_field", value(true)))
            .build());

UpdateResult updateResult = client.upsertAsync("{collection_name}", points).get();

Search for similar vectors

List<ScoredPoint> points =
    client
        .searchAsync(
            SearchPoints.newBuilder()
                .setCollectionName("{collection_name}")
                .addAllVector(List.of(0.6235f, 0.123f, 0.532f, 0.123f))
                .setLimit(5)
                .build())
        .get();

Search for similar vectors with filtering condition

// import static convenience methods
import static io.qdrant.client.ConditionFactory.range;

List<ScoredPoint> points = client.searchAsync(SearchPoints.newBuilder()
  .setCollectionName("{collection_name}")
  .addAllVector(List.of(0.6235f, 0.123f, 0.532f, 0.123f))
  .setFilter(Filter.newBuilder()
    .addMust(range("rand_number", Range.newBuilder().setGte(3).build()))
    .build())
  .setLimit(5)
  .build()
).get();

⚖️ LICENSE

Apache 2.0 © 2024