qdrant

# 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 ```bash 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:** ```xml <dependency> <groupId>io.qdrant</groupId> <artifactId>client</artifactId> <version>1.15.0</version> </dependency> ``` **Gradle:** ```gradle implementation 'io.qdrant:client:1.15.0' ``` ### 3. Initialize Client ```java QdrantClient client = new QdrantClient( QdrantGrpcClient.newBuilder("localhost").build()); ``` For production with API key: ```java QdrantClient client = new QdrantClient( QdrantGrpcClient.newBuilder("localhost", 6334, false) .withApiKey("YOUR_API_KEY") .build()); ``` ### 4. Create Collection ```java 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 ```java 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 ```java 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: ```java 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: ```java EmbeddingStore<TextSegment> embeddingStore = QdrantEmbeddingStore.builder() .collectionName("rag-collection") .host("localhost") .port(6334) .apiKey("YOUR_API_KEY") .build(); ``` Spring Boot configuration with LangChain4j: ```java @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: ```java @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 ```java @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 ```java public void upsertForTenant(String tenantId, List<PointStruct> points) { String collectionName = "tenant_" + tenantId + "_documents"; client.upsertAsync(collectionName, points).get(); } ``` ### Docker Compose for Production ```yaml services: qdrant: image: qdrant/qdrant:v1.7.0 ports: - "6333:6333" - "6334:6334" volumes: - qdrant_storage:/qdrant/storage ``` ## References - [Qdrant API Reference](references/references.md) — Complete client API documentation - [Complete Spring Boot Examples](references/examples.md) — Full application implementations - [Qdrant Documentation](https://qdrant.tech/documentation/) - [LangChain4j Documentation](https://langchain4j.dev/) ## 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.