The emergence of Large Language Models (LLM) has propelled Generative AI and surfaced one of its key components to a broad audience: Embeddings. Embeddings are a vector representation of data in a high-dimensional space capturing their semantic meaning. Vector representations allow for more efficient and effective search (Vector Search) of similar items. Vector search is typically used to build Retrieval-augmented generation (RAG) systems and so there is demand for vector databases. While new vector databases are on the rise, existing database engines are gradually incorporating vector search capabilities leading to two main types of databases: * Dedicated Vector Databases * Database Engines with Vector Search Capabilities Dedicated Vector Databases originate in the need for searching for similar items in high-dimensional spaces. They are optimized for this purpose and often use specialized indexing techniques to improve search performance. Examples include Pinecone, Weaviate, Milvus, and Qdrant. All of these are projects emerged around the early 2020s. A Vector Search typically requires a vector, which is an array of single-precision `float` numbers, a namespace (something like a table or collection) and a Top K (the number of results to return) argument. Vector search then run an Approximate Nearest Neighbor (ANN) or k-Nearest Neighbors (kNN) search. Those databases allow additional filtering similarity and metadata fields, however, the core of the search gravitates around vector representations. Existing Database Engines such as Postgres (pgvector), Oracle, and MongoDB have gradually added vector search capabilities to their engines. They are not dedicated vector databases but rather general-purpose databases with vector search capabilities. Their strength lies in their ability to handle a wide range of data types and queries, especially when it comes to combining vector search with traditional queries. They also have a long history of supporting administrative tasks with a well-understood operating model for backup and recovery, scaling, and maintenance. Another aspect to consider is that these databases are already being used in production, containing large amounts of existing data. ## Elephant in the Room Spring AI has a wide range of integrations with vector stores. The obvious question is: "Why has Spring AI support for Vector Search and Spring Data does not?". And why does that even matter? The goal of Spring AI is to simplify the process of building AI-powered applications by providing a consistent programming model and abstractions. It focuses on integrating AI capabilities into Spring applications and provides a unified API for working with various AI models and services. AI is a hot topic: Several database vendors have contributed their integration for vector search to Spring AI to enable use-cases such as Retrieval Augmented Generation. This is a great example of how Open Source can drive innovation and collaboration in the database space. When we consider what's after the peak of AI's hype cycle, we are faced with day-2 operations. Data has a lifecycle, new LLM models come and go, some are better for certain tasks or languages than others. While Spring AI's `VectorStore` has the means to reflect of data lifecycle to some extent, it is by no means its primary focus. And here comes Spring Data into play. Spring Data is all about data models, access, and data lifecycle. It provides a consistent programming model for accessing different data stores, including relational databases, NoSQL databases, and more. Spring Data's focus is on simplifying data access and management, making it easier to work with various data sources in a consistent way. Wouldn't it then make sense to have Vector Search capabilities in Spring Data? Yes, it would. ## Vector Search in Spring Data With Spring Data 3.5, we've introduced a `Vector` type to simplify usage of vector data in entities. Vector data types are not common in typical domain models. The closest resemblance of vector data has been geospatial data types such as `Point`, `Polygon`, etc. but even those are not common. Domain models rather consist of primitive types and value types reflecting the domain they are used in. Vector properties use either vendor-specific types (such as Cassandra's `CqlVector`) or use some sort of array, like `float[]`. In the latter case, using arrays introduces quite some accidental complexity: Java arrays are pointers. Their underlying actual array data is mutable. Carrying arrays around isn't too common either. Your domain model can leverage `Vector` property type reducing the risk of accidentally mutating the underlying data and giving the otherwise `float[]` a semantic context. Persisting and retrieving `Vector` properties is handled by Spring Data for modules where Spring Data handles object mapping. For JPA, you will require additional converters. Vector vector = Vector.of(0.0001f, 1.12345f, 2.23456f, 3.34567f, 4.45678f); `Vector.of(…)` creates an immutable `Vector` instance and a copy of the given input array. While this is useful for most scenarios, performance-sensitive arrangements that want to reduce GC pressure can retain the reference to the original array: Vector vector = Vector.unsafe(new float[]{0.0001f, 1.12345f, 2.23456f, 3.34567f, 4.45678f}); You can obtain a safe (copied) variant of the `float[]` array by calling `toFloatArray()` respective `toDoubleArray()` if you want to use `double[]`. Alternatively, you can access the `Vector`'s source through `getSource()`. Depending on your data store, you might need to equip your data model with additional annotations to indicate e.g. the number of dimensions or its precision. When running a Vector search operation, each database uses a very different API. Let's take a look at MongoDB and Apache Cassandra. In MongoDB, Vector Search is used through its Aggregation Framework requiring an aggregation stage: class Comment { String id; String language; String comment; Vector embedding; // getters, setters, … } VectorSearchOperation vectorSearch = VectorSearchOperation.search("euclidean-index") .path("embedding") .vector(0.0001f, 1.12345f, 2.23456f, 3.34567f, 4.45678f) // float[], Vector, or Mongo's BinaryVector .limit(10) // Top-K .numCandidates(200) .filter(where("language").is("DE")) .searchType(SearchType.ANN) .withSearchScore(); AggregationResults results = template.aggregate(newAggregation(vectorSearch), Comment.class, Document.class); `VectorSearchOperation` offers a fluent API guiding you through each step of the operation reflecting the underlying MongoDB API in a convenient way. Let's have a look at Apache Cassandra. Cassandra uses CQL (Cassandra Query Language) to run queries against the database. Cassandra Vector Search uses the same approach. With Cassandra, Spring Data users have the choice to either use Spring Data Cassandra's `Query` API or the native CQL API to run a Vector Search: @Table("comments") class CommentVectorSearchResult { @Id String id; double score; String language; String comment; // getters, setters, … } CassandraTemplate template = … Query query = Query.select(Columns.from("id", "language", "comment") .select("embedding", it -> it.similarity(Vector.of(1.1f, 2.2f)).cosine().as("score"))) .sort(VectorSort.ann("embedding", Vector.of(1.1f, 2.2f))) .limit(10); List select = template.select(query, VectorSearchResult.class); The CQL variant would look like this: CassandraTemplate template = … List> result = template.getCqlOperations().queryForList(""" SELECT id, language, comment, similarity_cosine(embedding, ?0) AS score FROM my_table ORDER BY embedding ANN OF ?0 LIMIT ?1 """, CqlVector.newInstance(1.1f, 2.2f), 10); All in all these are small and simple examples of how to use Vector Search in Spring Data. Coming from a domain model perspective, representing search results is different from representing the domain model itself. Clearly, one could favor Java Records over classes but that isn't what the differences are about. Have you noticed the additional `CommentVectorSearchResult` class or `List` (MongoDB's native document type)? Cassandra has no detached raw type that you could use to consume result so we need `CommentVectorSearchResult` as dedicated type to map this specific Cassandra search result. We not only want to access domain data, but also the score. MongoDB's Java driver ships with a `Document` type that behaves is essentially a `Map`. That's not how we envisioned a modern programming model. When searching for items, the result is not a list of domain objects but rather a list of search results. How do we even represent those? And can't we have a uniform programming model that combines the simplicity of expressing what I want with the power of the underlying database? ## Vector Search Methods If it is a search result, then it is a `SearchResult`. What if repository methods could return `SearchResults`? Searching is a slightly different concept than querying (finding) entities. Beyond that, search methods would work similarly to existing query methods. interface CommentRepository extends Repository { @VectorSearch(indexName = "euclidean-index") SearchResults searchTop10ByLanguageAndEmbeddingNear(String language, Vector vector, Similarity similarityThreshold); @VectorSearch(indexName = "euclidean-index") SearchResults searchByLanguageAndEmbeddingWithin(String language, Vector vector, Range range, Limit topK); } SearchResults results = repository.searchTop10ByLanguageAndEmbeddingNear("DE", Vector.of(0.0001f, 1.12345f, 2.23456f, 3.34567f, 4.45678f), Similarity.of(0.9)); for (SearchResult result : results) { Score score= result.getScore(); Comment comment = result.getContent(); // … } The example above shows a search method that runs a Vector search. Searching in MongoDB requires an index hint that is specific to MongoDB. Beyond that, query derivation creates the pre-filter to filter by `language`. By leveraging `Near` and `Within` keywords, Spring Data MongoDB is able to associate the given `Vector` and `Similarity` predicate to customize the actual Vector Search operation. The result is returned as `SearchResults` providing access to the found entity and its score respective similarity value. Using Vector Search with Postgres or Oracle is even simpler. The following example shows a Vector Search method in a Spring Data JPA repository through Hibernate's `hibernate-vector` module: interface CommentRepository extends Repository { SearchResults searchTop10ByLanguageAndEmbeddingNear(String language, Vector vector, Score scoreThreshold); SearchResults searchByLanguageAndEmbeddingWithin(String language, Vector vector, Range range, Limit topK); } `Near` and `Within` Search methods require a `Vector` and a `Score`, `Similarity` (subtype of Score), or `Range` parameter to determine how similarity/distance is calculated. Traditionally, query methods are intended to express predicates of a query while a typical Vector search is more about the Top-K limiting. That is something we have to consider in the future. Search methods can also leverage annotations in the same way that query methods do. The following example shows a search method in a Spring Data JPA: interface CommentRepository extends Repository { @Query(""" SELECT c, cosine_distance(c.embedding, :embedding) as distance FROM Comment c WHERE c.language = :language AND cosine_distance(c.embedding, :embedding) <= :distance ORDER BY cosine_distance(c.embedding, :embedding) asc """) SearchResults searchAnnotatedByLanguage(String language, Vector embedding, Score distance); } While it's not obvious, pgvector and Oracle calculate distances to compute a score. Spring Data allows consuming the native score value either directly or, when using `Similarity.of(…)` as argument with the appropriate `ScoringFunction`, Spring Data normalizes the native score into a similarity range between 0 and 1. // Using a native score SearchResults results = repository.searchAnnotatedByLanguage(…, Score.of(0.1, ScoringFunction.cosine())); // SearchResult.score will be an instance of Similarity SearchResults results = repository.searchAnnotatedByLanguage(…, Similarity.of(0.9, ScoringFunction.cosine())); A final note on `Vector` with JPA. When using JPA, you can use `Vector` in your domain model to store the vector assuming you have configured an `AttributeConverter` to convert the `Vector` into a database type. However, when using Hibernate's distance methods (such as `cosine_distance`), Hibernate doesn't consider any Attribute Converters, hence your model must resort to using `float[]` or `double[]` as embedding type: @Table class Comment { @Id @GeneratedValue(strategy = GenerationType.IDENTITY) private Integer id; private String language; private String comment; @JdbcTypeCode(SqlTypes.VECTOR) @Array(length = 5) private float[] embedding; } ## Conclusion We've explored the world of Vector Search and how it fits into the Spring ecosystem along with Vector Search origins in Spring AI. Support for the `Vector` type ships with Spring Data 3.5 (2025.0) in the May 2025 release. Vector Search Methods are a preview feature of the Spring Data 4.0 (2025.1) release train with first implementations for JPA through Hibernate Vector, MongoDB and Apache Cassandra. We're excited to hear what you think about Vector Search methods and how we can improve them further. You can find the documentation about Vector Search in the reference documentation, in JPA, MongoDB, and Cassandra.

Query Builder