Semantic search enhances traditional keyword-based search by understanding the meaning and context of queries rather than relying on exact keyword matches. This approach is useful for applications such as recommendation systems, document retrieval, intelligent chatbots, and enterprise knowledge management.
In this article, we will implement semantic search using Spring AI and PGVector, an extension for PostgreSQL that enables vector-based similarity search. We will integrate Ollama, an open-source AI model framework, to generate embeddings that represent the semantic meaning of text.
1. Adding Dependencies
To set up a Spring Boot project with Spring AI, PGVector, and Ollama, we will generate the project using Spring Initializr.
After adding the required dependencies, your pom.xml should look like this:
01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 16 17 18 19 20 21 | <dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-ollama-spring-boot-starter</artifactId></dependency><dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-pgvector-store-spring-boot-starter</artifactId></dependency><dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-docker-compose</artifactId> <scope>runtime</scope> <optional>true</optional></dependency><dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-spring-boot-docker-compose</artifactId> <scope>runtime</scope> <optional>true</optional></dependency> |
Each dependency in the pom.xml file serves a specific purpose in our application. Here’s what each one does:
spring-ai-ollama-spring-boot-starter: Integrates Ollama and Spring Boot for generating vector embeddings of text. This converts textual data, such as movie descriptions, into numerical vector representations, which are then stored in PGVector for similarity search.spring-ai-pgvector-store-spring-boot-starter: Provides support for storing and retrieving vector embeddings in PostgreSQL using PGVector.spring-boot-docker-compose: Enables Spring Boot to automatically manage Docker Compose. It enables Spring Boot applications to automatically start required Docker containers locally, ensuring PostgreSQL and Ollama are available without manual intervention.spring-ai-spring-boot-docker-compose: A helper dependency for managing Spring AI-related services with Docker Compose. It works alongsidespring-boot-docker-composeto ensure that AI models and vector databases are started and connected properly within a Dockerized environment.
2. Setting Up the Environment
To get started, we need to configure our environment using Docker. Below is the docker-compose.yml file, which sets up PostgreSQL with PGVector and Ollama:
01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 | services: postgres: image: pgvector/pgvector:pg17 environment: POSTGRES_DB: movie_vector_db POSTGRES_USER: postgres POSTGRES_PASSWORD: postgres ports: - "5434:5432" healthcheck: test: [ "CMD-SHELL", "pg_isready -U postgres" ] interval: 10s timeout: 5s retries: 5 ollama: image: ollama/ollama:latest ports: - "11432:11434" volumes: - ollama_data:/root/.ollamavolumes: ollama_data: |
The PostgreSQL service uses the pgvector/pgvector:pg17 image, which includes PostgreSQL 17 with PGVector support for storing and searching vector embeddings. It initializes a database named movie_vector_db, setting postgres as both the username and password. Additionally, it maps port 5432 inside the container to 5434 on the host machine.
The Ollama service is used to generate text embeddings and maps port 11434 inside the container to 11432 on the host machine for external access. It also utilizes a named volume (ollama_data) to designate where to persist AI models (Ollama is using an AI embedding model internally to generate embeddings).
3. Application Properties Configuration
We need to configure Spring Boot to interact with PGVector and Ollama. Below is the application.properties file:
01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 16 17 18 19 | spring.application.name=spring-ai-pgvector-movie-searchspring.ai.ollama.init.pull-model-strategy=when_missingspring.ai.ollama.init.chat.include=truespring.ai.ollama.embedding.options.model=nomic-embed-textspring.ai.vectorstore.pgvector.initialize-schema=truespring.ai.vectorstore.pgvector.dimensions=768spring.ai.vectorstore.pgvector.index-type=hnswspring.docker.compose.file=docker-compose.ymlspring.docker.compose.enabled=truespring.datasource.url=jdbc:postgresql://localhost:5434/movie_vector_dbspring.datasource.username=postgresspring.datasource.password=postgresspring.datasource.driver-class-name=org.postgresql.Driverspring.jpa.database-platform=org.hibernate.dialect.PostgreSQLDialect |
This application.properties file configures the application by defining properties for Ollama AI, PGVector, database connectivity, and Docker Compose integration.
pull-model-strategy=when_missing: Ensures that Ollama will download and use an AI model only if it is not already available, preventing unnecessary downloads.chat.include=true: Enables Ollama’s chat capability, allowing it to process conversational queries.embedding.options.model=nomic-embed-text: Specifies the embedding AI model Ollama will use (in our case,nomic-embed-text), to convert text into vector representations for semantic search.initialize-schema=true: Automatically initializes the PGVector schema in PostgreSQL if it doesn’t exist.dimensions=768: Sets the embedding vector dimension size to 768, aligning with the AI model’s output (in our case,nomic-embed-text).index-type=hnsw: Uses Hierarchical Navigable Small World (HNSW) indexing for faster vector similarity search.spring.docker.compose.file=docker-compose.yml: Specifies the Docker Compose file to be used when starting the application.spring.docker.compose.enabled=true: Enables automatic service management, ensuring PostgreSQL and Ollama containers start when the application runs.spring.datasource.url=jdbc:postgresql://localhost:5434/movie_vector_db: Configures the application to connect to the PostgreSQL database (movie_vector_db) running on port 5434.spring.datasource.username=postgres&spring.datasource.password=postgres: Provides authentication credentials for database access.spring.datasource.driver-class-name=org.postgresql.Driver: Specifies the PostgreSQL JDBC driver required for database connectivity.spring.jpa.database-platform=org.hibernate.dialect.PostgreSQLDialect: Instructs Hibernate to use PostgreSQL-specific SQL dialect, optimizing database queries for PostgreSQL.
4. Creating the Movie Entity
Below is a simple record class for movies:
1 2 3 | public record Movie(String title, String director, String description) {} |
Each movie has a title, director, and description. This will be converted into embeddings for similarity search.
5. Storing Movies in PGVector
To perform a semantic search, we must first store movies as embeddings in PGVector.
01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 | @Componentpublic class MovieStoragePipeline { private final VectorStore vectorStore; public MovieStoragePipeline(VectorStore vectorStore) { this.vectorStore = vectorStore; } @PostConstruct void run() { var movies = List.of( new Movie("Inception", "Christopher Nolan", "A thief who enters the dreams of others to steal their secrets is given a chance to erase his criminal record."), new Movie("Interstellar", "Christopher Nolan", "A group of astronauts travels through a wormhole in search of a new home for humanity."), new Movie("The Social Network", "David Fincher", "The story of Mark Zuckerberg and the creation of Facebook, a revolutionary social media platform."), new Movie("Parasite", "Bong Joon-ho", "A poor family infiltrates a wealthy household, leading to unexpected consequences."), new Movie("Blade Runner", "Ridley Scott", "Set in a dystopian future, a blade runner is tasked with hunting down bioengineered beings known as replicants."), new Movie("High-Rise", "Ben Wheatley", "Residents of a luxury tower block descend into chaos as class divisions and societal breakdowns emerge."), new Movie("Children of Men", "Alfonso Cuarón", "In a world where humans have become infertile, a disillusioned bureaucrat becomes the unlikely champion in the fight for humanity's survival."), new Movie("The Hunger Games", "Gary Ross", "In a dystopian future, a young girl volunteers to participate in a televised battle to the death.") ); List<Document> documents = movies.stream() .map(movie -> new Document(movie.toString())) .toList(); vectorStore.add(documents); }} |
The MovieStoragePipeline class is responsible for storing movie data in PGVector for semantic search. It initializes a list of Movie objects, each containing a title, director, and description. Using the @PostConstruct annotation, the run() method executes automatically after the class is instantiated, ensuring that the movies are added to the vector database at application startup. Each Movie object is converted into a Document and then stored in the VectorStore, allowing efficient similarity searches based on movie descriptions.
6. Implementing the Semantic Search Controller
The Semantic Search Controller below handles user queries by retrieving similar movie descriptions from PGVector using vector-based similarity search. It leverages semantic understanding, allowing users to find relevant movies even if their query does not contain exact title matches. The controller processes search requests, converts the query into an embedding, and retrieves the most similar stored vectors, making the search experience more intuitive.
01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 16 17 18 19 20 21 | @RestController@RequestMapping("/movies")public class MovieSearchController { private final VectorStore vectorStore; public MovieSearchController(VectorStore vectorStore) { this.vectorStore = vectorStore; } @PostMapping("/search") List<String> findSimilarMovies(@RequestBody String query) { return vectorStore.similaritySearch(SearchRequest.builder() .query(query) .topK(3) .build()) .stream() .map(Document::getText) .toList(); }} |
The MovieSearchController class exposes an endpoint (POST /movies/search) that takes a textual query from the user, converts it into an embedding, and retrieves the top three most similar movie descriptions. The vectorStore performs the similarity search, returning matching documents based on vector proximity rather than exact keyword matches.
7. Running the Application
The application is now ready to run with all configurations and components in place. When started, Spring Boot automatically launches the required Docker containers (PostgreSQL with PGVector and Ollama) and initializes the vector store. The MovieStoragePipeline class preloads a set of movies into PGVector, ensuring that the database has meaningful data for similarity searches.
Once the application is running, we can send POST requests to the /movies/search endpoint with a query like this:
1 | curl -X POST --data "dystopian future" http://localhost:8080/movies/search |
Example Response:
1 | ["Movie[title=The Hunger Games, director=Gary Ross, description=In a dystopian future, a young girl volunteers to participate in a televised battle to the death.]","Movie[title=Blade Runner, director=Ridley Scott, description=Set in a dystopian future, a blade runner is tasked with hunting down bioengineered beings known as replicants.]","Movie[title=The Social Network, director=David Fincher, description=The story of Mark Zuckerberg and the creation of Facebook, a revolutionary social media platform.]"] |
This response demonstrates the application’s ability to perform semantic searches, retrieving movies that conceptually match the query rather than relying solely on exact keyword matches.
8. Conclusion
In this article, we explored the integration of Spring AI with PGVector and Ollama to build a document query system. We began by setting up the necessary environment, including configuring PostgreSQL with the PGVector extension and integrating the Ollama AI service. We then demonstrated how to implement semantic search capabilities, enabling the application to process natural language queries and retrieve relevant documents effectively.
9. Download the Source Code
This article covered semantic search using Spring AI and PGVector.
You can download the full source code of this example here: spring ai pgvector semantic search
