Java library for the Qdrant vector search engine.

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.18.1</version>
</dependency>

SBT

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

Gradle

implementation 'io.qdrant:client:1.18.1'

[!NOTE]
Please make sure to include all necessary dependencies listed here in your project.

📖 Documentation

• Usage examples are available throughout the Qdrant documentation and API Reference.
• JavaDoc Reference

🔌 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