Original skill document
Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.
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/qdrantAccess: 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/storageReferences
- 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.
