Qdrant Vector Database Integration

Overview

Qdrant is an AI-native vector database for semantic search and similarity retrieval. This skill provides patterns for integrating Qdrant with Java applications, focusing on Spring Boot and LangChain4j integration.

When to Use

• Semantic search or recommendation systems in Spring Boot applications

• RAG pipelines with Java and LangChain4j

• Vector database integration for AI/ML applications

• High-performance similarity search with filtered queries

Instructions

1. Deploy Qdrant with Docker

docker run -p 6333:6333 -p 6334:6334
-v "$(pwd)/qdrant_storage:/qdrant/storage:z"
qdrant/qdrant

Access: REST API at http://localhost:6333 , gRPC at http://localhost:6334 .

2. Add Dependencies

Maven:

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

Gradle:

implementation 'io.qdrant:client:1.15.0'

3. Initialize Client

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

For production with API key:

QdrantClient client = new QdrantClient( QdrantGrpcClient.newBuilder("localhost", 6334, false) .withApiKey("YOUR_API_KEY") .build());

4. Create Collection

client.createCollectionAsync("search-collection", VectorParams.newBuilder() .setDistance(Distance.Cosine) .setSize(384) .build() ).get();

Validation: Verify the collection was created by checking client.getCollectionAsync("search-collection").get() .

5. Upsert Vectors

List<PointStruct> points = List.of( PointStruct.newBuilder() .setId(id(1)) .setVectors(vectors(0.05f, 0.61f, 0.76f, 0.74f)) .putAllPayload(Map.of("title", value("Spring Boot Documentation"))) .build() ); client.upsertAsync("search-collection", points).get();

Validation: Check that client.upsertAsync(...).get() completes without throwing.

6. Search Vectors

List<ScoredPoint> results = client.queryAsync( QueryPoints.newBuilder() .setCollectionName("search-collection") .setLimit(5) .setQuery(nearest(0.2f, 0.1f, 0.9f, 0.7f)) .build() ).get();

Filtered search:

List<ScoredPoint> results = client.searchAsync( SearchPoints.newBuilder() .setCollectionName("search-collection") .addAllVector(List.of(0.62f, 0.12f, 0.53f, 0.12f)) .setFilter(Filter.newBuilder() .addMust(range("category", Range.newBuilder().setEq("docs").build())) .build()) .setLimit(5) .build()).get();

LangChain4j Integration

For RAG pipelines, use LangChain4j's high-level abstractions:

EmbeddingStore<TextSegment> embeddingStore = QdrantEmbeddingStore.builder() .collectionName("rag-collection") .host("localhost") .port(6334) .apiKey("YOUR_API_KEY") .build();

Spring Boot configuration with LangChain4j:

@Bean public EmbeddingStore<TextSegment> embeddingStore() { return QdrantEmbeddingStore.builder() .collectionName("rag-collection") .host(host) .port(port) .build(); }

@Bean public EmbeddingModel embeddingModel() { return new AllMiniLmL6V2EmbeddingModel(); }

Spring Boot Integration

Inject the client via configuration:

@Configuration public class QdrantConfig { @Value("${qdrant.host:localhost}") private String host;

@Value("${qdrant.port:6334}")
private int port;

@Bean
public QdrantClient qdrantClient() {
    return new QdrantClient(
        QdrantGrpcClient.newBuilder(host, port, false).build());
}

}

Examples

REST Search Endpoint

@RestController @RequestMapping("/api/search") public class SearchController { private final VectorSearchService searchService;

public SearchController(VectorSearchService searchService) {
    this.searchService = searchService;
}

@GetMapping
public List<ScoredPoint> search(@RequestParam String query) {
    List<Float> queryVector = embeddingModel.embed(query).content().vectorAsList();
    return searchService.search("documents", queryVector);
}

}

Best Practices

• Distance metric: Cosine for normalized text embeddings, Euclidean for non-normalized.

• Batch upserts: Use batch operations over individual point insertions.

• Connection pooling: Configure connection pooling for high-throughput production workloads.

• Error handling: Wrap async operations in try/catch for ExecutionException/InterruptedException.

• API keys: Store in environment variables or Spring config, never hardcode.

Advanced Patterns

Multi-tenant Storage

public void upsertForTenant(String tenantId, List<PointStruct> points) { String collectionName = "tenant_" + tenantId + "_documents"; client.upsertAsync(collectionName, points).get(); }

Docker Compose for Production

services: qdrant: image: qdrant/qdrant:v1.7.0 ports: - "6333:6333" - "6334:6334" volumes: - qdrant_storage:/qdrant/storage

References

• Qdrant API Reference — Complete client API documentation

• Complete Spring Boot Examples — Full application implementations

• Qdrant Documentation

• LangChain4j Documentation

Constraints and Warnings

• Vector dimensions must match the embedding model exactly; mismatched dimensions cause upsert errors.

• Input validation: Sanitize all document content before ingestion; untrusted payloads may contain prompt injection attacks.

• Content filtering: Apply content filtering on retrieved documents before passing them to the LLM.

• Large collections require proper indexing for acceptable search performance.

• Use gRPC API (port 6334) for production; REST API (port 6333) for debugging only.

• Collection recreation deletes all data; implement backup strategies for production environments.