Refactor SearchRequest builder methods

- Add a new Builder inner class to move all the builder methods and deprecate the existing builder methods
 - Update docs and references

spring-ai-core/src/main/java/org/springframework/ai/chat/client/advisor/QuestionAnswerAdvisor.java

@@ -88,7 +88,7 @@ public class QuestionAnswerAdvisor implements CallAroundAdvisor, StreamAroundAdv
 	 * @param vectorStore The vector store to use
 	 */
 	public QuestionAnswerAdvisor(VectorStore vectorStore) {
-		this(vectorStore, SearchRequest.defaults(), DEFAULT_USER_TEXT_ADVISE);
+		this(vectorStore, SearchRequest.builder().build(), DEFAULT_USER_TEXT_ADVISE);
 	}
 
 	/**
@@ -218,8 +218,9 @@ public class QuestionAnswerAdvisor implements CallAroundAdvisor, StreamAroundAdv
 		// 2. Search for similar documents in the vector store.
 		String query = new PromptTemplate(request.userText(), request.userParams()).render();
 		var searchRequestToUse = SearchRequest.from(this.searchRequest)
-			.withQuery(query)
-			.withFilterExpression(doGetFilterExpression(context));
+			.query(query)
+			.filterExpression(doGetFilterExpression(context))
+			.build();
 
 		List<Document> documents = this.vectorStore.similaritySearch(searchRequestToUse);
 
@@ -273,7 +274,7 @@ public class QuestionAnswerAdvisor implements CallAroundAdvisor, StreamAroundAdv
 
 		private final VectorStore vectorStore;
 
-		private SearchRequest searchRequest = SearchRequest.defaults();
+		private SearchRequest searchRequest = SearchRequest.builder().build();
 
 		private String userTextAdvise = DEFAULT_USER_TEXT_ADVISE;
 

spring-ai-core/src/main/java/org/springframework/ai/chat/client/advisor/VectorStoreChatMemoryAdvisor.java

@@ -138,10 +138,12 @@ public class VectorStoreChatMemoryAdvisor extends AbstractChatMemoryAdvisor<Vect
 			advisedSystemText = this.systemTextAdvise;
 		}
 
-		var searchRequest = SearchRequest.query(request.userText())
-			.withTopK(this.doGetChatMemoryRetrieveSize(request.adviseContext()))
-			.withFilterExpression(DOCUMENT_METADATA_CONVERSATION_ID + "=='"
-					+ this.doGetConversationId(request.adviseContext()) + "'");
+		var searchRequest = SearchRequest.builder()
+			.query(request.userText())
+			.topK(this.doGetChatMemoryRetrieveSize(request.adviseContext()))
+			.filterExpression(
+					DOCUMENT_METADATA_CONVERSATION_ID + "=='" + this.doGetConversationId(request.adviseContext()) + "'")
+			.build();
 
 		List<Document> documents = this.getChatMemoryStore().similaritySearch(searchRequest);
 

spring-ai-core/src/main/java/org/springframework/ai/rag/retrieval/search/VectorStoreDocumentRetriever.java

@@ -75,10 +75,12 @@ public final class VectorStoreDocumentRetriever implements DocumentRetriever {
 	@Override
 	public List<Document> retrieve(Query query) {
 		Assert.notNull(query, "query cannot be null");
-		var searchRequest = SearchRequest.query(query.text())
-			.withFilterExpression(this.filterExpression.get())
-			.withSimilarityThreshold(this.similarityThreshold)
-			.withTopK(this.topK);
+		var searchRequest = SearchRequest.builder()
+			.query(query.text())
+			.filterExpression(this.filterExpression.get())
+			.similarityThreshold(this.similarityThreshold)
+			.topK(this.topK)
+			.build();
 		return this.vectorStore.similaritySearch(searchRequest);
 	}
 

spring-ai-core/src/main/java/org/springframework/ai/vectorstore/SearchRequest.java

@@ -26,12 +26,12 @@ import org.springframework.lang.Nullable;
 import org.springframework.util.Assert;
 
 /**
- * Similarity search request builder. Use the {@link #query(String)}, {@link #defaults()}
- * or {@link #from(SearchRequest)} factory methods to create a new {@link SearchRequest}
- * instance and then apply the 'with' methods to alter the default values.
+ * Similarity search request. Use the {@link SearchRequest#builder()} to create the
+ * instance of a {@link SearchRequest}.
  *
  * @author Christian Tzolov
  * @author Thomas Vitale
+ * @author Ilayaperumal Gopinathan
  */
 public final class SearchRequest {
 
@@ -47,7 +47,10 @@ public final class SearchRequest {
 	 */
 	public static final int DEFAULT_TOP_K = 4;
 
-	private String query;
+	/**
+	 * Default value is empty string.
+	 */
+	private String query = "";
 
 	private int topK = DEFAULT_TOP_K;
 
@@ -56,46 +59,209 @@ public final class SearchRequest {
 	@Nullable
 	private Filter.Expression filterExpression;
 
-	private SearchRequest(String query) {
-		this.query = query;
+	/**
+	 * Copy an existing {@link SearchRequest.Builder} instance.
+	 * @param originalSearchRequest {@link SearchRequest} instance to copy.
+	 * @return Returns new {@link SearchRequest.Builder} instance.
+	 */
+	public static Builder from(SearchRequest originalSearchRequest) {
+		return builder().query(originalSearchRequest.getQuery())
+			.topK(originalSearchRequest.getTopK())
+			.similarityThreshold(originalSearchRequest.getSimilarityThreshold())
+			.filterExpression(originalSearchRequest.getFilterExpression());
 	}
 
 	/**
-	 * Create a new {@link SearchRequest} builder instance with specified embedding query
-	 * string.
-	 * @param query Text to use for embedding similarity comparison.
-	 * @return Returns new {@link SearchRequest} builder instance.
+	 * @deprecated use {@link SearchRequest.Builder#query(String)} instead.
 	 */
+	@Deprecated(forRemoval = true, since = "1.0.0-M5")
 	public static SearchRequest query(String query) {
 		Assert.notNull(query, "Query can not be null.");
-		return new SearchRequest(query);
+		return builder().query(query).build();
 	}
 
 	/**
 	 * Create a new {@link SearchRequest} builder instance with an empty embedding query
-	 * string. Use the {@link #withQuery(String query)} to set/update the embedding query
-	 * text.
+	 * string. Use the {@link Builder#query(String query)} to set/update the embedding
+	 * query text.
 	 * @return Returns new {@link SearchRequest} builder instance.
+	 * @deprecated use {@link Builder#builder().build()} instead.
 	 */
-	public static SearchRequest defaults() {
-		return new SearchRequest("");
+	@Deprecated(forRemoval = true, since = "1.0.0-M5")
+	public static Builder defaults() {
+		return new Builder().topK(DEFAULT_TOP_K).similarityThresholdAll();
 	}
 
 	/**
-	 * Copy an existing {@link SearchRequest} instance.
-	 * @param originalSearchRequest {@link SearchRequest} instance to copy.
-	 * @return Returns new {@link SearchRequest} builder instance.
+	 * Builder for creating the SearchRequest instance.
+	 * @return the builder.
 	 */
-	public static SearchRequest from(SearchRequest originalSearchRequest) {
-		return new SearchRequest(originalSearchRequest.getQuery()).withTopK(originalSearchRequest.getTopK())
-			.withSimilarityThreshold(originalSearchRequest.getSimilarityThreshold())
-			.withFilterExpression(originalSearchRequest.getFilterExpression());
+	public static Builder builder() {
+		return new Builder();
 	}
 
 	/**
-	 * @param query Text to use for embedding similarity comparison.
-	 * @return this builder.
+	 * SearchRequest Builder.
 	 */
+	public static class Builder {
+
+		private final SearchRequest searchRequest = new SearchRequest();
+
+		/**
+		 * @param query Text to use for embedding similarity comparison.
+		 * @return this builder.
+		 */
+		public Builder query(String query) {
+			Assert.notNull(query, "Query can not be null.");
+			this.searchRequest.query = query;
+			return this;
+		}
+
+		/**
+		 * @param topK the top 'k' similar results to return.
+		 * @return this builder.
+		 */
+		public Builder topK(int topK) {
+			Assert.isTrue(topK >= 0, "TopK should be positive.");
+			this.searchRequest.topK = topK;
+			return this;
+		}
+
+		/**
+		 * Similarity threshold score to filter the search response by. Only documents
+		 * with similarity score equal or greater than the 'threshold' will be returned.
+		 * Note that this is a post-processing step performed on the client not the server
+		 * side. A threshold value of 0.0 means any similarity is accepted or disable the
+		 * similarity threshold filtering. A threshold value of 1.0 means an exact match
+		 * is required.
+		 * @param threshold The lower bound of the similarity score.
+		 * @return this builder.
+		 */
+		public Builder similarityThreshold(double threshold) {
+			Assert.isTrue(threshold >= 0 && threshold <= 1, "Similarity threshold must be in [0,1] range.");
+			this.searchRequest.similarityThreshold = threshold;
+			return this;
+		}
+
+		/**
+		 * Sets disables the similarity threshold by setting it to 0.0 - all results are
+		 * accepted.
+		 * @return this builder.
+		 */
+		public Builder similarityThresholdAll() {
+			this.searchRequest.similarityThreshold = 0.0;
+			return this;
+		}
+
+		/**
+		 * Retrieves documents by query embedding similarity and matching the filters.
+		 * Value of 'null' means that no metadata filters will be applied to the search.
+		 *
+		 * For example if the {@link Document#getMetadata()} schema is:
+		 *
+		 * <pre>{@code
+		 * &#123;
+		 * "country": <Text>,
+		 * "city": <Text>,
+		 * "year": <Number>,
+		 * "price": <Decimal>,
+		 * "isActive": <Boolean>
+		 * &#125;
+		 * }</pre>
+		 *
+		 * you can constrain the search result to only UK countries with isActive=true and
+		 * year equal or greater 2020. You can build this such metadata filter
+		 * programmatically like this:
+		 *
+		 * <pre>{@code
+		 * var exp = new Filter.Expression(AND,
+		 * 		new Expression(EQ, new Key("country"), new Value("UK")),
+		 * 		new Expression(AND,
+		 * 				new Expression(GTE, new Key("year"), new Value(2020)),
+		 * 				new Expression(EQ, new Key("isActive"), new Value(true))));
+		 * }</pre>
+		 *
+		 * The {@link Filter.Expression} is portable across all vector stores.<br/>
+		 *
+		 *
+		 * The {@link FilterExpressionBuilder} is a DSL creating expressions
+		 * programmatically:
+		 *
+		 * <pre>{@code
+		 * var b = new FilterExpressionBuilder();
+		 * var exp = b.and(
+		 * 		b.eq("country", "UK"),
+		 * 		b.and(
+		 * 			b.gte("year", 2020),
+		 * 			b.eq("isActive", true)));
+		 * }</pre>
+		 *
+		 * The {@link FilterExpressionTextParser} converts textual, SQL like filter
+		 * expression language into {@link Filter.Expression}:
+		 *
+		 * <pre>{@code
+		 * var parser = new FilterExpressionTextParser();
+		 * var exp = parser.parse("country == 'UK' && isActive == true && year >=2020");
+		 * }</pre>
+		 * @param expression {@link Filter.Expression} instance used to define the
+		 * metadata filter criteria. The 'null' value stands for no expression filters.
+		 * @return this builder.
+		 */
+		public Builder filterExpression(@Nullable Filter.Expression expression) {
+			this.searchRequest.filterExpression = expression;
+			return this;
+		}
+
+		/**
+		 * Document metadata filter expression. For example if your
+		 * {@link Document#getMetadata()} has a schema like:
+		 *
+		 * <pre>{@code
+		 * &#123;
+		 * "country": <Text>,
+		 * "city": <Text>,
+		 * "year": <Number>,
+		 * "price": <Decimal>,
+		 * "isActive": <Boolean>
+		 * &#125;
+		 * }</pre>
+		 *
+		 * then you can constrain the search result with metadata filter expressions like:
+		 *
+		 * <pre>{@code
+		 * country == 'UK' && year >= 2020 && isActive == true
+		 * Or
+		 * country == 'BG' && (city NOT IN ['Sofia', 'Plovdiv'] || price < 134.34)
+		 * }</pre>
+		 *
+		 * This ensures that the response contains only embeddings that match the
+		 * specified filer criteria. <br/>
+		 *
+		 * The declarative, SQL like, filter syntax is portable across all vector stores
+		 * supporting the filter search feature.<br/>
+		 *
+		 * The {@link FilterExpressionTextParser} is used to convert the text filter
+		 * expression into {@link Filter.Expression}.
+		 * @param textExpression declarative, portable, SQL like, metadata filter syntax.
+		 * The 'null' value stands for no expression filters.
+		 * @return this.builder
+		 */
+		public Builder filterExpression(@Nullable String textExpression) {
+			this.searchRequest.filterExpression = (textExpression != null)
+					? new FilterExpressionTextParser().parse(textExpression) : null;
+			return this;
+		}
+
+		public SearchRequest build() {
+			return this.searchRequest;
+		}
+
+	}
+
+	/**
+	 * @deprecated use {@link Builder#query(String)} instead.
+	 */
+	@Deprecated(forRemoval = true, since = "1.0.0-M5")
 	public SearchRequest withQuery(String query) {
 		Assert.notNull(query, "Query can not be null.");
 		this.query = query;
@@ -103,9 +269,9 @@ public final class SearchRequest {
 	}
 
 	/**
-	 * @param topK the top 'k' similar results to return.
-	 * @return this builder.
+	 * @deprecated use {@link Builder#topK(int)} instead.
 	 */
+	@Deprecated(forRemoval = true, since = "1.0.0-M5")
 	public SearchRequest withTopK(int topK) {
 		Assert.isTrue(topK >= 0, "TopK should be positive.");
 		this.topK = topK;
@@ -113,14 +279,9 @@ public final class SearchRequest {
 	}
 
 	/**
-	 * Similarity threshold score to filter the search response by. Only documents with
-	 * similarity score equal or greater than the 'threshold' will be returned. Note that
-	 * this is a post-processing step performed on the client not the server side. A
-	 * threshold value of 0.0 means any similarity is accepted or disable the similarity
-	 * threshold filtering. A threshold value of 1.0 means an exact match is required.
-	 * @param threshold The lower bound of the similarity score.
-	 * @return this builder.
+	 * @deprecated use {@link Builder#similarityThreshold(double)} instead.
 	 */
+	@Deprecated(forRemoval = true, since = "1.0.0-M5")
 	public SearchRequest withSimilarityThreshold(double threshold) {
 		Assert.isTrue(threshold >= 0 && threshold <= 1, "Similarity threshold must be in [0,1] range.");
 		this.similarityThreshold = threshold;
@@ -128,106 +289,26 @@ public final class SearchRequest {
 	}
 
 	/**
-	 * Sets disables the similarity threshold by setting it to 0.0 - all results are
-	 * accepted.
-	 * @return this builder.
+	 * @deprecated use {@link Builder#similarityThresholdAll()} instead.
 	 */
+	@Deprecated(forRemoval = true, since = "1.0.0-M5")
 	public SearchRequest withSimilarityThresholdAll() {
 		return withSimilarityThreshold(SIMILARITY_THRESHOLD_ACCEPT_ALL);
 	}
 
 	/**
-	 * Retrieves documents by query embedding similarity and matching the filters. Value
-	 * of 'null' means that no metadata filters will be applied to the search.
-	 *
-	 * For example if the {@link Document#getMetadata()} schema is:
-	 *
-	 * <pre>{@code
-	 * &#123;
-	 * "country": <Text>,
-	 * "city": <Text>,
-	 * "year": <Number>,
-	 * "price": <Decimal>,
-	 * "isActive": <Boolean>
-	 * &#125;
-	 * }</pre>
-	 *
-	 * you can constrain the search result to only UK countries with isActive=true and
-	 * year equal or greater 2020. You can build this such metadata filter
-	 * programmatically like this:
-	 *
-	 * <pre>{@code
-	 * var exp = new Filter.Expression(AND,
-	 * 		new Expression(EQ, new Key("country"), new Value("UK")),
-	 * 		new Expression(AND,
-	 * 				new Expression(GTE, new Key("year"), new Value(2020)),
-	 * 				new Expression(EQ, new Key("isActive"), new Value(true))));
-	 * }</pre>
-	 *
-	 * The {@link Filter.Expression} is portable across all vector stores.<br/>
-	 *
-	 *
-	 * The {@link FilterExpressionBuilder} is a DSL creating expressions programmatically:
-	 *
-	 * <pre>{@code
-	 * var b = new FilterExpressionBuilder();
-	 * var exp = b.and(
-	 * 		b.eq("country", "UK"),
-	 * 		b.and(
-	 * 			b.gte("year", 2020),
-	 * 			b.eq("isActive", true)));
-	 * }</pre>
-	 *
-	 * The {@link FilterExpressionTextParser} converts textual, SQL like filter expression
-	 * language into {@link Filter.Expression}:
-	 *
-	 * <pre>{@code
-	 * var parser = new FilterExpressionTextParser();
-	 * var exp = parser.parse("country == 'UK' && isActive == true && year >=2020");
-	 * }</pre>
-	 * @param expression {@link Filter.Expression} instance used to define the metadata
-	 * filter criteria. The 'null' value stands for no expression filters.
-	 * @return this builder.
+	 * @deprecated use {@link Builder#filterExpression(Filter.Expression)} instead.
 	 */
+	@Deprecated(forRemoval = true, since = "1.0.0-M5")
 	public SearchRequest withFilterExpression(@Nullable Filter.Expression expression) {
 		this.filterExpression = expression;
 		return this;
 	}
 
 	/**
-	 * Document metadata filter expression. For example if your
-	 * {@link Document#getMetadata()} has a schema like:
-	 *
-	 * <pre>{@code
-	 * &#123;
-	 * "country": <Text>,
-	 * "city": <Text>,
-	 * "year": <Number>,
-	 * "price": <Decimal>,
-	 * "isActive": <Boolean>
-	 * &#125;
-	 * }</pre>
-	 *
-	 * then you can constrain the search result with metadata filter expressions like:
-	 *
-	 * <pre>{@code
-	 * country == 'UK' && year >= 2020 && isActive == true
-	 * Or
-	 * country == 'BG' && (city NOT IN ['Sofia', 'Plovdiv'] || price < 134.34)
-	 * }</pre>
-	 *
-	 * This ensures that the response contains only embeddings that match the specified
-	 * filer criteria. <br/>
-	 *
-	 * The declarative, SQL like, filter syntax is portable across all vector stores
-	 * supporting the filter search feature.<br/>
-	 *
-	 * The {@link FilterExpressionTextParser} is used to convert the text filter
-	 * expression into {@link Filter.Expression}.
-	 * @param textExpression declarative, portable, SQL like, metadata filter syntax. The
-	 * 'null' value stands for no expression filters.
-	 * @return this.builder
+	 * @deprecated use {@link Builder#filterExpression(String)} instead.
 	 */
+	@Deprecated(forRemoval = true, since = "1.0.0-M5")
 	public SearchRequest withFilterExpression(@Nullable String textExpression) {
 		this.filterExpression = (textExpression != null) ? new FilterExpressionTextParser().parse(textExpression)
 				: null;

spring-ai-core/src/main/java/org/springframework/ai/vectorstore/VectorStore.java

@@ -80,7 +80,7 @@ public interface VectorStore extends DocumentWriter {
 	 */
 	@Nullable
 	default List<Document> similaritySearch(String query) {
-		return this.similaritySearch(SearchRequest.query(query));
+		return this.similaritySearch(SearchRequest.builder().query(query).build());
 	}
 
 	/**

spring-ai-core/src/test/java/org/springframework/ai/chat/client/advisor/QuestionAnswerAdvisorTests.java

@@ -112,7 +112,7 @@ public class QuestionAnswerAdvisorTests {
 			.willReturn(List.of(new Document("doc1"), new Document("doc2")));
 
 		var qaAdvisor = new QuestionAnswerAdvisor(this.vectorStore,
-				SearchRequest.defaults().withSimilarityThreshold(0.99d).withTopK(6));
+				SearchRequest.builder().similarityThreshold(0.99d).topK(6).build());
 
 		var chatClient = ChatClient.builder(this.chatModel)
 			.defaultSystem("Default system text.")
@@ -186,7 +186,7 @@ public class QuestionAnswerAdvisorTests {
 				.willReturn(List.of(new Document("doc1"), new Document("doc2")));
 
 		var chatClient = ChatClient.builder(this.chatModel).build();
-		var qaAdvisor = new QuestionAnswerAdvisor(this.vectorStore, SearchRequest.defaults());
+		var qaAdvisor = new QuestionAnswerAdvisor(this.vectorStore, SearchRequest.builder().build());
 
 		var userTextTemplate = "Please answer my question {question}";
 		// @formatter:off
@@ -214,7 +214,7 @@ public class QuestionAnswerAdvisorTests {
 				.willReturn(List.of(new Document("doc1"), new Document("doc2")));
 
 		var chatClient = ChatClient.builder(this.chatModel).build();
-		var qaAdvisor = new QuestionAnswerAdvisor(this.vectorStore, SearchRequest.defaults());
+		var qaAdvisor = new QuestionAnswerAdvisor(this.vectorStore, SearchRequest.builder().build());
 
 		var userTextTemplate = "Please answer my question {question}";
 		var userPromptTemplate = new PromptTemplate(userTextTemplate, Map.of("question", "XYZ"));

spring-ai-core/src/test/java/org/springframework/ai/vectorstore/SimpleVectorStoreTests.java

@@ -125,7 +125,7 @@ class SimpleVectorStoreTests {
 
 		this.vectorStore.add(List.of(doc));
 
-		SearchRequest request = SearchRequest.query("query").withSimilarityThreshold(0.99f).withTopK(5);
+		SearchRequest request = SearchRequest.builder().query("query").similarityThreshold(0.99f).topK(5).build();
 
 		List<Document> results = this.vectorStore.similaritySearch(request);
 		assertThat(results).isEmpty();
@@ -191,7 +191,7 @@ class SimpleVectorStoreTests {
 			thread.join();
 		}
 
-		SearchRequest request = SearchRequest.query("test").withTopK(numThreads);
+		SearchRequest request = SearchRequest.builder().query("test").topK(numThreads).build();
 
 		List<Document> results = this.vectorStore.similaritySearch(request);
 
@@ -213,14 +213,15 @@ class SimpleVectorStoreTests {
 
 	@Test
 	void shouldRejectInvalidSimilarityThreshold() {
-		assertThatThrownBy(() -> SearchRequest.query("test").withSimilarityThreshold(2.0f))
+		assertThatThrownBy(() -> SearchRequest.builder().query("test").similarityThreshold(2.0f).build())
 			.isInstanceOf(IllegalArgumentException.class)
 			.hasMessage("Similarity threshold must be in [0,1] range.");
 	}
 
 	@Test
 	void shouldRejectNegativeTopK() {
-		assertThatThrownBy(() -> SearchRequest.query("test").withTopK(-1)).isInstanceOf(IllegalArgumentException.class)
+		assertThatThrownBy(() -> SearchRequest.builder().query("test").topK(-1).build())
+			.isInstanceOf(IllegalArgumentException.class)
 			.hasMessage("TopK should be positive.");
 	}
 

spring-ai-core/src/test/java/org/springframework/ai/vectorstore/filter/SearchRequestTests.java

@@ -26,31 +26,34 @@ import static org.assertj.core.api.Assertions.assertThatThrownBy;
 
 /**
  * @author Christian Tzolov
+ * @author Ilayaperumal Gopinathan
  */
 public class SearchRequestTests {
 
 	@Test
 	public void createDefaults() {
-		var emptyRequest = SearchRequest.defaults();
+		var emptyRequest = SearchRequest.builder().build();
 		assertThat(emptyRequest.getQuery()).isEqualTo("");
 		checkDefaults(emptyRequest);
 	}
 
 	@Test
 	public void createQuery() {
-		var emptyRequest = SearchRequest.query("New Query");
+		var emptyRequest = SearchRequest.builder().query("New Query").build();
 		assertThat(emptyRequest.getQuery()).isEqualTo("New Query");
 		checkDefaults(emptyRequest);
 	}
 
 	@Test
 	public void createFrom() {
-		var originalRequest = SearchRequest.query("New Query")
-			.withTopK(696)
-			.withSimilarityThreshold(0.678)
-			.withFilterExpression("country == 'NL'");
+		var originalRequest = SearchRequest.builder()
+			.query("New Query")
+			.topK(696)
+			.similarityThreshold(0.678)
+			.filterExpression("country == 'NL'")
+			.build();
 
-		var newRequest = SearchRequest.from(originalRequest);
+		var newRequest = SearchRequest.from(originalRequest).build();
 
 		assertThat(newRequest).isNotSameAs(originalRequest);
 		assertThat(newRequest.getQuery()).isEqualTo(originalRequest.getQuery());
@@ -60,71 +63,76 @@ public class SearchRequestTests {
 	}
 
 	@Test
-	public void withQuery() {
-		var emptyRequest = SearchRequest.defaults();
+	public void queryString() {
+		var emptyRequest = SearchRequest.builder().build();
 		assertThat(emptyRequest.getQuery()).isEqualTo("");
 
-		emptyRequest.withQuery("New Query");
-		assertThat(emptyRequest.getQuery()).isEqualTo("New Query");
+		var emptyRequest1 = SearchRequest.from(emptyRequest).query("New Query").build();
+		assertThat(emptyRequest1.getQuery()).isEqualTo("New Query");
 	}
 
 	@Test
-	public void withSimilarityThreshold() {
-		var request = SearchRequest.query("Test").withSimilarityThreshold(0.678);
+	public void similarityThreshold() {
+		var request = SearchRequest.builder().query("Test").similarityThreshold(0.678).build();
 		assertThat(request.getSimilarityThreshold()).isEqualTo(0.678);
 
-		request.withSimilarityThreshold(0.9);
-		assertThat(request.getSimilarityThreshold()).isEqualTo(0.9);
+		var request1 = SearchRequest.from(request).similarityThreshold(0.9).build();
+		assertThat(request1.getSimilarityThreshold()).isEqualTo(0.9);
 
-		assertThatThrownBy(() -> request.withSimilarityThreshold(-1)).isInstanceOf(IllegalArgumentException.class)
+		assertThatThrownBy(() -> SearchRequest.from(request).similarityThreshold(-1))
+			.isInstanceOf(IllegalArgumentException.class)
 			.hasMessageContaining("Similarity threshold must be in [0,1] range.");
 
-		assertThatThrownBy(() -> request.withSimilarityThreshold(1.1)).isInstanceOf(IllegalArgumentException.class)
+		assertThatThrownBy(() -> SearchRequest.from(request).similarityThreshold(1.1))
+			.isInstanceOf(IllegalArgumentException.class)
 			.hasMessageContaining("Similarity threshold must be in [0,1] range.");
 
 	}
 
 	@Test
-	public void withTopK() {
-		var request = SearchRequest.query("Test").withTopK(66);
+	public void topK() {
+		var request = SearchRequest.builder().query("Test").topK(66).build();
 		assertThat(request.getTopK()).isEqualTo(66);
 
-		request.withTopK(89);
-		assertThat(request.getTopK()).isEqualTo(89);
+		var request1 = SearchRequest.from(request).topK(89).build();
+		assertThat(request1.getTopK()).isEqualTo(89);
 
-		assertThatThrownBy(() -> request.withTopK(-1)).isInstanceOf(IllegalArgumentException.class)
+		assertThatThrownBy(() -> SearchRequest.from(request).topK(-1)).isInstanceOf(IllegalArgumentException.class)
 			.hasMessageContaining("TopK should be positive.");
 
 	}
 
 	@Test
-	public void withFilterExpression() {
+	public void filterExpression() {
 
-		var request = SearchRequest.query("Test").withFilterExpression("country == 'BG' && year >= 2022");
+		var request = SearchRequest.builder().query("Test").filterExpression("country == 'BG' && year >= 2022").build();
 		assertThat(request.getFilterExpression()).isEqualTo(new Filter.Expression(Filter.ExpressionType.AND,
 				new Filter.Expression(Filter.ExpressionType.EQ, new Filter.Key("country"), new Filter.Value("BG")),
 				new Filter.Expression(Filter.ExpressionType.GTE, new Filter.Key("year"), new Filter.Value(2022))));
 		assertThat(request.hasFilterExpression()).isTrue();
 
-		request.withFilterExpression("active == true");
-		assertThat(request.getFilterExpression()).isEqualTo(
+		var request1 = SearchRequest.from(request).filterExpression("active == true").build();
+		assertThat(request1.getFilterExpression()).isEqualTo(
 				new Filter.Expression(Filter.ExpressionType.EQ, new Filter.Key("active"), new Filter.Value(true)));
-		assertThat(request.hasFilterExpression()).isTrue();
+		assertThat(request1.hasFilterExpression()).isTrue();
 
-		request.withFilterExpression(new FilterExpressionBuilder().eq("country", "NL").build());
-		assertThat(request.getFilterExpression()).isEqualTo(
+		var request2 = SearchRequest.from(request)
+			.filterExpression(new FilterExpressionBuilder().eq("country", "NL").build())
+			.build();
+
+		assertThat(request2.getFilterExpression()).isEqualTo(
 				new Filter.Expression(Filter.ExpressionType.EQ, new Filter.Key("country"), new Filter.Value("NL")));
-		assertThat(request.hasFilterExpression()).isTrue();
+		assertThat(request2.hasFilterExpression()).isTrue();
 
-		request.withFilterExpression((String) null);
-		assertThat(request.getFilterExpression()).isNull();
-		assertThat(request.hasFilterExpression()).isFalse();
+		var request3 = SearchRequest.from(request).filterExpression((String) null).build();
+		assertThat(request3.getFilterExpression()).isNull();
+		assertThat(request3.hasFilterExpression()).isFalse();
 
-		request.withFilterExpression((Filter.Expression) null);
-		assertThat(request.getFilterExpression()).isNull();
-		assertThat(request.hasFilterExpression()).isFalse();
+		var request4 = SearchRequest.from(request).filterExpression((Filter.Expression) null).build();
+		assertThat(request4.getFilterExpression()).isNull();
+		assertThat(request4.hasFilterExpression()).isFalse();
 
-		assertThatThrownBy(() -> request.withFilterExpression("FooBar"))
+		assertThatThrownBy(() -> SearchRequest.from(request).filterExpression("FooBar"))
 			.isInstanceOf(FilterExpressionParseException.class)
 			.hasMessageContaining("Error: no viable alternative at input 'FooBar'");
 

spring-ai-core/src/test/java/org/springframework/ai/vectorstore/observation/DefaultVectorStoreObservationConventionTests.java

@@ -83,7 +83,10 @@ class DefaultVectorStoreObservationConventionTests {
 			.fieldName("FIELD_NAME")
 			.namespace("NAMESPACE")
 			.similarityMetric("SIMILARITY_METRIC")
-			.queryRequest(SearchRequest.query("VDB QUERY").withFilterExpression("country == 'UK' && year >= 2020"))
+			.queryRequest(SearchRequest.builder()
+				.query("VDB QUERY")
+				.filterExpression("country == 'UK' && year >= 2020")
+				.build())
 			.build();
 
 		List<Document> queryResponseDocs = List.of(new Document("doc1"), new Document("doc2"));

spring-ai-docs/src/main/antora/modules/ROOT/pages/api/vectordbs.adoc

@@ -53,11 +53,11 @@ public class SearchRequest {
 
 	private SearchRequest(String query) { this.query = query; }
 
-	public SearchRequest withTopK(int topK) {...}
-	public SearchRequest withSimilarityThreshold(double threshold) {...}
-	public SearchRequest withSimilarityThresholdAll() {...}
-	public SearchRequest withFilterExpression(Filter.Expression expression) {...}
-	public SearchRequest withFilterExpression(String textExpression) {...}
+	public SearchRequest topK(int topK) {...}
+	public SearchRequest similarityThreshold(double threshold) {...}
+	public SearchRequest similarityThresholdAll() {...}
+	public SearchRequest filterExpression(Filter.Expression expression) {...}
+	public SearchRequest filterExpression(String textExpression) {...}
 
 	public String getQuery() {...}
 	public int getTopK() {...}

spring-ai-docs/src/main/antora/modules/ROOT/pages/api/vectordbs/apache-cassandra.adoc

@@ -142,7 +142,7 @@ And retrieve documents similar to a query:
 [source,java]
 ----
 List<Document> results = vectorStore.similaritySearch(
-    SearchRequest.query("Spring").withTopK(5));
+    SearchRequest.query("Spring").topK(5));
 ----
 
 You can also limit results based on a similarity threshold:
@@ -151,8 +151,8 @@ You can also limit results based on a similarity threshold:
 ----
 List<Document> results = vectorStore.similaritySearch(
     SearchRequest.query("Spring")
-        .withTopK(5)
-        .withSimilarityThreshold(0.5d));
+        .topK(5)
+        .similarityThreshold(0.5d));
 ----
 
 === Advanced Configuration
@@ -193,8 +193,8 @@ For example, you can use either the text expression language:
 ----
 vectorStore.similaritySearch(
     SearchRequest.query("The World")
-        .withTopK(5)
-        .withFilterExpression("country in ['UK', 'NL'] && year >= 2020"));
+        .topK(5)
+        .filterExpression("country in ['UK', 'NL'] && year >= 2020"));
 ----
 
 or programmatically using the expression DSL:
@@ -209,8 +209,8 @@ Filter.Expression f = new FilterExpressionBuilder()
 
 vectorStore.similaritySearch(
     SearchRequest.query("The World")
-        .withTopK(5)
-        .withFilterExpression(f));
+        .topK(5)
+        .filterExpression(f));
 ----
 
 The portable filter expressions get automatically converted into link:https://cassandra.apache.org/doc/latest/cassandra/developing/cql/index.html[CQL queries].

spring-ai-docs/src/main/antora/modules/ROOT/pages/api/vectordbs/azure-cosmos-db.adoc

@@ -69,7 +69,7 @@ public class DemoApplication implements CommandLineRunner {
         Document document1 = new Document(UUID.randomUUID().toString(), "Sample content1", Map.of("key1", "value1"));
         Document document2 = new Document(UUID.randomUUID().toString(), "Sample content2", Map.of("key2", "value2"));
 		this.vectorStore.add(List.of(document1, document2));
-        List<Document> results = this.vectorStore.similaritySearch(SearchRequest.query("Sample content").withTopK(1));
+        List<Document> results = this.vectorStore.similaritySearch(SearchRequest.query("Sample content").topK(1));
 
         log.info("Search results: {}", results);
 
@@ -140,8 +140,8 @@ vectorStore.add(List.of(document1, document2));
 
 FilterExpressionBuilder builder = new FilterExpressionBuilder();
 List<Document> results = vectorStore.similaritySearch(SearchRequest.query("The World")
-    .withTopK(10)
-    .withFilterExpression((this.builder.in("country", "UK", "NL")).build()));
+    .topK(10)
+    .filterExpression((this.builder.in("country", "UK", "NL")).build()));
 ----
 
 == Setting up Azure Cosmos DB Vector Store without Auto Configuration
@@ -192,7 +192,7 @@ public class DemoApplication implements CommandLineRunner {
         Document document2 = new Document(UUID.randomUUID().toString(), "Sample content2", Map.of("key2", "value2"));
 		this.vectorStore.add(List.of(document1, document2));
 
-        List<Document> results = this.vectorStore.similaritySearch(SearchRequest.query("Sample content").withTopK(1));
+        List<Document> results = this.vectorStore.similaritySearch(SearchRequest.query("Sample content").topK(1));
         log.info("Search results: {}", results);
     }
 

spring-ai-docs/src/main/antora/modules/ROOT/pages/api/vectordbs/azure.adoc

@@ -171,7 +171,7 @@ And finally, retrieve documents similar to a query:
 List<Document> results = vectorStore.similaritySearch(
     SearchRequest
       .query("Spring")
-      .withTopK(5));
+      .topK(5));
 ----
 
 If all goes well, you should retrieve the document containing the text "Spring AI rocks!!".
@@ -187,9 +187,9 @@ For example, you can use either the text expression language:
 vectorStore.similaritySearch(
    SearchRequest
       .query("The World")
-      .withTopK(TOP_K)
-      .withSimilarityThreshold(SIMILARITY_THRESHOLD)
-      .withFilterExpression("country in ['UK', 'NL'] && year >= 2020"));
+      .topK(TOP_K)
+      .similarityThreshold(SIMILARITY_THRESHOLD)
+      .filterExpression("country in ['UK', 'NL'] && year >= 2020"));
 ----
 
 or programmatically using the expression DSL:
@@ -201,9 +201,9 @@ FilterExpressionBuilder b = new FilterExpressionBuilder();
 vectorStore.similaritySearch(
     SearchRequest
       .query("The World")
-      .withTopK(TOP_K)
-      .withSimilarityThreshold(SIMILARITY_THRESHOLD)
-      .withFilterExpression(b.and(
+      .topK(TOP_K)
+      .similarityThreshold(SIMILARITY_THRESHOLD)
+      .filterExpression(b.and(
          b.in("country", "UK", "NL"),
          b.gte("year", 2020)).build()));
 ----

spring-ai-docs/src/main/antora/modules/ROOT/pages/api/vectordbs/chroma.adoc

@@ -101,7 +101,7 @@ List <Document> documents = List.of(
 vectorStore.add(documents);
 
 // Retrieve documents similar to a query
-List<Document> results = this.vectorStore.similaritySearch(SearchRequest.query("Spring").withTopK(5));
+List<Document> results = this.vectorStore.similaritySearch(SearchRequest.query("Spring").topK(5));
 ----
 
 === Configuration properties
@@ -138,10 +138,10 @@ For example, you can use either the text expression language:
 ----
 vectorStore.similaritySearch(
                     SearchRequest.defaults()
-                            .withQuery("The World")
-                            .withTopK(TOP_K)
-                            .withSimilarityThreshold(SIMILARITY_THRESHOLD)
-                            .withFilterExpression("author in ['john', 'jill'] && article_type == 'blog'"));
+                            .queryString("The World")
+                            .topK(TOP_K)
+                            .similarityThreshold(SIMILARITY_THRESHOLD)
+                            .filterExpression("author in ['john', 'jill'] && article_type == 'blog'"));
 ----
 
 or programmatically using the `Filter.Expression` DSL:
@@ -151,10 +151,10 @@ or programmatically using the `Filter.Expression` DSL:
 FilterExpressionBuilder b = new FilterExpressionBuilder();
 
 vectorStore.similaritySearch(SearchRequest.defaults()
-                    .withQuery("The World")
-                    .withTopK(TOP_K)
-                    .withSimilarityThreshold(SIMILARITY_THRESHOLD)
-                    .withFilterExpression(b.and(
+                    .queryString("The World")
+                    .topK(TOP_K)
+                    .similarityThreshold(SIMILARITY_THRESHOLD)
+                    .filterExpression(b.and(
                             b.in("john", "jill"),
                             b.eq("article_type", "blog")).build()));
 ----

spring-ai-docs/src/main/antora/modules/ROOT/pages/api/vectordbs/elasticsearch.adoc

@@ -98,7 +98,7 @@ List <Document> documents = List.of(
 vectorStore.add(documents);
 
 // Retrieve documents similar to a query
-List<Document> results = this.vectorStore.similaritySearch(SearchRequest.query("Spring").withTopK(5));
+List<Document> results = this.vectorStore.similaritySearch(SearchRequest.query("Spring").topK(5));
 ----
 
 [[elasticsearchvector-properties]]
@@ -172,10 +172,10 @@ For example, you can use either the text expression language:
 [source,java]
 ----
 vectorStore.similaritySearch(SearchRequest.defaults()
-        .withQuery("The World")
-        .withTopK(TOP_K)
-        .withSimilarityThreshold(SIMILARITY_THRESHOLD)
-        .withFilterExpression("author in ['john', 'jill'] && 'article_type' == 'blog'"));
+        .queryString("The World")
+        .topK(TOP_K)
+        .similarityThreshold(SIMILARITY_THRESHOLD)
+        .filterExpression("author in ['john', 'jill'] && 'article_type' == 'blog'"));
 ----
 
 or programmatically using the `Filter.Expression` DSL:
@@ -185,10 +185,10 @@ or programmatically using the `Filter.Expression` DSL:
 FilterExpressionBuilder b = new FilterExpressionBuilder();
 
 vectorStore.similaritySearch(SearchRequest.defaults()
-        .withQuery("The World")
-        .withTopK(TOP_K)
-        .withSimilarityThreshold(SIMILARITY_THRESHOLD)
-        .withFilterExpression(b.and(
+        .queryString("The World")
+        .topK(TOP_K)
+        .similarityThreshold(SIMILARITY_THRESHOLD)
+        .filterExpression(b.and(
                 b.in("author", "john", "jill"),
                 b.eq("article_type", "blog")).build()));
 ----

spring-ai-docs/src/main/antora/modules/ROOT/pages/api/vectordbs/gemfire.adoc

@@ -122,7 +122,7 @@ vectorStore.add(documents);
 [source,java]
 ----
 List<Document> results = vectorStore.similaritySearch(
-   SearchRequest.query("Spring").withTopK(5));
+   SearchRequest.query("Spring").topK(5));
 ----
 
 You should retrieve the document containing the text "Spring AI rocks!!".
@@ -131,7 +131,7 @@ You can also limit the number of results using a similarity threshold:
 [source,java]
 ----
 List<Document> results = vectorStore.similaritySearch(
-   SearchRequest.query("Spring").withTopK(5)
-      .withSimilarityThreshold(0.5d));
+   SearchRequest.query("Spring").topK(5)
+      .similarityThreshold(0.5d));
 ----
 

spring-ai-docs/src/main/antora/modules/ROOT/pages/api/vectordbs/mariadb.adoc

@@ -72,7 +72,7 @@ List<Document> documents = List.of(
 vectorStore.add(documents);
 
 // Retrieve documents similar to a query
-List<Document> results = vectorStore.similaritySearch(SearchRequest.query("Spring").withTopK(5));
+List<Document> results = vectorStore.similaritySearch(SearchRequest.query("Spring").topK(5));
 ----
 
 [[mariadbvector-properties]]
@@ -183,10 +183,10 @@ For example, you can use either the text expression language:
 ----
 vectorStore.similaritySearch(
     SearchRequest.defaults()
-        .withQuery("The World")
-        .withTopK(TOP_K)
-        .withSimilarityThreshold(SIMILARITY_THRESHOLD)
-        .withFilterExpression("author in ['john', 'jill'] && article_type == 'blog'"));
+        .queryString("The World")
+        .topK(TOP_K)
+        .similarityThreshold(SIMILARITY_THRESHOLD)
+        .filterExpression("author in ['john', 'jill'] && article_type == 'blog'"));
 ----
 
 or programmatically using the `Filter.Expression` DSL:
@@ -196,10 +196,10 @@ or programmatically using the `Filter.Expression` DSL:
 FilterExpressionBuilder b = new FilterExpressionBuilder();
 
 vectorStore.similaritySearch(SearchRequest.defaults()
-    .withQuery("The World")
-    .withTopK(TOP_K)
-    .withSimilarityThreshold(SIMILARITY_THRESHOLD)
-    .withFilterExpression(b.and(
+    .queryString("The World")
+    .topK(TOP_K)
+    .similarityThreshold(SIMILARITY_THRESHOLD)
+    .filterExpression(b.and(
         b.in("author", "john", "jill"),
         b.eq("article_type", "blog")).build()));
 ----

spring-ai-docs/src/main/antora/modules/ROOT/pages/api/vectordbs/milvus.adoc

@@ -85,7 +85,7 @@ List <Document> documents = List.of(
 vectorStore.add(documents);
 
 // Retrieve documents similar to a query
-List<Document> results = this.vectorStore.similaritySearch(SearchRequest.query("Spring").withTopK(5));
+List<Document> results = this.vectorStore.similaritySearch(SearchRequest.query("Spring").topK(5));
 ----
 
 === Manual Configuration
@@ -137,10 +137,10 @@ For example, you can use either the text expression language:
 ----
 vectorStore.similaritySearch(
     SearchRequest.defaults()
-    .withQuery("The World")
-    .withTopK(TOP_K)
-    .withSimilarityThreshold(SIMILARITY_THRESHOLD)
-    .withFilterExpression("author in ['john', 'jill'] && article_type == 'blog'"));
+    .queryString("The World")
+    .topK(TOP_K)
+    .similarityThreshold(SIMILARITY_THRESHOLD)
+    .filterExpression("author in ['john', 'jill'] && article_type == 'blog'"));
 ----
 
 or programmatically using the `Filter.Expression` DSL:
@@ -150,10 +150,10 @@ or programmatically using the `Filter.Expression` DSL:
 FilterExpressionBuilder b = new FilterExpressionBuilder();
 
 vectorStore.similaritySearch(SearchRequest.defaults()
-    .withQuery("The World")
-    .withTopK(TOP_K)
-    .withSimilarityThreshold(SIMILARITY_THRESHOLD)
-    .withFilterExpression(b.and(
+    .queryString("The World")
+    .topK(TOP_K)
+    .similarityThreshold(SIMILARITY_THRESHOLD)
+    .filterExpression(b.and(
         b.in("author","john", "jill"),
         b.eq("article_type", "blog")).build()));
 ----

spring-ai-docs/src/main/antora/modules/ROOT/pages/api/vectordbs/mongodb.adoc

@@ -70,7 +70,7 @@ List<Document> documents = List.of(
 vectorStore.add(documents);
 
 // Retrieve documents similar to a query
-List<Document> results = vectorStore.similaritySearch(SearchRequest.query("Spring").withTopK(5));
+List<Document> results = vectorStore.similaritySearch(SearchRequest.query("Spring").topK(5));
 ----
 
 [[mongodbvector-properties]]
@@ -175,10 +175,10 @@ For example, you can use either the text expression language:
 [source,java]
 ----
 vectorStore.similaritySearch(SearchRequest.defaults()
-        .withQuery("The World")
-        .withTopK(5)
-        .withSimilarityThreshold(0.7)
-        .withFilterExpression("author in ['john', 'jill'] && article_type == 'blog'"));
+        .queryString("The World")
+        .topK(5)
+        .similarityThreshold(0.7)
+        .filterExpression("author in ['john', 'jill'] && article_type == 'blog'"));
 ----
 
 or programmatically using the `Filter.Expression` DSL:
@@ -188,10 +188,10 @@ or programmatically using the `Filter.Expression` DSL:
 FilterExpressionBuilder b = new FilterExpressionBuilder();
 
 vectorStore.similaritySearch(SearchRequest.defaults()
-        .withQuery("The World")
-        .withTopK(5)
-        .withSimilarityThreshold(0.7)
-        .withFilterExpression(b.and(
+        .queryString("The World")
+        .topK(5)
+        .similarityThreshold(0.7)
+        .filterExpression(b.and(
                 b.in("author", "john", "jill"),
                 b.eq("article_type", "blog")).build()));
 ----

spring-ai-docs/src/main/antora/modules/ROOT/pages/api/vectordbs/neo4j.adoc

@@ -71,7 +71,7 @@ List<Document> documents = List.of(
 vectorStore.add(documents);
 
 // Retrieve documents similar to a query
-List<Document> results = vectorStore.similaritySearch(SearchRequest.query("Spring").withTopK(5));
+List<Document> results = vectorStore.similaritySearch(SearchRequest.query("Spring").topK(5));
 ----
 
 [[neo4jvector-properties]]
@@ -203,10 +203,10 @@ For example, you can use either the text expression language:
 ----
 vectorStore.similaritySearch(
     SearchRequest.defaults()
-        .withQuery("The World")
-        .withTopK(TOP_K)
-        .withSimilarityThreshold(SIMILARITY_THRESHOLD)
-        .withFilterExpression("author in ['john', 'jill'] && 'article_type' == 'blog'"));
+        .queryString("The World")
+        .topK(TOP_K)
+        .similarityThreshold(SIMILARITY_THRESHOLD)
+        .filterExpression("author in ['john', 'jill'] && 'article_type' == 'blog'"));
 ----
 
 or programmatically using the `Filter.Expression` DSL:
@@ -216,10 +216,10 @@ or programmatically using the `Filter.Expression` DSL:
 FilterExpressionBuilder b = new FilterExpressionBuilder();
 
 vectorStore.similaritySearch(SearchRequest.defaults()
-    .withQuery("The World")
-    .withTopK(TOP_K)
-    .withSimilarityThreshold(SIMILARITY_THRESHOLD)
-    .withFilterExpression(b.and(
+    .queryString("The World")
+    .topK(TOP_K)
+    .similarityThreshold(SIMILARITY_THRESHOLD)
+    .filterExpression(b.and(
         b.in("author", "john", "jill"),
         b.eq("article_type", "blog")).build()));
 ----

spring-ai-docs/src/main/antora/modules/ROOT/pages/api/vectordbs/opensearch.adoc

@@ -77,7 +77,7 @@ List<Document> documents = List.of(
 vectorStore.add(documents);
 
 // Retrieve documents similar to a query
-List<Document> results = vectorStore.similaritySearch(SearchRequest.query("Spring").withTopK(5));
+List<Document> results = vectorStore.similaritySearch(SearchRequest.query("Spring").topK(5));
 ----
 
 === Configuration Properties
@@ -204,10 +204,10 @@ For example, you can use either the text expression language:
 ----
 vectorStore.similaritySearch(
     SearchRequest.defaults()
-        .withQuery("The World")
-        .withTopK(TOP_K)
-        .withSimilarityThreshold(SIMILARITY_THRESHOLD)
-        .withFilterExpression("author in ['john', 'jill'] && 'article_type' == 'blog'"));
+        .queryString("The World")
+        .topK(TOP_K)
+        .similarityThreshold(SIMILARITY_THRESHOLD)
+        .filterExpression("author in ['john', 'jill'] && 'article_type' == 'blog'"));
 ----
 
 or programmatically using the `Filter.Expression` DSL:
@@ -217,10 +217,10 @@ or programmatically using the `Filter.Expression` DSL:
 FilterExpressionBuilder b = new FilterExpressionBuilder();
 
 vectorStore.similaritySearch(SearchRequest.defaults()
-    .withQuery("The World")
-    .withTopK(TOP_K)
-    .withSimilarityThreshold(SIMILARITY_THRESHOLD)
-    .withFilterExpression(b.and(
+    .queryString("The World")
+    .topK(TOP_K)
+    .similarityThreshold(SIMILARITY_THRESHOLD)
+    .filterExpression(b.and(
         b.in("author", "john", "jill"),
         b.eq("article_type", "blog")).build()));
 ----

spring-ai-docs/src/main/antora/modules/ROOT/pages/api/vectordbs/oracle.adoc

@@ -91,7 +91,7 @@ List<Document> documents = List.of(
 vectorStore.add(documents);
 
 // Retrieve documents similar to a query
-List<Document> results = this.vectorStore.similaritySearch(SearchRequest.query("Spring").withTopK(5));
+List<Document> results = this.vectorStore.similaritySearch(SearchRequest.query("Spring").topK(5));
 ----
 
 [[oracle-properties]]
@@ -129,10 +129,10 @@ For example, you can use either the text expression language:
 ----
 vectorStore.similaritySearch(
     SearchRequest.defaults()
-    .withQuery("The World")
-    .withTopK(TOP_K)
-    .withSimilarityThreshold(SIMILARITY_THRESHOLD)
-    .withFilterExpression("author in ['john', 'jill'] && article_type == 'blog'"));
+    .query("The World")
+    .topK(TOP_K)
+    .similarityThreshold(SIMILARITY_THRESHOLD)
+    .filterExpression("author in ['john', 'jill'] && article_type == 'blog'"));
 ----
 
 or programmatically using the `Filter.Expression` DSL:
@@ -142,10 +142,10 @@ or programmatically using the `Filter.Expression` DSL:
 FilterExpressionBuilder b = new FilterExpressionBuilder();
 
 vectorStore.similaritySearch(SearchRequest.defaults()
-    .withQuery("The World")
-    .withTopK(TOP_K)
-    .withSimilarityThreshold(SIMILARITY_THRESHOLD)
-    .withFilterExpression(b.and(
+    .queryString("The World")
+    .topK(TOP_K)
+    .similarityThreshold(SIMILARITY_THRESHOLD)
+    .filterExpression(b.and(
         b.in("author","john", "jill"),
         b.eq("article_type", "blog")).build()));
 ----

spring-ai-docs/src/main/antora/modules/ROOT/pages/api/vectordbs/pgvector.adoc

@@ -127,7 +127,7 @@ List<Document> documents = List.of(
 vectorStore.add(documents);
 
 // Retrieve documents similar to a query
-List<Document> results = this.vectorStore.similaritySearch(SearchRequest.query("Spring").withTopK(5));
+List<Document> results = this.vectorStore.similaritySearch(SearchRequest.query("Spring").topK(5));
 ----
 
 [[pgvector-properties]]
@@ -165,10 +165,10 @@ For example, you can use either the text expression language:
 ----
 vectorStore.similaritySearch(
     SearchRequest.defaults()
-    .withQuery("The World")
-    .withTopK(TOP_K)
-    .withSimilarityThreshold(SIMILARITY_THRESHOLD)
-    .withFilterExpression("author in ['john', 'jill'] && article_type == 'blog'"));
+    .queryString("The World")
+    .topK(TOP_K)
+    .similarityThreshold(SIMILARITY_THRESHOLD)
+    .filterExpression("author in ['john', 'jill'] && article_type == 'blog'"));
 ----
 
 or programmatically using the `Filter.Expression` DSL:
@@ -178,10 +178,10 @@ or programmatically using the `Filter.Expression` DSL:
 FilterExpressionBuilder b = new FilterExpressionBuilder();
 
 vectorStore.similaritySearch(SearchRequest.defaults()
-    .withQuery("The World")
-    .withTopK(TOP_K)
-    .withSimilarityThreshold(SIMILARITY_THRESHOLD)
-    .withFilterExpression(b.and(
+    .queryString("The World")
+    .topK(TOP_K)
+    .similarityThreshold(SIMILARITY_THRESHOLD)
+    .filterExpression(b.and(
         b.in("author","john", "jill"),
         b.eq("article_type", "blog")).build()));
 ----

spring-ai-docs/src/main/antora/modules/ROOT/pages/api/vectordbs/pinecone.adoc

@@ -96,7 +96,7 @@ List <Document> documents = List.of(
 vectorStore.add(documents);
 
 // Retrieve documents similar to a query
-List<Document> results = this.vectorStore.similaritySearch(SearchRequest.query("Spring").withTopK(5));
+List<Document> results = this.vectorStore.similaritySearch(SearchRequest.query("Spring").topK(5));
 ----
 
 === Configuration properties
@@ -128,10 +128,10 @@ For example, you can use either the text expression language:
 ----
 vectorStore.similaritySearch(
     SearchRequest.defaults()
-    .withQuery("The World")
-    .withTopK(TOP_K)
-    .withSimilarityThreshold(SIMILARITY_THRESHOLD)
-    .withFilterExpression("author in ['john', 'jill'] && article_type == 'blog'"));
+    .queryString("The World")
+    .topK(TOP_K)
+    .similarityThreshold(SIMILARITY_THRESHOLD)
+    .filterExpression("author in ['john', 'jill'] && article_type == 'blog'"));
 ----
 
 or programmatically using the `Filter.Expression` DSL:
@@ -141,10 +141,10 @@ or programmatically using the `Filter.Expression` DSL:
 FilterExpressionBuilder b = new FilterExpressionBuilder();
 
 vectorStore.similaritySearch(SearchRequest.defaults()
-    .withQuery("The World")
-    .withTopK(TOP_K)
-    .withSimilarityThreshold(SIMILARITY_THRESHOLD)
-    .withFilterExpression(b.and(
+    .queryString("The World")
+    .topK(TOP_K)
+    .similarityThreshold(SIMILARITY_THRESHOLD)
+    .filterExpression(b.and(
         b.in("author","john", "jill"),
         b.eq("article_type", "blog")).build()));
 ----
@@ -233,7 +233,7 @@ And finally, retrieve documents similar to a query:
 
 [source,java]
 ----
-List<Document> results = vectorStore.similaritySearch(SearchRequest.query("Spring").withTopK(5));
+List<Document> results = vectorStore.similaritySearch(SearchRequest.query("Spring").topK(5));
 ----
 
 If all goes well, you should retrieve the document containing the text "Spring AI rocks!!".

spring-ai-docs/src/main/antora/modules/ROOT/pages/api/vectordbs/qdrant.adoc

@@ -63,7 +63,7 @@ List<Document> documents = List.of(
 vectorStore.add(documents);
 
 // Retrieve documents similar to a query
-List<Document> results = vectorStore.similaritySearch(SearchRequest.query("Spring").withTopK(5));
+List<Document> results = vectorStore.similaritySearch(SearchRequest.query("Spring").topK(5));
 ----
 
 [[qdrant-vectorstore-properties]]
@@ -173,10 +173,10 @@ For example, you can use either the text expression language:
 ----
 vectorStore.similaritySearch(
     SearchRequest.defaults()
-        .withQuery("The World")
-        .withTopK(TOP_K)
-        .withSimilarityThreshold(SIMILARITY_THRESHOLD)
-        .withFilterExpression("author in ['john', 'jill'] && article_type == 'blog'"));
+        .queryString("The World")
+        .topK(TOP_K)
+        .similarityThreshold(SIMILARITY_THRESHOLD)
+        .filterExpression("author in ['john', 'jill'] && article_type == 'blog'"));
 ----
 
 or programmatically using the `Filter.Expression` DSL:
@@ -186,10 +186,10 @@ or programmatically using the `Filter.Expression` DSL:
 FilterExpressionBuilder b = new FilterExpressionBuilder();
 
 vectorStore.similaritySearch(SearchRequest.defaults()
-    .withQuery("The World")
-    .withTopK(TOP_K)
-    .withSimilarityThreshold(SIMILARITY_THRESHOLD)
-    .withFilterExpression(b.and(
+    .queryString("The World")
+    .topK(TOP_K)
+    .similarityThreshold(SIMILARITY_THRESHOLD)
+    .filterExpression(b.and(
         b.in("author", "john", "jill"),
         b.eq("article_type", "blog")).build()));
 ----

spring-ai-docs/src/main/antora/modules/ROOT/pages/api/vectordbs/redis.adoc

@@ -70,7 +70,7 @@ List <Document> documents = List.of(
 vectorStore.add(documents);
 
 // Retrieve documents similar to a query
-List<Document> results = this.vectorStore.similaritySearch(SearchRequest.query("Spring").withTopK(5));
+List<Document> results = this.vectorStore.similaritySearch(SearchRequest.query("Spring").topK(5));
 ----
 
 [[redisvector-properties]]
@@ -115,10 +115,10 @@ For example, you can use either the text expression language:
 [source,java]
 ----
 vectorStore.similaritySearch(SearchRequest.defaults()
-        .withQuery("The World")
-        .withTopK(TOP_K)
-        .withSimilarityThreshold(SIMILARITY_THRESHOLD)
-        .withFilterExpression("country in ['UK', 'NL'] && year >= 2020"));
+        .queryString("The World")
+        .topK(TOP_K)
+        .similarityThreshold(SIMILARITY_THRESHOLD)
+        .filterExpression("country in ['UK', 'NL'] && year >= 2020"));
 ----
 
 or programmatically using the `Filter.Expression` DSL:
@@ -128,10 +128,10 @@ or programmatically using the `Filter.Expression` DSL:
 FilterExpressionBuilder b = new FilterExpressionBuilder();
 
 vectorStore.similaritySearch(SearchRequest.defaults()
-        .withQuery("The World")
-        .withTopK(TOP_K)
-        .withSimilarityThreshold(SIMILARITY_THRESHOLD)
-        .withFilterExpression(b.and(
+        .queryString("The World")
+        .topK(TOP_K)
+        .similarityThreshold(SIMILARITY_THRESHOLD)
+        .filterExpression(b.and(
                 b.in("country", "UK", "NL"),
                 b.gte("year", 2020)).build()));
 ----

spring-ai-docs/src/main/antora/modules/ROOT/pages/api/vectordbs/typesense.adoc

@@ -60,7 +60,7 @@ List<Document> documents = List.of(
 vectorStore.add(documents);
 
 // Retrieve documents similar to a query
-List<Document> results = vectorStore.similaritySearch(SearchRequest.query("Spring").withTopK(5));
+List<Document> results = vectorStore.similaritySearch(SearchRequest.query("Spring").topK(5));
 ----
 
 === Configuration Properties
@@ -188,10 +188,10 @@ For example you can use either the text expression language:
 ----
 vectorStore.similaritySearch(
     SearchRequest.defaults()
-        .withQuery("The World")
-        .withTopK(TOP_K)
-        .withSimilarityThreshold(SIMILARITY_THRESHOLD)
-        .withFilterExpression("country in ['UK', 'NL'] && year >= 2020"));
+        .queryString("The World")
+        .topK(TOP_K)
+        .similarityThreshold(SIMILARITY_THRESHOLD)
+        .filterExpression("country in ['UK', 'NL'] && year >= 2020"));
 ----
 
 or programmatically using the `Filter.Expression` DSL:
@@ -201,10 +201,10 @@ or programmatically using the `Filter.Expression` DSL:
 FilterExpressionBuilder b = new FilterExpressionBuilder();
 
 vectorStore.similaritySearch(SearchRequest.defaults()
-    .withQuery("The World")
-    .withTopK(TOP_K)
-    .withSimilarityThreshold(SIMILARITY_THRESHOLD)
-    .withFilterExpression(b.and(
+    .queryString("The World")
+    .topK(TOP_K)
+    .similarityThreshold(SIMILARITY_THRESHOLD)
+    .filterExpression(b.and(
         b.in("country", "UK", "NL"),
         b.gte("year", 2020)).build()));
 ----

spring-ai-docs/src/main/antora/modules/ROOT/pages/api/vectordbs/weaviate.adoc

@@ -142,10 +142,10 @@ For example, you can use either the text expression language:
 ----
 vectorStore.similaritySearch(
     SearchRequest.defaults()
-        .withQuery("The World")
-        .withTopK(TOP_K)
-        .withSimilarityThreshold(SIMILARITY_THRESHOLD)
-        .withFilterExpression("country in ['UK', 'NL'] && year >= 2020"));
+        .queryString("The World")
+        .topK(TOP_K)
+        .similarityThreshold(SIMILARITY_THRESHOLD)
+        .filterExpression("country in ['UK', 'NL'] && year >= 2020"));
 ----
 
 or programmatically using the `Filter.Expression` DSL:
@@ -155,10 +155,10 @@ or programmatically using the `Filter.Expression` DSL:
 FilterExpressionBuilder b = new FilterExpressionBuilder();
 
 vectorStore.similaritySearch(SearchRequest.defaults()
-    .withQuery("The World")
-    .withTopK(TOP_K)
-    .withSimilarityThreshold(SIMILARITY_THRESHOLD)
-    .withFilterExpression(b.and(
+    .queryString("The World")
+    .topK(TOP_K)
+    .similarityThreshold(SIMILARITY_THRESHOLD)
+    .filterExpression(b.and(
         b.in("country", "UK", "NL"),
         b.gte("year", 2020)).build()));
 ----

spring-ai-integration-tests/src/test/java/org/springframework/ai/integration/tests/vectorstore/SimpleVectorStoreIT.java

@@ -90,7 +90,7 @@ public class SimpleVectorStoreIT {
 
 		vectorStore.add(List.of(document));
 
-		List<Document> results = vectorStore.similaritySearch(SearchRequest.query("Spring").withTopK(5));
+		List<Document> results = vectorStore.similaritySearch(SearchRequest.builder().query("Spring").topK(5).build());
 
 		assertThat(results).hasSize(1);
 		Document resultDoc = results.get(0);
@@ -107,7 +107,7 @@ public class SimpleVectorStoreIT {
 
 		vectorStore.add(List.of(sameIdDocument));
 
-		results = vectorStore.similaritySearch(SearchRequest.query("FooBar").withTopK(5));
+		results = vectorStore.similaritySearch(SearchRequest.builder().query("FooBar").topK(5).build());
 
 		assertThat(results).hasSize(1);
 		resultDoc = results.get(0);

spring-ai-spring-boot-autoconfigure/src/test/java/org/springframework/ai/autoconfigure/vectorstore/azure/AzureVectorStoreAutoConfigurationIT.java

@@ -109,14 +109,16 @@ public class AzureVectorStoreAutoConfigurationIT {
 				vectorStore.add(this.documents);
 
 				Awaitility.await()
-					.until(() -> vectorStore.similaritySearch(SearchRequest.query("Spring").withTopK(1)), hasSize(1));
+					.until(() -> vectorStore.similaritySearch(SearchRequest.builder().query("Spring").topK(1).build()),
+							hasSize(1));
 
 				org.springframework.ai.autoconfigure.vectorstore.observation.ObservationTestUtil
 					.assertObservationRegistry(observationRegistry, VectorStoreProvider.AZURE,
 							VectorStoreObservationContext.Operation.ADD);
 				observationRegistry.clear();
 
-				List<Document> results = vectorStore.similaritySearch(SearchRequest.query("Spring").withTopK(1));
+				List<Document> results = vectorStore
+					.similaritySearch(SearchRequest.builder().query("Spring").topK(1).build());
 
 				assertThat(results).hasSize(1);
 				Document resultDoc = results.get(0);
@@ -135,7 +137,8 @@ public class AzureVectorStoreAutoConfigurationIT {
 				vectorStore.delete(this.documents.stream().map(doc -> doc.getId()).toList());
 
 				Awaitility.await()
-					.until(() -> vectorStore.similaritySearch(SearchRequest.query("Spring").withTopK(1)), hasSize(0));
+					.until(() -> vectorStore.similaritySearch(SearchRequest.builder().query("Spring").topK(1).build()),
+							hasSize(0));
 
 				org.springframework.ai.autoconfigure.vectorstore.observation.ObservationTestUtil
 					.assertObservationRegistry(observationRegistry, VectorStoreProvider.AZURE,

spring-ai-spring-boot-autoconfigure/src/test/java/org/springframework/ai/autoconfigure/vectorstore/cassandra/CassandraVectorStoreAutoConfigurationIT.java

@@ -86,7 +86,8 @@ class CassandraVectorStoreAutoConfigurationIT {
 						VectorStoreObservationContext.Operation.ADD);
 				observationRegistry.clear();
 
-				List<Document> results = vectorStore.similaritySearch(SearchRequest.query("Spring").withTopK(1));
+				List<Document> results = vectorStore
+					.similaritySearch(SearchRequest.builder().query("Spring").topK(1).build());
 
 				assertThat(results).hasSize(1);
 				Document resultDoc = results.get(0);
@@ -101,7 +102,7 @@ class CassandraVectorStoreAutoConfigurationIT {
 				// Remove all documents from the store
 				vectorStore.delete(this.documents.stream().map(doc -> doc.getId()).toList());
 
-				results = vectorStore.similaritySearch(SearchRequest.query("Spring").withTopK(1));
+				results = vectorStore.similaritySearch(SearchRequest.builder().query("Spring").topK(1).build());
 				assertThat(results).isEmpty();
 
 				assertObservationRegistry(observationRegistry, VectorStoreProvider.CASSANDRA,

spring-ai-spring-boot-autoconfigure/src/test/java/org/springframework/ai/autoconfigure/vectorstore/chroma/ChromaVectorStoreAutoConfigurationIT.java

@@ -83,20 +83,24 @@ public class ChromaVectorStoreAutoConfigurationIT {
 					observationRegistry, VectorStoreProvider.CHROMA, VectorStoreObservationContext.Operation.ADD);
 			observationRegistry.clear();
 
-			var request = SearchRequest.query("The World").withTopK(5);
+			var request = SearchRequest.builder().query("The World").topK(5).build();
 
 			List<Document> results = vectorStore.similaritySearch(request);
 			assertThat(results).hasSize(2);
 			observationRegistry.clear();
 
-			results = vectorStore
-				.similaritySearch(request.withSimilarityThresholdAll().withFilterExpression("country == 'Bulgaria'"));
+			results = vectorStore.similaritySearch(SearchRequest.from(request)
+				.similarityThresholdAll()
+				.filterExpression("country == 'Bulgaria'")
+				.build());
 			assertThat(results).hasSize(1);
 			assertThat(results.get(0).getId()).isEqualTo(bgDocument.getId());
 			observationRegistry.clear();
 
-			results = vectorStore.similaritySearch(
-					request.withSimilarityThresholdAll().withFilterExpression("country == 'Netherlands'"));
+			results = vectorStore.similaritySearch(SearchRequest.from(request)
+				.similarityThresholdAll()
+				.filterExpression("country == 'Netherlands'")
+				.build());
 			assertThat(results).hasSize(1);
 			assertThat(results.get(0).getId()).isEqualTo(nlDocument.getId());
 

spring-ai-spring-boot-autoconfigure/src/test/java/org/springframework/ai/autoconfigure/vectorstore/cosmosdb/CosmosDBVectorStoreAutoConfigurationIT.java

@@ -78,7 +78,8 @@ public class CosmosDBVectorStoreAutoConfigurationIT {
 		this.vectorStore.add(List.of(document1, document2));
 
 		// Perform a similarity search
-		List<Document> results = this.vectorStore.similaritySearch(SearchRequest.query("Sample content").withTopK(1));
+		List<Document> results = this.vectorStore
+			.similaritySearch(SearchRequest.builder().query("Sample content").topK(1).build());
 
 		// Verify the search results
 		assertThat(results).isNotEmpty();
@@ -88,7 +89,8 @@ public class CosmosDBVectorStoreAutoConfigurationIT {
 		this.vectorStore.delete(List.of(document1.getId(), document2.getId()));
 
 		// Perform a similarity search again
-		List<Document> results2 = this.vectorStore.similaritySearch(SearchRequest.query("Sample content").withTopK(1));
+		List<Document> results2 = this.vectorStore
+			.similaritySearch(SearchRequest.builder().query("Sample content").topK(1).build());
 
 		// Verify the search results
 		assertThat(results2).isEmpty();
@@ -129,24 +131,30 @@ public class CosmosDBVectorStoreAutoConfigurationIT {
 
 		this.vectorStore.add(List.of(document1, document2, document3, document4));
 		FilterExpressionBuilder b = new FilterExpressionBuilder();
-		List<Document> results = this.vectorStore.similaritySearch(SearchRequest.query("The World")
-			.withTopK(10)
-			.withFilterExpression((b.in("country", "UK", "NL")).build()));
+		List<Document> results = this.vectorStore.similaritySearch(SearchRequest.builder()
+			.query("The World")
+			.topK(10)
+			.filterExpression((b.in("country", "UK", "NL").build()))
+			.build());
 
 		assertThat(results).hasSize(2);
 		assertThat(results).extracting(Document::getId).containsExactlyInAnyOrder("1", "2");
 
-		List<Document> results2 = this.vectorStore.similaritySearch(SearchRequest.query("The World")
-			.withTopK(10)
-			.withFilterExpression(
-					b.and(b.or(b.gte("year", 2021), b.eq("country", "NL")), b.ne("city", "Amsterdam")).build()));
+		List<Document> results2 = this.vectorStore.similaritySearch(SearchRequest.builder()
+			.query("The World")
+			.topK(10)
+			.filterExpression(
+					b.and(b.or(b.gte("year", 2021), b.eq("country", "NL")), b.ne("city", "Amsterdam")).build())
+			.build());
 
 		assertThat(results2).hasSize(1);
 		assertThat(results2).extracting(Document::getId).containsExactlyInAnyOrder("1");
 
-		List<Document> results3 = this.vectorStore.similaritySearch(SearchRequest.query("The World")
-			.withTopK(10)
-			.withFilterExpression(b.and(b.eq("country", "US"), b.eq("year", 2020)).build()));
+		List<Document> results3 = this.vectorStore.similaritySearch(SearchRequest.builder()
+			.query("The World")
+			.topK(10)
+			.filterExpression(b.and(b.eq("country", "US"), b.eq("year", 2020)).build())
+			.build());
 
 		assertThat(results3).hasSize(1);
 		assertThat(results3).extracting(Document::getId).containsExactlyInAnyOrder("4");
@@ -154,7 +162,8 @@ public class CosmosDBVectorStoreAutoConfigurationIT {
 		this.vectorStore.delete(List.of(document1.getId(), document2.getId(), document3.getId(), document4.getId()));
 
 		// Perform a similarity search again
-		List<Document> results4 = this.vectorStore.similaritySearch(SearchRequest.query("The World").withTopK(1));
+		List<Document> results4 = this.vectorStore
+			.similaritySearch(SearchRequest.builder().query("The World").topK(1).build());
 
 		// Verify the search results
 		assertThat(results4).isEmpty();

spring-ai-spring-boot-autoconfigure/src/test/java/org/springframework/ai/autoconfigure/vectorstore/elasticsearch/ElasticsearchVectorStoreAutoConfigurationIT.java

@@ -88,14 +88,14 @@ class ElasticsearchVectorStoreAutoConfigurationIT {
 			observationRegistry.clear();
 
 			Awaitility.await()
-				.until(() -> vectorStore
-					.similaritySearch(SearchRequest.query("Great Depression").withTopK(1).withSimilarityThreshold(0)),
+				.until(() -> vectorStore.similaritySearch(
+						SearchRequest.builder().query("Great Depression").topK(1).similarityThreshold(0).build()),
 						hasSize(1));
 
 			observationRegistry.clear();
 
-			List<Document> results = vectorStore
-				.similaritySearch(SearchRequest.query("Great Depression").withTopK(1).withSimilarityThreshold(0));
+			List<Document> results = vectorStore.similaritySearch(
+					SearchRequest.builder().query("Great Depression").topK(1).similarityThreshold(0).build());
 
 			assertThat(results).hasSize(1);
 			Document resultDoc = results.get(0);
@@ -117,8 +117,8 @@ class ElasticsearchVectorStoreAutoConfigurationIT {
 			observationRegistry.clear();
 
 			Awaitility.await()
-				.until(() -> vectorStore
-					.similaritySearch(SearchRequest.query("Great Depression").withTopK(1).withSimilarityThreshold(0)),
+				.until(() -> vectorStore.similaritySearch(
+						SearchRequest.builder().query("Great Depression").topK(1).similarityThreshold(0).build()),
 						hasSize(0));
 		});
 	}

spring-ai-spring-boot-autoconfigure/src/test/java/org/springframework/ai/autoconfigure/vectorstore/gemfire/GemFireVectorStoreAutoConfigurationIT.java

@@ -153,10 +153,12 @@ class GemFireVectorStoreAutoConfigurationIT {
 					VectorStoreObservationContext.Operation.ADD);
 
 			Awaitility.await()
-				.until(() -> vectorStore.similaritySearch(SearchRequest.query("Spring").withTopK(1)), hasSize(1));
+				.until(() -> vectorStore.similaritySearch(SearchRequest.builder().query("Spring").topK(1).build()),
+						hasSize(1));
 			observationRegistry.clear();
 
-			List<Document> results = vectorStore.similaritySearch(SearchRequest.query("Spring").withTopK(1));
+			List<Document> results = vectorStore
+				.similaritySearch(SearchRequest.builder().query("Spring").topK(1).build());
 
 			assertObservationRegistry(observationRegistry, VectorStoreProvider.GEMFIRE,
 					VectorStoreObservationContext.Operation.QUERY);
@@ -177,7 +179,8 @@ class GemFireVectorStoreAutoConfigurationIT {
 					VectorStoreObservationContext.Operation.DELETE);
 
 			Awaitility.await()
-				.until(() -> vectorStore.similaritySearch(SearchRequest.query("Spring").withTopK(1)), hasSize(0));
+				.until(() -> vectorStore.similaritySearch(SearchRequest.builder().query("Spring").topK(1).build()),
+						hasSize(0));
 			observationRegistry.clear();
 		});
 	}

spring-ai-spring-boot-autoconfigure/src/test/java/org/springframework/ai/autoconfigure/vectorstore/mariadb/MariaDbStoreAutoConfigurationIT.java

@@ -117,7 +117,7 @@ public class MariaDbStoreAutoConfigurationIT {
 			observationRegistry.clear();
 
 			List<Document> results = vectorStore
-				.similaritySearch(SearchRequest.query("What is Great Depression?").withTopK(1));
+				.similaritySearch(SearchRequest.builder().query("What is Great Depression?").topK(1).build());
 
 			assertThat(results).hasSize(1);
 			Document resultDoc = results.get(0);
@@ -134,7 +134,7 @@ public class MariaDbStoreAutoConfigurationIT {
 			assertObservationRegistry(observationRegistry, VectorStoreProvider.MARIADB,
 					VectorStoreObservationContext.Operation.DELETE);
 
-			results = vectorStore.similaritySearch(SearchRequest.query("Great Depression").withTopK(1));
+			results = vectorStore.similaritySearch(SearchRequest.builder().query("Great Depression").topK(1).build());
 			assertThat(results).hasSize(0);
 			observationRegistry.clear();
 		});

spring-ai-spring-boot-autoconfigure/src/test/java/org/springframework/ai/autoconfigure/vectorstore/milvus/MilvusVectorStoreAutoConfigurationIT.java

@@ -83,7 +83,8 @@ public class MilvusVectorStoreAutoConfigurationIT {
 						VectorStoreObservationContext.Operation.ADD);
 				observationRegistry.clear();
 
-				List<Document> results = vectorStore.similaritySearch(SearchRequest.query("Spring").withTopK(1));
+				List<Document> results = vectorStore
+					.similaritySearch(SearchRequest.builder().query("Spring").topK(1).build());
 
 				assertThat(results).hasSize(1);
 				Document resultDoc = results.get(0);
@@ -100,7 +101,7 @@ public class MilvusVectorStoreAutoConfigurationIT {
 				// Remove all documents from the store
 				vectorStore.delete(this.documents.stream().map(doc -> doc.getId()).toList());
 
-				results = vectorStore.similaritySearch(SearchRequest.query("Spring").withTopK(1));
+				results = vectorStore.similaritySearch(SearchRequest.builder().query("Spring").topK(1).build());
 				assertThat(results).hasSize(0);
 
 				assertObservationRegistry(observationRegistry, VectorStoreProvider.MILVUS,
@@ -134,7 +135,8 @@ public class MilvusVectorStoreAutoConfigurationIT {
 						VectorStoreObservationContext.Operation.ADD);
 				observationRegistry.clear();
 
-				List<Document> results = vectorStore.similaritySearch(SearchRequest.query("Spring").withTopK(1));
+				List<Document> results = vectorStore
+					.similaritySearch(SearchRequest.builder().query("Spring").topK(1).build());
 
 				assertThat(results).hasSize(1);
 				Document resultDoc = results.get(0);
@@ -151,7 +153,7 @@ public class MilvusVectorStoreAutoConfigurationIT {
 				// Remove all documents from the store
 				vectorStore.delete(this.documents.stream().map(doc -> doc.getId()).toList());
 
-				results = vectorStore.similaritySearch(SearchRequest.query("Spring").withTopK(1));
+				results = vectorStore.similaritySearch(SearchRequest.builder().query("Spring").topK(1).build());
 				assertThat(results).hasSize(0);
 
 				assertObservationRegistry(observationRegistry, VectorStoreProvider.MILVUS,

spring-ai-spring-boot-autoconfigure/src/test/java/org/springframework/ai/autoconfigure/vectorstore/mongo/MongoDBAtlasVectorStoreAutoConfigurationIT.java

@@ -101,7 +101,8 @@ class MongoDBAtlasVectorStoreAutoConfigurationIT {
 
 			Thread.sleep(5000); // Await a second for the document to be indexed
 
-			List<Document> results = vectorStore.similaritySearch(SearchRequest.query("Great").withTopK(1));
+			List<Document> results = vectorStore
+				.similaritySearch(SearchRequest.builder().query("Great").topK(1).build());
 
 			assertThat(results).hasSize(1);
 			Document resultDoc = results.get(0);
@@ -121,7 +122,8 @@ class MongoDBAtlasVectorStoreAutoConfigurationIT {
 					VectorStoreObservationContext.Operation.DELETE);
 			observationRegistry.clear();
 
-			List<Document> results2 = vectorStore.similaritySearch(SearchRequest.query("Great").withTopK(1));
+			List<Document> results2 = vectorStore
+				.similaritySearch(SearchRequest.builder().query("Great").topK(1).build());
 			assertThat(results2).isEmpty();
 
 			context.getBean(MongoTemplate.class).dropCollection("test_collection");
@@ -139,14 +141,16 @@ class MongoDBAtlasVectorStoreAutoConfigurationIT {
 				Thread.sleep(5000); // Await a second for the document to be indexed
 
 				List<Document> results = vectorStore
-					.similaritySearch(SearchRequest.query("Testcontainers").withTopK(2));
+					.similaritySearch(SearchRequest.builder().query("Testcontainers").topK(2).build());
 				assertThat(results).hasSize(2);
 				results.forEach(doc -> assertThat(doc.getContent().contains("Testcontainers")).isTrue());
 
 				FilterExpressionBuilder b = new FilterExpressionBuilder();
-				results = vectorStore.similaritySearch(SearchRequest.query("Testcontainers")
-					.withTopK(2)
-					.withFilterExpression(b.eq("foo", "bar").build()));
+				results = vectorStore.similaritySearch(SearchRequest.builder()
+					.query("Testcontainers")
+					.topK(2)
+					.filterExpression(b.eq("foo", "bar").build())
+					.build());
 
 				assertThat(results).hasSize(1);
 				Document resultDoc = results.get(0);

spring-ai-spring-boot-autoconfigure/src/test/java/org/springframework/ai/autoconfigure/vectorstore/neo4j/Neo4jVectorStoreAutoConfigurationIT.java

@@ -89,7 +89,8 @@ public class Neo4jVectorStoreAutoConfigurationIT {
 						VectorStoreObservationContext.Operation.ADD);
 				observationRegistry.clear();
 
-				List<Document> results = vectorStore.similaritySearch(SearchRequest.query("Spring").withTopK(1));
+				List<Document> results = vectorStore
+					.similaritySearch(SearchRequest.builder().query("Spring").topK(1).build());
 
 				assertThat(results).hasSize(1);
 				Document resultDoc = results.get(0);
@@ -108,7 +109,7 @@ public class Neo4jVectorStoreAutoConfigurationIT {
 						VectorStoreObservationContext.Operation.DELETE);
 				observationRegistry.clear();
 
-				results = vectorStore.similaritySearch(SearchRequest.query("Spring").withTopK(1));
+				results = vectorStore.similaritySearch(SearchRequest.builder().query("Spring").topK(1).build());
 				assertThat(results).isEmpty();
 			});
 	}

spring-ai-spring-boot-autoconfigure/src/test/java/org/springframework/ai/autoconfigure/vectorstore/opensearch/AwsOpenSearchVectorStoreAutoConfigurationIT.java

@@ -113,12 +113,12 @@ class AwsOpenSearchVectorStoreAutoConfigurationIT {
 			vectorStore.add(this.documents);
 
 			Awaitility.await()
-				.until(() -> vectorStore
-					.similaritySearch(SearchRequest.query("Great Depression").withTopK(1).withSimilarityThreshold(0)),
+				.until(() -> vectorStore.similaritySearch(
+						SearchRequest.builder().query("Great Depression").topK(1).similarityThreshold(0).build()),
 						hasSize(1));
 
-			List<Document> results = vectorStore
-				.similaritySearch(SearchRequest.query("Great Depression").withTopK(1).withSimilarityThreshold(0));
+			List<Document> results = vectorStore.similaritySearch(
+					SearchRequest.builder().query("Great Depression").topK(1).similarityThreshold(0).build());
 
 			assertThat(results).hasSize(1);
 			Document resultDoc = results.get(0);
@@ -132,8 +132,8 @@ class AwsOpenSearchVectorStoreAutoConfigurationIT {
 			vectorStore.delete(this.documents.stream().map(Document::getId).toList());
 
 			Awaitility.await()
-				.until(() -> vectorStore
-					.similaritySearch(SearchRequest.query("Great Depression").withTopK(1).withSimilarityThreshold(0)),
+				.until(() -> vectorStore.similaritySearch(
+						SearchRequest.builder().query("Great Depression").topK(1).similarityThreshold(0).build()),
 						hasSize(0));
 		});
 	}

spring-ai-spring-boot-autoconfigure/src/test/java/org/springframework/ai/autoconfigure/vectorstore/opensearch/OpenSearchVectorStoreAutoConfigurationIT.java

@@ -106,14 +106,14 @@ class OpenSearchVectorStoreAutoConfigurationIT {
 					VectorStoreObservationContext.Operation.ADD);
 
 			Awaitility.await()
-				.until(() -> vectorStore
-					.similaritySearch(SearchRequest.query("Great Depression").withTopK(1).withSimilarityThreshold(0)),
+				.until(() -> vectorStore.similaritySearch(
+						SearchRequest.builder().query("Great Depression").topK(1).similarityThreshold(0).build()),
 						hasSize(1));
 
 			observationRegistry.clear();
 
-			List<Document> results = vectorStore
-				.similaritySearch(SearchRequest.query("Great Depression").withTopK(1).withSimilarityThreshold(0));
+			List<Document> results = vectorStore.similaritySearch(
+					SearchRequest.builder().query("Great Depression").topK(1).similarityThreshold(0).build());
 
 			assertObservationRegistry(observationRegistry, VectorStoreProvider.OPENSEARCH,
 					VectorStoreObservationContext.Operation.QUERY);
@@ -136,8 +136,8 @@ class OpenSearchVectorStoreAutoConfigurationIT {
 			observationRegistry.clear();
 
 			Awaitility.await()
-				.until(() -> vectorStore
-					.similaritySearch(SearchRequest.query("Great Depression").withTopK(1).withSimilarityThreshold(0)),
+				.until(() -> vectorStore.similaritySearch(
+						SearchRequest.builder().query("Great Depression").topK(1).similarityThreshold(0).build()),
 						hasSize(0));
 		});
 	}

spring-ai-spring-boot-autoconfigure/src/test/java/org/springframework/ai/autoconfigure/vectorstore/oracle/OracleVectorStoreAutoConfigurationIT.java

@@ -101,7 +101,7 @@ public class OracleVectorStoreAutoConfigurationIT {
 			observationRegistry.clear();
 
 			List<Document> results = vectorStore
-				.similaritySearch(SearchRequest.query("What is Great Depression?").withTopK(1));
+				.similaritySearch(SearchRequest.builder().query("What is Great Depression?").topK(1).build());
 
 			assertThat(results).hasSize(1);
 			Document resultDoc = results.get(0);
@@ -119,7 +119,7 @@ public class OracleVectorStoreAutoConfigurationIT {
 					VectorStoreObservationContext.Operation.DELETE);
 			observationRegistry.clear();
 
-			results = vectorStore.similaritySearch(SearchRequest.query("Great Depression").withTopK(1));
+			results = vectorStore.similaritySearch(SearchRequest.builder().query("Great Depression").topK(1).build());
 			assertThat(results).hasSize(0);
 		});
 	}

spring-ai-spring-boot-autoconfigure/src/test/java/org/springframework/ai/autoconfigure/vectorstore/pgvector/PgVectorStoreAutoConfigurationIT.java

@@ -115,7 +115,7 @@ public class PgVectorStoreAutoConfigurationIT {
 			observationRegistry.clear();
 
 			List<Document> results = vectorStore
-				.similaritySearch(SearchRequest.query("What is Great Depression?").withTopK(1));
+				.similaritySearch(SearchRequest.builder().query("What is Great Depression?").topK(1).build());
 
 			assertThat(results).hasSize(1);
 			Document resultDoc = results.get(0);
@@ -132,7 +132,7 @@ public class PgVectorStoreAutoConfigurationIT {
 			assertObservationRegistry(observationRegistry, VectorStoreProvider.PG_VECTOR,
 					VectorStoreObservationContext.Operation.DELETE);
 
-			results = vectorStore.similaritySearch(SearchRequest.query("Great Depression").withTopK(1));
+			results = vectorStore.similaritySearch(SearchRequest.builder().query("Great Depression").topK(1).build());
 			assertThat(results).hasSize(0);
 			observationRegistry.clear();
 		});

spring-ai-spring-boot-autoconfigure/src/test/java/org/springframework/ai/autoconfigure/vectorstore/pinecone/PineconeVectorStoreAutoConfigurationIT.java

@@ -99,10 +99,12 @@ public class PineconeVectorStoreAutoConfigurationIT {
 					observationRegistry, VectorStoreProvider.PINECONE, VectorStoreObservationContext.Operation.ADD);
 
 			Awaitility.await()
-				.until(() -> vectorStore.similaritySearch(SearchRequest.query("Spring").withTopK(1)), hasSize(1));
+				.until(() -> vectorStore.similaritySearch(SearchRequest.builder().query("Spring").topK(1).build()),
+						hasSize(1));
 			observationRegistry.clear();
 
-			List<Document> results = vectorStore.similaritySearch(SearchRequest.query("Spring").withTopK(1));
+			List<Document> results = vectorStore
+				.similaritySearch(SearchRequest.builder().query("Spring").topK(1).build());
 
 			assertThat(results).hasSize(1);
 			Document resultDoc = results.get(0);
@@ -124,7 +126,8 @@ public class PineconeVectorStoreAutoConfigurationIT {
 			observationRegistry.clear();
 
 			Awaitility.await()
-				.until(() -> vectorStore.similaritySearch(SearchRequest.query("Spring").withTopK(1)), hasSize(0));
+				.until(() -> vectorStore.similaritySearch(SearchRequest.builder().query("Spring").topK(1).build()),
+						hasSize(0));
 		});
 	}
 

spring-ai-spring-boot-autoconfigure/src/test/java/org/springframework/ai/autoconfigure/vectorstore/qdrant/QdrantVectorStoreAutoConfigurationIT.java

@@ -92,7 +92,7 @@ public class QdrantVectorStoreAutoConfigurationIT {
 			observationRegistry.clear();
 
 			List<Document> results = vectorStore
-				.similaritySearch(SearchRequest.query("What is Great Depression?").withTopK(1));
+				.similaritySearch(SearchRequest.builder().query("What is Great Depression?").topK(1).build());
 
 			assertThat(results).hasSize(1);
 			Document resultDoc = results.get(0);
@@ -105,7 +105,7 @@ public class QdrantVectorStoreAutoConfigurationIT {
 
 			// Remove all documents from the store
 			vectorStore.delete(this.documents.stream().map(doc -> doc.getId()).toList());
-			results = vectorStore.similaritySearch(SearchRequest.query("Great Depression").withTopK(1));
+			results = vectorStore.similaritySearch(SearchRequest.builder().query("Great Depression").topK(1).build());
 			assertThat(results).hasSize(0);
 
 			assertObservationRegistry(observationRegistry, VectorStoreProvider.QDRANT,

spring-ai-spring-boot-autoconfigure/src/test/java/org/springframework/ai/autoconfigure/vectorstore/qdrant/QdrantVectorStoreCloudAutoConfigurationIT.java

@@ -121,7 +121,7 @@ public class QdrantVectorStoreCloudAutoConfigurationIT {
 			vectorStore.add(this.documents);
 
 			List<Document> results = vectorStore
-				.similaritySearch(SearchRequest.query("What is Great Depression?").withTopK(1));
+				.similaritySearch(SearchRequest.builder().query("What is Great Depression?").topK(1).build());
 
 			assertThat(results).hasSize(1);
 			Document resultDoc = results.get(0);
@@ -130,7 +130,7 @@ public class QdrantVectorStoreCloudAutoConfigurationIT {
 
 			// Remove all documents from the store
 			vectorStore.delete(this.documents.stream().map(doc -> doc.getId()).toList());
-			results = vectorStore.similaritySearch(SearchRequest.query("Great Depression").withTopK(1));
+			results = vectorStore.similaritySearch(SearchRequest.builder().query("Great Depression").topK(1).build());
 			assertThat(results).hasSize(0);
 		});
 	}

spring-ai-spring-boot-autoconfigure/src/test/java/org/springframework/ai/autoconfigure/vectorstore/redis/RedisVectorStoreAutoConfigurationIT.java

@@ -81,7 +81,8 @@ class RedisVectorStoreAutoConfigurationIT {
 					VectorStoreObservationContext.Operation.ADD);
 			observationRegistry.clear();
 
-			List<Document> results = vectorStore.similaritySearch(SearchRequest.query("Spring").withTopK(1));
+			List<Document> results = vectorStore
+				.similaritySearch(SearchRequest.builder().query("Spring").topK(1).build());
 
 			assertThat(results).hasSize(1);
 			Document resultDoc = results.get(0);
@@ -100,7 +101,7 @@ class RedisVectorStoreAutoConfigurationIT {
 					VectorStoreObservationContext.Operation.DELETE);
 			observationRegistry.clear();
 
-			results = vectorStore.similaritySearch(SearchRequest.query("Spring").withTopK(1));
+			results = vectorStore.similaritySearch(SearchRequest.builder().query("Spring").topK(1).build());
 			assertThat(results).isEmpty();
 		});
 	}

spring-ai-spring-boot-autoconfigure/src/test/java/org/springframework/ai/autoconfigure/vectorstore/typesense/TypesenseVectorStoreAutoConfigurationIT.java

@@ -87,7 +87,8 @@ public class TypesenseVectorStoreAutoConfigurationIT {
 						VectorStoreObservationContext.Operation.ADD);
 				observationRegistry.clear();
 
-				List<Document> results = vectorStore.similaritySearch(SearchRequest.query("Spring").withTopK(1));
+				List<Document> results = vectorStore
+					.similaritySearch(SearchRequest.builder().query("Spring").topK(1).build());
 
 				assertThat(results).hasSize(1);
 				Document resultDoc = results.get(0);
@@ -107,7 +108,7 @@ public class TypesenseVectorStoreAutoConfigurationIT {
 						VectorStoreObservationContext.Operation.DELETE);
 				observationRegistry.clear();
 
-				results = vectorStore.similaritySearch(SearchRequest.query("Spring").withTopK(1));
+				results = vectorStore.similaritySearch(SearchRequest.builder().query("Spring").topK(1).build());
 				assertThat(results).hasSize(0);
 			});
 	}

spring-ai-spring-boot-autoconfigure/src/test/java/org/springframework/ai/autoconfigure/vectorstore/weaviate/WeaviateVectorStoreAutoConfigurationIT.java

@@ -94,35 +94,45 @@ public class WeaviateVectorStoreAutoConfigurationIT {
 					VectorStoreObservationContext.Operation.ADD);
 			observationRegistry.clear();
 
-			var request = SearchRequest.query("The World").withTopK(5);
+			var request = SearchRequest.builder().query("The World").topK(5).build();
 
 			List<Document> results = vectorStore.similaritySearch(request);
 			assertThat(results).hasSize(2);
 
-			results = vectorStore
-				.similaritySearch(request.withSimilarityThresholdAll().withFilterExpression("country == 'Bulgaria'"));
+			results = vectorStore.similaritySearch(SearchRequest.from(request)
+				.similarityThresholdAll()
+				.filterExpression("country == 'Bulgaria'")
+				.build());
 			assertThat(results).hasSize(1);
 			assertThat(results.get(0).getId()).isEqualTo(bgDocument.getId());
 
 			assertObservationRegistry(observationRegistry, VectorStoreProvider.WEAVIATE,
 					VectorStoreObservationContext.Operation.QUERY);
 
-			results = vectorStore.similaritySearch(
-					request.withSimilarityThresholdAll().withFilterExpression("country == 'Netherlands'"));
+			results = vectorStore.similaritySearch(SearchRequest.from(request)
+				.similarityThresholdAll()
+				.filterExpression("country == 'Netherlands'")
+				.build());
 			assertThat(results).hasSize(1);
 			assertThat(results.get(0).getId()).isEqualTo(nlDocument.getId());
 
-			results = vectorStore.similaritySearch(
-					request.withSimilarityThresholdAll().withFilterExpression("price > 1.57 && active == true"));
+			results = vectorStore.similaritySearch(SearchRequest.from(request)
+				.similarityThresholdAll()
+				.filterExpression("price > 1.57 && active == true")
+				.build());
 			assertThat(results).hasSize(1);
 			assertThat(results.get(0).getId()).isEqualTo(bgDocument.getId());
 
-			results = vectorStore
-				.similaritySearch(request.withSimilarityThresholdAll().withFilterExpression("year in [2020, 2023]"));
+			results = vectorStore.similaritySearch(SearchRequest.from(request)
+				.similarityThresholdAll()
+				.filterExpression("year in [2020, 2023]")
+				.build());
 			assertThat(results).hasSize(2);
 
-			results = vectorStore.similaritySearch(
-					request.withSimilarityThresholdAll().withFilterExpression("year > 2020 && year <= 2023"));
+			results = vectorStore.similaritySearch(SearchRequest.from(request)
+				.similarityThresholdAll()
+				.filterExpression("year > 2020 && year <= 2023")
+				.build());
 			assertThat(results).hasSize(1);
 			assertThat(results.get(0).getId()).isEqualTo(nlDocument.getId());
 

spring-ai-spring-boot-testcontainers/src/test/java/org/springframework/ai/testcontainers/service/connection/chroma/ChromaContainerConnectionDetailsFactoryIT.java

@@ -63,18 +63,20 @@ class ChromaContainerConnectionDetailsFactoryIT {
 
 		this.vectorStore.add(List.of(bgDocument, nlDocument));
 
-		var request = SearchRequest.query("The World").withTopK(5);
+		var request = SearchRequest.builder().query("The World").topK(5).build();
 
 		List<Document> results = this.vectorStore.similaritySearch(request);
 		assertThat(results).hasSize(2);
 
-		results = this.vectorStore
-			.similaritySearch(request.withSimilarityThresholdAll().withFilterExpression("country == 'Bulgaria'"));
+		results = this.vectorStore.similaritySearch(
+				SearchRequest.from(request).similarityThresholdAll().filterExpression("country == 'Bulgaria'").build());
 		assertThat(results).hasSize(1);
 		assertThat(results.get(0).getId()).isEqualTo(bgDocument.getId());
 
-		results = this.vectorStore
-			.similaritySearch(request.withSimilarityThresholdAll().withFilterExpression("country == 'Netherlands'"));
+		results = this.vectorStore.similaritySearch(SearchRequest.from(request)
+			.similarityThresholdAll()
+			.filterExpression("country == 'Netherlands'")
+			.build());
 		assertThat(results).hasSize(1);
 		assertThat(results.get(0).getId()).isEqualTo(nlDocument.getId());
 

spring-ai-spring-boot-testcontainers/src/test/java/org/springframework/ai/testcontainers/service/connection/chroma/ChromaWithToken2ContainerConnectionDetailsFactoryIT.java

@@ -67,18 +67,20 @@ class ChromaWithToken2ContainerConnectionDetailsFactoryIT {
 
 		this.vectorStore.add(List.of(bgDocument, nlDocument));
 
-		var request = SearchRequest.query("The World").withTopK(5);
+		var request = SearchRequest.builder().query("The World").topK(5).build();
 
 		List<Document> results = this.vectorStore.similaritySearch(request);
 		assertThat(results).hasSize(2);
 
-		results = this.vectorStore
-			.similaritySearch(request.withSimilarityThresholdAll().withFilterExpression("country == 'Bulgaria'"));
+		results = this.vectorStore.similaritySearch(
+				SearchRequest.from(request).similarityThresholdAll().filterExpression("country == 'Bulgaria'").build());
 		assertThat(results).hasSize(1);
 		assertThat(results.get(0).getId()).isEqualTo(bgDocument.getId());
 
-		results = this.vectorStore
-			.similaritySearch(request.withSimilarityThresholdAll().withFilterExpression("country == 'Netherlands'"));
+		results = this.vectorStore.similaritySearch(SearchRequest.from(request)
+			.similarityThresholdAll()
+			.filterExpression("country == 'Netherlands'")
+			.build());
 		assertThat(results).hasSize(1);
 		assertThat(results.get(0).getId()).isEqualTo(nlDocument.getId());
 

spring-ai-spring-boot-testcontainers/src/test/java/org/springframework/ai/testcontainers/service/connection/chroma/ChromaWithTokenContainerConnectionDetailsFactoryIT.java

@@ -65,18 +65,20 @@ class ChromaWithTokenContainerConnectionDetailsFactoryIT {
 
 		this.vectorStore.add(List.of(bgDocument, nlDocument));
 
-		var request = SearchRequest.query("The World").withTopK(5);
+		var request = SearchRequest.builder().query("The World").topK(5).build();
 
 		List<Document> results = this.vectorStore.similaritySearch(request);
 		assertThat(results).hasSize(2);
 
-		results = this.vectorStore
-			.similaritySearch(request.withSimilarityThresholdAll().withFilterExpression("country == 'Bulgaria'"));
+		results = this.vectorStore.similaritySearch(
+				SearchRequest.from(request).similarityThresholdAll().filterExpression("country == 'Bulgaria'").build());
 		assertThat(results).hasSize(1);
 		assertThat(results.get(0).getId()).isEqualTo(bgDocument.getId());
 
-		results = this.vectorStore
-			.similaritySearch(request.withSimilarityThresholdAll().withFilterExpression("country == 'Netherlands'"));
+		results = this.vectorStore.similaritySearch(SearchRequest.from(request)
+			.similarityThresholdAll()
+			.filterExpression("country == 'Netherlands'")
+			.build());
 		assertThat(results).hasSize(1);
 		assertThat(results.get(0).getId()).isEqualTo(nlDocument.getId());
 

spring-ai-spring-boot-testcontainers/src/test/java/org/springframework/ai/testcontainers/service/connection/milvus/MilvusContainerConnectionDetailsFactoryIT.java

@@ -65,7 +65,8 @@ class MilvusContainerConnectionDetailsFactoryIT {
 	public void addAndSearch() {
 		this.vectorStore.add(this.documents);
 
-		List<Document> results = this.vectorStore.similaritySearch(SearchRequest.query("Spring").withTopK(1));
+		List<Document> results = this.vectorStore
+			.similaritySearch(SearchRequest.builder().query("Spring").topK(1).build());
 
 		assertThat(results).hasSize(1);
 		Document resultDoc = results.get(0);
@@ -78,7 +79,7 @@ class MilvusContainerConnectionDetailsFactoryIT {
 		// Remove all documents from the store
 		this.vectorStore.delete(this.documents.stream().map(doc -> doc.getId()).toList());
 
-		results = this.vectorStore.similaritySearch(SearchRequest.query("Spring").withTopK(1));
+		results = this.vectorStore.similaritySearch(SearchRequest.builder().query("Spring").topK(1).build());
 		assertThat(results).hasSize(0);
 	}
 

spring-ai-spring-boot-testcontainers/src/test/java/org/springframework/ai/testcontainers/service/connection/mongo/MongoDbAtlasLocalContainerConnectionDetailsFactoryIT.java

@@ -75,7 +75,8 @@ class MongoDbAtlasLocalContainerConnectionDetailsFactoryIT {
 		this.vectorStore.add(documents);
 		Thread.sleep(5000); // Await a second for the document to be indexed
 
-		List<Document> results = this.vectorStore.similaritySearch(SearchRequest.query("Great").withTopK(1));
+		List<Document> results = this.vectorStore
+			.similaritySearch(SearchRequest.builder().query("Great").topK(1).build());
 
 		assertThat(results).hasSize(1);
 		Document resultDoc = results.get(0);
@@ -87,7 +88,8 @@ class MongoDbAtlasLocalContainerConnectionDetailsFactoryIT {
 		// Remove all documents from the store
 		this.vectorStore.delete(documents.stream().map(Document::getId).collect(Collectors.toList()));
 
-		List<Document> results2 = this.vectorStore.similaritySearch(SearchRequest.query("Great").withTopK(1));
+		List<Document> results2 = this.vectorStore
+			.similaritySearch(SearchRequest.builder().query("Great").topK(1).build());
 		assertThat(results2).isEmpty();
 	}
 

spring-ai-spring-boot-testcontainers/src/test/java/org/springframework/ai/testcontainers/service/connection/opensearch/AwsOpenSearchContainerConnectionDetailsFactoryIT.java

@@ -100,12 +100,12 @@ class AwsOpenSearchContainerConnectionDetailsFactoryIT {
 		this.vectorStore.add(this.documents);
 
 		Awaitility.await()
-			.until(() -> this.vectorStore
-				.similaritySearch(SearchRequest.query("Great Depression").withTopK(1).withSimilarityThreshold(0)),
+			.until(() -> this.vectorStore.similaritySearch(
+					SearchRequest.builder().query("Great Depression").topK(1).similarityThreshold(0).build()),
 					hasSize(1));
 
 		List<Document> results = this.vectorStore
-			.similaritySearch(SearchRequest.query("Great Depression").withTopK(1).withSimilarityThreshold(0));
+			.similaritySearch(SearchRequest.builder().query("Great Depression").topK(1).similarityThreshold(0).build());
 
 		assertThat(results).hasSize(1);
 		Document resultDoc = results.get(0);
@@ -119,8 +119,8 @@ class AwsOpenSearchContainerConnectionDetailsFactoryIT {
 		this.vectorStore.delete(this.documents.stream().map(Document::getId).toList());
 
 		Awaitility.await()
-			.until(() -> this.vectorStore
-				.similaritySearch(SearchRequest.query("Great Depression").withTopK(1).withSimilarityThreshold(0)),
+			.until(() -> this.vectorStore.similaritySearch(
+					SearchRequest.builder().query("Great Depression").topK(1).similarityThreshold(0).build()),
 					hasSize(0));
 	}
 

spring-ai-spring-boot-testcontainers/src/test/java/org/springframework/ai/testcontainers/service/connection/opensearch/OpenSearchContainerConnectionDetailsFactoryIT.java

@@ -80,12 +80,12 @@ class OpenSearchContainerConnectionDetailsFactoryIT {
 			vectorStore.add(this.documents);
 
 			Awaitility.await()
-				.until(() -> vectorStore
-					.similaritySearch(SearchRequest.query("Great Depression").withTopK(1).withSimilarityThreshold(0)),
+				.until(() -> vectorStore.similaritySearch(
+						SearchRequest.builder().query("Great Depression").topK(1).similarityThreshold(0).build()),
 						hasSize(1));
 
-			List<Document> results = vectorStore
-				.similaritySearch(SearchRequest.query("Great Depression").withTopK(1).withSimilarityThreshold(0));
+			List<Document> results = vectorStore.similaritySearch(
+					SearchRequest.builder().query("Great Depression").topK(1).similarityThreshold(0).build());
 
 			assertThat(results).hasSize(1);
 			Document resultDoc = results.get(0);
@@ -99,8 +99,8 @@ class OpenSearchContainerConnectionDetailsFactoryIT {
 			vectorStore.delete(this.documents.stream().map(Document::getId).toList());
 
 			Awaitility.await()
-				.until(() -> vectorStore
-					.similaritySearch(SearchRequest.query("Great Depression").withTopK(1).withSimilarityThreshold(0)),
+				.until(() -> vectorStore.similaritySearch(
+						SearchRequest.builder().query("Great Depression").topK(1).similarityThreshold(0).build()),
 						hasSize(0));
 		});
 	}

spring-ai-spring-boot-testcontainers/src/test/java/org/springframework/ai/testcontainers/service/connection/qdrant/QdrantContainerConnectionDetailsFactoryIT.java

@@ -76,7 +76,7 @@ public class QdrantContainerConnectionDetailsFactoryIT {
 		this.vectorStore.add(this.documents);
 
 		List<Document> results = this.vectorStore
-			.similaritySearch(SearchRequest.query("What is Great Depression?").withTopK(1));
+			.similaritySearch(SearchRequest.builder().query("What is Great Depression?").topK(1).build());
 
 		assertThat(results).hasSize(1);
 		Document resultDoc = results.get(0);
@@ -85,7 +85,7 @@ public class QdrantContainerConnectionDetailsFactoryIT {
 
 		// Remove all documents from the store
 		this.vectorStore.delete(this.documents.stream().map(doc -> doc.getId()).toList());
-		results = this.vectorStore.similaritySearch(SearchRequest.query("Great Depression").withTopK(1));
+		results = this.vectorStore.similaritySearch(SearchRequest.builder().query("Great Depression").topK(1).build());
 		assertThat(results).hasSize(0);
 	}
 

spring-ai-spring-boot-testcontainers/src/test/java/org/springframework/ai/testcontainers/service/connection/qdrant/QdrantContainerWithApiKeyConnectionDetailsFactoryIT.java

@@ -76,7 +76,7 @@ public class QdrantContainerWithApiKeyConnectionDetailsFactoryIT {
 		this.vectorStore.add(this.documents);
 
 		List<Document> results = this.vectorStore
-			.similaritySearch(SearchRequest.query("What is Great Depression?").withTopK(1));
+			.similaritySearch(SearchRequest.builder().query("What is Great Depression?").topK(1).build());
 
 		assertThat(results).hasSize(1);
 		Document resultDoc = results.get(0);
@@ -85,7 +85,7 @@ public class QdrantContainerWithApiKeyConnectionDetailsFactoryIT {
 
 		// Remove all documents from the store
 		this.vectorStore.delete(this.documents.stream().map(doc -> doc.getId()).toList());
-		results = this.vectorStore.similaritySearch(SearchRequest.query("Great Depression").withTopK(1));
+		results = this.vectorStore.similaritySearch(SearchRequest.builder().query("Great Depression").topK(1).build());
 		assertThat(results).hasSize(0);
 	}
 

spring-ai-spring-boot-testcontainers/src/test/java/org/springframework/ai/testcontainers/service/connection/typesense/TypesenseContainerConnectionDetailsFactoryIT.java

@@ -70,7 +70,8 @@ class TypesenseContainerConnectionDetailsFactoryIT {
 
 		this.vectorStore.add(this.documents);
 
-		List<Document> results = this.vectorStore.similaritySearch(SearchRequest.query("Spring").withTopK(1));
+		List<Document> results = this.vectorStore
+			.similaritySearch(SearchRequest.builder().query("Spring").topK(1).build());
 
 		assertThat(results).hasSize(1);
 		Document resultDoc = results.get(0);
@@ -82,7 +83,7 @@ class TypesenseContainerConnectionDetailsFactoryIT {
 
 		this.vectorStore.delete(this.documents.stream().map(doc -> doc.getId()).toList());
 
-		results = this.vectorStore.similaritySearch(SearchRequest.query("Spring").withTopK(1));
+		results = this.vectorStore.similaritySearch(SearchRequest.builder().query("Spring").topK(1).build());
 		assertThat(results).hasSize(0);
 	}
 

spring-ai-spring-boot-testcontainers/src/test/java/org/springframework/ai/testcontainers/service/connection/weaviate/WeaviateContainerConnectionDetailsFactoryIT.java

@@ -83,32 +83,38 @@ class WeaviateContainerConnectionDetailsFactoryIT {
 
 		this.vectorStore.add(List.of(bgDocument, nlDocument));
 
-		var request = SearchRequest.query("The World").withTopK(5);
+		var request = SearchRequest.builder().query("The World").topK(5).build();
 
 		List<Document> results = this.vectorStore.similaritySearch(request);
 		assertThat(results).hasSize(2);
 
-		results = this.vectorStore
-			.similaritySearch(request.withSimilarityThresholdAll().withFilterExpression("country == 'Bulgaria'"));
+		results = this.vectorStore.similaritySearch(
+				SearchRequest.from(request).similarityThresholdAll().filterExpression("country == 'Bulgaria'").build());
 		assertThat(results).hasSize(1);
 		assertThat(results.get(0).getId()).isEqualTo(bgDocument.getId());
 
-		results = this.vectorStore
-			.similaritySearch(request.withSimilarityThresholdAll().withFilterExpression("country == 'Netherlands'"));
+		results = this.vectorStore.similaritySearch(SearchRequest.from(request)
+			.similarityThresholdAll()
+			.filterExpression("country == 'Netherlands'")
+			.build());
 		assertThat(results).hasSize(1);
 		assertThat(results.get(0).getId()).isEqualTo(nlDocument.getId());
 
-		results = this.vectorStore.similaritySearch(
-				request.withSimilarityThresholdAll().withFilterExpression("price > 1.57 && active == true"));
+		results = this.vectorStore.similaritySearch(SearchRequest.from(request)
+			.similarityThresholdAll()
+			.filterExpression("price > 1.57 && active == true")
+			.build());
 		assertThat(results).hasSize(1);
 		assertThat(results.get(0).getId()).isEqualTo(bgDocument.getId());
 
-		results = this.vectorStore
-			.similaritySearch(request.withSimilarityThresholdAll().withFilterExpression("year in [2020, 2023]"));
+		results = this.vectorStore.similaritySearch(
+				SearchRequest.from(request).similarityThresholdAll().filterExpression("year in [2020, 2023]").build());
 		assertThat(results).hasSize(2);
 
-		results = this.vectorStore
-			.similaritySearch(request.withSimilarityThresholdAll().withFilterExpression("year > 2020 && year <= 2023"));
+		results = this.vectorStore.similaritySearch(SearchRequest.from(request)
+			.similarityThresholdAll()
+			.filterExpression("year > 2020 && year <= 2023")
+			.build());
 		assertThat(results).hasSize(1);
 		assertThat(results.get(0).getId()).isEqualTo(nlDocument.getId());
 

vector-stores/spring-ai-azure-cosmos-db-store/src/main/java/org/springframework/ai/vectorstore/cosmosdb/CosmosDBVectorStore.java

@@ -344,7 +344,7 @@ public class CosmosDBVectorStore extends AbstractObservationVectorStore implemen
 
 	@Override
 	public List<Document> similaritySearch(String query) {
-		return similaritySearch(SearchRequest.query(query));
+		return similaritySearch(SearchRequest.builder().query(query).build());
 	}
 
 	@Override

vector-stores/spring-ai-azure-cosmos-db-store/src/test/java/org/springframework/ai/vectorstore/cosmosdb/CosmosDBVectorStoreIT.java

@@ -77,7 +77,8 @@ public class CosmosDBVectorStoreIT {
 			.hasMessageContaining("Duplicate document id: " + document1.getId());
 
 		// Perform a similarity search
-		List<Document> results = this.vectorStore.similaritySearch(SearchRequest.query("Sample content").withTopK(1));
+		List<Document> results = this.vectorStore
+			.similaritySearch(SearchRequest.builder().query("Sample content").topK(1).build());
 
 		// Verify the search results
 		assertThat(results).isNotEmpty();
@@ -87,7 +88,8 @@ public class CosmosDBVectorStoreIT {
 		this.vectorStore.delete(List.of(document1.getId(), document2.getId()));
 
 		// Perform a similarity search again
-		List<Document> results2 = this.vectorStore.similaritySearch(SearchRequest.query("Sample content").withTopK(1));
+		List<Document> results2 = this.vectorStore
+			.similaritySearch(SearchRequest.builder().query("Sample content").topK(1).build());
 
 		// Verify the search results
 		assertThat(results2).isEmpty();
@@ -129,24 +131,30 @@ public class CosmosDBVectorStoreIT {
 
 		this.vectorStore.add(List.of(document1, document2, document3, document4));
 		FilterExpressionBuilder b = new FilterExpressionBuilder();
-		List<Document> results = this.vectorStore.similaritySearch(SearchRequest.query("The World")
-			.withTopK(10)
-			.withFilterExpression((b.in("country", "UK", "NL")).build()));
+		List<Document> results = this.vectorStore.similaritySearch(SearchRequest.builder()
+			.query("The World")
+			.topK(10)
+			.filterExpression((b.in("country", "UK", "NL")).build())
+			.build());
 
 		assertThat(results).hasSize(2);
 		assertThat(results).extracting(Document::getId).containsExactlyInAnyOrder("1", "2");
 
-		List<Document> results2 = this.vectorStore.similaritySearch(SearchRequest.query("The World")
-			.withTopK(10)
-			.withFilterExpression(
-					b.and(b.or(b.gte("year", 2021), b.eq("country", "NL")), b.ne("city", "Amsterdam")).build()));
+		List<Document> results2 = this.vectorStore.similaritySearch(SearchRequest.builder()
+			.query("The World")
+			.topK(10)
+			.filterExpression(
+					b.and(b.or(b.gte("year", 2021), b.eq("country", "NL")), b.ne("city", "Amsterdam")).build())
+			.build());
 
 		assertThat(results2).hasSize(1);
 		assertThat(results2).extracting(Document::getId).containsExactlyInAnyOrder("1");
 
-		List<Document> results3 = this.vectorStore.similaritySearch(SearchRequest.query("The World")
-			.withTopK(10)
-			.withFilterExpression(b.and(b.eq("country", "US"), b.eq("year", 2020)).build()));
+		List<Document> results3 = this.vectorStore.similaritySearch(SearchRequest.builder()
+			.query("The World")
+			.topK(10)
+			.filterExpression(b.and(b.eq("country", "US"), b.eq("year", 2020)).build())
+			.build());
 
 		assertThat(results3).hasSize(1);
 		assertThat(results3).extracting(Document::getId).containsExactlyInAnyOrder("4");
@@ -154,7 +162,8 @@ public class CosmosDBVectorStoreIT {
 		this.vectorStore.delete(List.of(document1.getId(), document2.getId(), document3.getId(), document4.getId()));
 
 		// Perform a similarity search again
-		List<Document> results4 = this.vectorStore.similaritySearch(SearchRequest.query("The World").withTopK(1));
+		List<Document> results4 = this.vectorStore
+			.similaritySearch(SearchRequest.builder().query("The World").topK(1).build());
 
 		// Verify the search results
 		assertThat(results4).isEmpty();

vector-stores/spring-ai-azure-store/src/main/java/org/springframework/ai/vectorstore/azure/AzureVectorStore.java

@@ -315,9 +315,11 @@ public class AzureVectorStore extends AbstractObservationVectorStore implements
 
 	@Override
 	public List<Document> similaritySearch(String query) {
-		return this.similaritySearch(SearchRequest.query(query)
-			.withTopK(this.defaultTopK)
-			.withSimilarityThreshold(this.defaultSimilarityThreshold));
+		return this.similaritySearch(SearchRequest.builder()
+			.query(query)
+			.topK(this.defaultTopK)
+			.similarityThreshold(this.defaultSimilarityThreshold)
+			.build());
 	}
 
 	@Override

vector-stores/spring-ai-azure-store/src/test/java/org/springframework/ai/vectorstore/azure/AzureVectorStoreIT.java

@@ -94,10 +94,11 @@ public class AzureVectorStoreIT {
 			vectorStore.add(this.documents);
 
 			Awaitility.await()
-				.until(() -> vectorStore.similaritySearch(SearchRequest.query("Great Depression").withTopK(1)),
-						hasSize(1));
+				.until(() -> vectorStore
+					.similaritySearch(SearchRequest.builder().query("Great Depression").topK(1).build()), hasSize(1));
 
-			List<Document> results = vectorStore.similaritySearch(SearchRequest.query("Great Depression").withTopK(1));
+			List<Document> results = vectorStore
+				.similaritySearch(SearchRequest.builder().query("Great Depression").topK(1).build());
 
 			assertThat(results).hasSize(1);
 			Document resultDoc = results.get(0);
@@ -111,7 +112,8 @@ public class AzureVectorStoreIT {
 			vectorStore.delete(this.documents.stream().map(doc -> doc.getId()).toList());
 
 			Awaitility.await()
-				.until(() -> vectorStore.similaritySearch(SearchRequest.query("Hello").withTopK(1)), hasSize(0));
+				.until(() -> vectorStore.similaritySearch(SearchRequest.builder().query("Hello").topK(1).build()),
+						hasSize(0));
 		});
 	}
 
@@ -131,60 +133,75 @@ public class AzureVectorStoreIT {
 			vectorStore.add(List.of(bgDocument, nlDocument, bgDocument2));
 
 			Awaitility.await()
-				.until(() -> vectorStore.similaritySearch(SearchRequest.query("The World").withTopK(5)), hasSize(3));
+				.until(() -> vectorStore.similaritySearch(SearchRequest.builder().query("The World").topK(5).build()),
+						hasSize(3));
 
-			List<Document> results = vectorStore.similaritySearch(SearchRequest.query("The World")
-				.withTopK(5)
-				.withSimilarityThresholdAll()
-				.withFilterExpression("country == 'NL'"));
+			List<Document> results = vectorStore.similaritySearch(SearchRequest.builder()
+				.query("The World")
+				.topK(5)
+				.similarityThresholdAll()
+				.filterExpression("country == 'NL'")
+				.build());
 			assertThat(results).hasSize(1);
 			assertThat(results.get(0).getId()).isEqualTo(nlDocument.getId());
 
-			results = vectorStore.similaritySearch(SearchRequest.query("The World")
-				.withTopK(5)
-				.withSimilarityThresholdAll()
-				.withFilterExpression("country == 'BG'"));
+			results = vectorStore.similaritySearch(SearchRequest.builder()
+				.query("The World")
+				.topK(5)
+				.similarityThresholdAll()
+				.filterExpression("country == 'BG'")
+				.build());
 
 			assertThat(results).hasSize(2);
 			assertThat(results.get(0).getId()).isIn(bgDocument.getId(), bgDocument2.getId());
 			assertThat(results.get(1).getId()).isIn(bgDocument.getId(), bgDocument2.getId());
 
-			results = vectorStore.similaritySearch(SearchRequest.query("The World")
-				.withTopK(5)
-				.withSimilarityThresholdAll()
-				.withFilterExpression("country == 'BG' && year == 2020"));
+			results = vectorStore.similaritySearch(SearchRequest.builder()
+				.query("The World")
+				.topK(5)
+				.similarityThresholdAll()
+				.filterExpression("country == 'BG' && year == 2020")
+				.build());
 
 			assertThat(results).hasSize(1);
 			assertThat(results.get(0).getId()).isEqualTo(bgDocument.getId());
 
-			results = vectorStore.similaritySearch(SearchRequest.query("The World")
-				.withTopK(5)
-				.withSimilarityThresholdAll()
-				.withFilterExpression("country in ['BG']"));
+			results = vectorStore.similaritySearch(SearchRequest.builder()
+				.query("The World")
+				.topK(5)
+				.similarityThresholdAll()
+				.filterExpression("country in ['BG']")
+				.build());
 
 			assertThat(results).hasSize(2);
 			assertThat(results.get(0).getId()).isIn(bgDocument.getId(), bgDocument2.getId());
 			assertThat(results.get(1).getId()).isIn(bgDocument.getId(), bgDocument2.getId());
 
-			results = vectorStore.similaritySearch(SearchRequest.query("The World")
-				.withTopK(5)
-				.withSimilarityThresholdAll()
-				.withFilterExpression("country in ['BG','NL']"));
+			results = vectorStore.similaritySearch(SearchRequest.builder()
+				.query("The World")
+				.topK(5)
+				.similarityThresholdAll()
+				.filterExpression("country in ['BG','NL']")
+				.build());
 
 			assertThat(results).hasSize(3);
 
-			results = vectorStore.similaritySearch(SearchRequest.query("The World")
-				.withTopK(5)
-				.withSimilarityThresholdAll()
-				.withFilterExpression("country not in ['BG']"));
+			results = vectorStore.similaritySearch(SearchRequest.builder()
+				.query("The World")
+				.topK(5)
+				.similarityThresholdAll()
+				.filterExpression("country not in ['BG']")
+				.build());
 
 			assertThat(results).hasSize(1);
 			assertThat(results.get(0).getId()).isEqualTo(nlDocument.getId());
 
-			results = vectorStore.similaritySearch(SearchRequest.query("The World")
-				.withTopK(5)
-				.withSimilarityThresholdAll()
-				.withFilterExpression("NOT(country not in ['BG'])"));
+			results = vectorStore.similaritySearch(SearchRequest.builder()
+				.query("The World")
+				.topK(5)
+				.similarityThresholdAll()
+				.filterExpression("NOT(country not in ['BG'])")
+				.build());
 
 			assertThat(results).hasSize(2);
 			assertThat(results.get(0).getId()).isIn(bgDocument.getId(), bgDocument2.getId());
@@ -215,7 +232,7 @@ public class AzureVectorStoreIT {
 
 			vectorStore.add(List.of(document));
 
-			SearchRequest springSearchRequest = SearchRequest.query("Spring").withTopK(5);
+			SearchRequest springSearchRequest = SearchRequest.builder().query("Spring").topK(5).build();
 
 			Awaitility.await().until(() -> vectorStore.similaritySearch(springSearchRequest), hasSize(1));
 
@@ -234,7 +251,7 @@ public class AzureVectorStoreIT {
 
 			vectorStore.add(List.of(sameIdDocument));
 
-			SearchRequest fooBarSearchRequest = SearchRequest.query("FooBar").withTopK(5);
+			SearchRequest fooBarSearchRequest = SearchRequest.builder().query("FooBar").topK(5).build();
 
 			Awaitility.await()
 				.until(() -> vectorStore.similaritySearch(fooBarSearchRequest).get(0).getContent(),
@@ -266,12 +283,12 @@ public class AzureVectorStoreIT {
 			vectorStore.add(this.documents);
 
 			Awaitility.await()
-				.until(() -> vectorStore
-					.similaritySearch(SearchRequest.query("Depression").withTopK(50).withSimilarityThresholdAll()),
+				.until(() -> vectorStore.similaritySearch(
+						SearchRequest.builder().query("Depression").topK(50).similarityThresholdAll().build()),
 						hasSize(3));
 
 			List<Document> fullResult = vectorStore
-				.similaritySearch(SearchRequest.query("Depression").withTopK(5).withSimilarityThresholdAll());
+				.similaritySearch(SearchRequest.builder().query("Depression").topK(5).similarityThresholdAll().build());
 
 			List<Double> scores = fullResult.stream().map(Document::getScore).toList();
 
@@ -279,8 +296,11 @@ public class AzureVectorStoreIT {
 
 			double similarityThreshold = (scores.get(0) + scores.get(1)) / 2;
 
-			List<Document> results = vectorStore.similaritySearch(
-					SearchRequest.query("Depression").withTopK(5).withSimilarityThreshold(similarityThreshold));
+			List<Document> results = vectorStore.similaritySearch(SearchRequest.builder()
+				.query("Depression")
+				.topK(5)
+				.similarityThreshold(similarityThreshold)
+				.build());
 
 			assertThat(results).hasSize(1);
 			Document resultDoc = results.get(0);
@@ -293,7 +313,8 @@ public class AzureVectorStoreIT {
 			// Remove all documents from the store
 			vectorStore.delete(this.documents.stream().map(doc -> doc.getId()).toList());
 			Awaitility.await()
-				.until(() -> vectorStore.similaritySearch(SearchRequest.query("Hello").withTopK(1)), hasSize(0));
+				.until(() -> vectorStore.similaritySearch(SearchRequest.builder().query("Hello").topK(1).build()),
+						hasSize(0));
 		});
 	}
 

vector-stores/spring-ai-azure-store/src/test/java/org/springframework/ai/vectorstore/azure/AzureVectorStoreObservationIT.java

@@ -130,7 +130,7 @@ public class AzureVectorStoreObservationIT {
 			observationRegistry.clear();
 
 			List<Document> results = vectorStore
-				.similaritySearch(SearchRequest.query("What is Great Depression").withTopK(1));
+				.similaritySearch(SearchRequest.builder().query("What is Great Depression").topK(1).build());
 
 			assertThat(results).isNotEmpty();
 

vector-stores/spring-ai-cassandra-store/src/test/java/org/springframework/ai/vectorstore/cassandra/CassandraRichSchemaVectorStoreIT.java

@@ -154,7 +154,7 @@ class CassandraRichSchemaVectorStoreIT {
 			try (CassandraVectorStore store = createStore(context, false)) {
 				Assertions.assertNotNull(store);
 				store.checkSchemaValid();
-				store.similaritySearch(SearchRequest.query("1843").withTopK(1));
+				store.similaritySearch(SearchRequest.builder().query("1843").topK(1).build());
 			}
 		});
 	}
@@ -170,7 +170,7 @@ class CassandraRichSchemaVectorStoreIT {
 
 				store.checkSchemaValid();
 
-				store.similaritySearch(SearchRequest.query("1843").withTopK(1));
+				store.similaritySearch(SearchRequest.builder().query("1843").topK(1).build());
 
 				CassandraVectorStore.dropKeyspace(builder);
 				executeCqlFile(context, "test_wiki_partial_3_schema.cql");
@@ -201,7 +201,7 @@ class CassandraRichSchemaVectorStoreIT {
 				try {
 					store.checkSchemaValid();
 
-					store.similaritySearch(SearchRequest.query("1843").withTopK(1));
+					store.similaritySearch(SearchRequest.builder().query("1843").topK(1).build());
 				}
 				finally {
 					CassandraVectorStore.dropKeyspace(builder);
@@ -220,8 +220,8 @@ class CassandraRichSchemaVectorStoreIT {
 			try (CassandraVectorStore store = createStore(context, false)) {
 				store.add(documents);
 
-				List<Document> results = store
-					.similaritySearch(SearchRequest.query("Neptunes gravity makes its atmosphere").withTopK(1));
+				List<Document> results = store.similaritySearch(
+						SearchRequest.builder().query("Neptunes gravity makes its atmosphere").topK(1).build());
 
 				assertThat(results).hasSize(1);
 				Document resultDoc = results.get(0);
@@ -236,7 +236,7 @@ class CassandraRichSchemaVectorStoreIT {
 				// Remove all documents from the createStore
 				store.delete(documents.stream().map(doc -> doc.getId()).toList());
 
-				results = store.similaritySearch(SearchRequest.query("Spring").withTopK(1));
+				results = store.similaritySearch(SearchRequest.builder().query("Spring").topK(1).build());
 				assertThat(results).isEmpty();
 			}
 		});
@@ -272,8 +272,10 @@ class CassandraRichSchemaVectorStoreIT {
 							}
 							store.add(documents);
 
-							var results = store.similaritySearch(
-									SearchRequest.query(RandomStringUtils.randomAlphanumeric(20)).withTopK(10));
+							var results = store.similaritySearch(SearchRequest.builder()
+								.query(RandomStringUtils.randomAlphanumeric(20))
+								.topK(10)
+								.build());
 
 							assertThat(results).hasSize(10);
 						}, executor);
@@ -292,13 +294,16 @@ class CassandraRichSchemaVectorStoreIT {
 			try (CassandraVectorStore store = createStore(context, false)) {
 				store.add(documents);
 
-				List<Document> results = store.similaritySearch(SearchRequest.query("Great Dark Spot").withTopK(5));
+				List<Document> results = store
+					.similaritySearch(SearchRequest.builder().query("Great Dark Spot").topK(5).build());
 				assertThat(results).hasSize(3);
 
-				results = store.similaritySearch(SearchRequest.query(URANUS_ORBIT_QUERY)
-					.withTopK(5)
-					.withSimilarityThresholdAll()
-					.withFilterExpression("wiki == 'simplewiki' && language == 'en' && title == 'Neptune'"));
+				results = store.similaritySearch(SearchRequest.builder()
+					.query(URANUS_ORBIT_QUERY)
+					.topK(5)
+					.similarityThresholdAll()
+					.filterExpression("wiki == 'simplewiki' && language == 'en' && title == 'Neptune'")
+					.build());
 
 				assertThat(results).hasSize(3);
 				assertThat(results.get(0).getId()).isEqualTo(documents.get(1).getId());
@@ -317,21 +322,24 @@ class CassandraRichSchemaVectorStoreIT {
 				// assertThat(results).hasSize(1);
 				// assertThat(results.get(0).getId()).isEqualTo(documents.get(0).getId());
 
-				results = store.similaritySearch(SearchRequest.query("Great Dark Spot")
-					.withTopK(5)
-					.withSimilarityThresholdAll()
-					.withFilterExpression(
-							"wiki == 'simplewiki' && language == 'en' && title == 'Neptune' && id == 558"));
+				results = store.similaritySearch(SearchRequest.builder()
+					.query("Great Dark Spot")
+					.topK(5)
+					.similarityThresholdAll()
+					.filterExpression("wiki == 'simplewiki' && language == 'en' && title == 'Neptune' && id == 558")
+					.build());
 
 				assertThat(results).hasSize(3);
 
 				// cassandra server will throw an error
 				Assertions.assertThrows(SyntaxError.class,
-						() -> store.similaritySearch(SearchRequest.query("Great Dark Spot")
-							.withTopK(5)
-							.withSimilarityThresholdAll()
-							.withFilterExpression(
-									"NOT(wiki == 'simplewiki' && language == 'en' && title == 'Neptune' && id == 1)")));
+						() -> store.similaritySearch(SearchRequest.builder()
+							.query("Great Dark Spot")
+							.topK(5)
+							.similarityThresholdAll()
+							.filterExpression(
+									"NOT(wiki == 'simplewiki' && language == 'en' && title == 'Neptune' && id == 1)")
+							.build()));
 			}
 		});
 	}
@@ -342,14 +350,17 @@ class CassandraRichSchemaVectorStoreIT {
 			try (CassandraVectorStore store = createStore(context, false)) {
 				store.add(documents);
 
-				List<Document> results = store.similaritySearch(SearchRequest.query("Great Dark Spot").withTopK(5));
+				List<Document> results = store
+					.similaritySearch(SearchRequest.builder().query("Great Dark Spot").topK(5).build());
 				assertThat(results).hasSize(3);
 
 				Assertions.assertThrows(InvalidQueryException.class,
-						() -> store.similaritySearch(SearchRequest.query("The World")
-							.withTopK(5)
-							.withSimilarityThresholdAll()
-							.withFilterExpression("revision == 9385813")));
+						() -> store.similaritySearch(SearchRequest.builder()
+							.query("The World")
+							.topK(5)
+							.similarityThresholdAll()
+							.filterExpression("revision == 9385813")
+							.build()));
 			}
 		});
 	}
@@ -360,29 +371,36 @@ class CassandraRichSchemaVectorStoreIT {
 			try (CassandraVectorStore store = createStore(context, false)) {
 				store.add(documents);
 
-				List<Document> results = store.similaritySearch(SearchRequest.query(URANUS_ORBIT_QUERY).withTopK(5));
+				List<Document> results = store
+					.similaritySearch(SearchRequest.builder().query(URANUS_ORBIT_QUERY).topK(5).build());
 				assertThat(results).hasSize(3);
 
-				results = store.similaritySearch(SearchRequest.query(URANUS_ORBIT_QUERY)
-					.withTopK(5)
-					.withSimilarityThresholdAll()
-					.withFilterExpression("id == 558"));
+				results = store.similaritySearch(SearchRequest.builder()
+					.query(URANUS_ORBIT_QUERY)
+					.topK(5)
+					.similarityThresholdAll()
+					.filterExpression("id == 558")
+					.build());
 
 				assertThat(results).hasSize(3);
 				assertThat(results.get(0).getId()).isEqualTo(documents.get(1).getId());
 
-				results = store.similaritySearch(SearchRequest.query(URANUS_ORBIT_QUERY)
-					.withTopK(5)
-					.withSimilarityThresholdAll()
-					.withFilterExpression("id > 557"));
+				results = store.similaritySearch(SearchRequest.builder()
+					.query(URANUS_ORBIT_QUERY)
+					.topK(5)
+					.similarityThresholdAll()
+					.filterExpression("id > 557")
+					.build());
 
 				assertThat(results).hasSize(3);
 				assertThat(results.get(0).getId()).isEqualTo(documents.get(1).getId());
 
-				results = store.similaritySearch(SearchRequest.query(URANUS_ORBIT_QUERY)
-					.withTopK(5)
-					.withSimilarityThresholdAll()
-					.withFilterExpression("id >= 558"));
+				results = store.similaritySearch(SearchRequest.builder()
+					.query(URANUS_ORBIT_QUERY)
+					.topK(5)
+					.similarityThresholdAll()
+					.filterExpression("id >= 558")
+					.build());
 
 				assertThat(results).hasSize(3);
 				assertThat(results.get(0).getId()).isEqualTo(documents.get(1).getId());
@@ -393,25 +411,31 @@ class CassandraRichSchemaVectorStoreIT {
 				// achieve
 				// e.g. searchWithFilterOnPrimaryKeys()
 				Assertions.assertThrows(InvalidQueryException.class,
-						() -> store.similaritySearch(SearchRequest.query(URANUS_ORBIT_QUERY)
-							.withTopK(5)
-							.withSimilarityThresholdAll()
-							.withFilterExpression("id > 557 && \"chunk_no\" == 1")));
+						() -> store.similaritySearch(SearchRequest.builder()
+							.query(URANUS_ORBIT_QUERY)
+							.topK(5)
+							.similarityThresholdAll()
+							.filterExpression("id > 557 && \"chunk_no\" == 1")
+							.build()));
 
 				// cassandra server will throw an error,
 				// as revision is not searchable (i.e. no SAI index on it)
 				Assertions.assertThrows(SyntaxError.class,
-						() -> store.similaritySearch(SearchRequest.query("Great Dark Spot")
-							.withTopK(5)
-							.withSimilarityThresholdAll()
-							.withFilterExpression("id == 558 || revision == 2020")));
+						() -> store.similaritySearch(SearchRequest.builder()
+							.query("Great Dark Spot")
+							.topK(5)
+							.similarityThresholdAll()
+							.filterExpression("id == 558 || revision == 2020")
+							.build()));
 
 				// cassandra java-driver will throw an error
 				Assertions.assertThrows(InvalidQueryException.class,
-						() -> store.similaritySearch(SearchRequest.query("Great Dark Spot")
-							.withTopK(5)
-							.withSimilarityThresholdAll()
-							.withFilterExpression("NOT(id == 557 || revision == 2020)")));
+						() -> store.similaritySearch(SearchRequest.builder()
+							.query("Great Dark Spot")
+							.topK(5)
+							.similarityThresholdAll()
+							.filterExpression("NOT(id == 557 || revision == 2020)")
+							.build()));
 			}
 		});
 	}
@@ -428,13 +452,16 @@ class CassandraRichSchemaVectorStoreIT {
 
 				store.add(documents);
 
-				List<Document> results = store.similaritySearch(SearchRequest.query(URANUS_ORBIT_QUERY).withTopK(5));
+				List<Document> results = store
+					.similaritySearch(SearchRequest.builder().query(URANUS_ORBIT_QUERY).topK(5).build());
 				assertThat(results).hasSize(3);
 
-				store.similaritySearch(SearchRequest.query(URANUS_ORBIT_QUERY)
-					.withTopK(5)
-					.withSimilarityThresholdAll()
-					.withFilterExpression("id > 557 && \"chunk_no\" == 1"));
+				store.similaritySearch(SearchRequest.builder()
+					.query(URANUS_ORBIT_QUERY)
+					.topK(5)
+					.similarityThresholdAll()
+					.filterExpression("id > 557 && \"chunk_no\" == 1")
+					.build());
 
 				assertThat(results).hasSize(3);
 				assertThat(results.get(0).getId()).isEqualTo(documents.get(1).getId());
@@ -458,7 +485,8 @@ class CassandraRichSchemaVectorStoreIT {
 			try (CassandraVectorStore store = createStore(context, false)) {
 				store.add(documents);
 
-				List<Document> results = store.similaritySearch(SearchRequest.query(URANUS_ORBIT_QUERY).withTopK(1));
+				List<Document> results = store
+					.similaritySearch(SearchRequest.builder().query(URANUS_ORBIT_QUERY).topK(1).build());
 
 				assertThat(results).hasSize(1);
 				Document resultDoc = results.get(0);
@@ -490,7 +518,7 @@ class CassandraRichSchemaVectorStoreIT {
 
 				store.delete(List.of(sameIdDocument.getId()));
 
-				results = store.similaritySearch(SearchRequest.query(newContent).withTopK(1));
+				results = store.similaritySearch(SearchRequest.builder().query(newContent).topK(1).build());
 
 				assertThat(results).hasSize(1);
 				resultDoc = results.get(0);
@@ -508,8 +536,8 @@ class CassandraRichSchemaVectorStoreIT {
 			try (CassandraVectorStore store = createStore(context, false)) {
 				store.add(documents);
 
-				List<Document> fullResult = store
-					.similaritySearch(SearchRequest.query(URANUS_ORBIT_QUERY).withTopK(5).withSimilarityThresholdAll());
+				List<Document> fullResult = store.similaritySearch(
+						SearchRequest.builder().query(URANUS_ORBIT_QUERY).topK(5).similarityThresholdAll().build());
 
 				List<Double> scores = fullResult.stream().map(Document::getScore).toList();
 
@@ -517,9 +545,11 @@ class CassandraRichSchemaVectorStoreIT {
 
 				double similarityThreshold = (scores.get(0) + scores.get(1)) / 2;
 
-				List<Document> results = store.similaritySearch(SearchRequest.query(URANUS_ORBIT_QUERY)
-					.withTopK(5)
-					.withSimilarityThreshold(similarityThreshold));
+				List<Document> results = store.similaritySearch(SearchRequest.builder()
+					.query(URANUS_ORBIT_QUERY)
+					.topK(5)
+					.similarityThreshold(similarityThreshold)
+					.build());
 
 				assertThat(results).hasSize(1);
 				Document resultDoc = results.get(0);

vector-stores/spring-ai-cassandra-store/src/test/java/org/springframework/ai/vectorstore/cassandra/CassandraVectorStoreIT.java

@@ -126,7 +126,8 @@ class CassandraVectorStoreIT {
 				List<Document> documents = documents();
 				store.add(documents);
 
-				List<Document> results = store.similaritySearch(SearchRequest.query("Spring").withTopK(1));
+				List<Document> results = store
+					.similaritySearch(SearchRequest.builder().query("Spring").topK(1).build());
 
 				assertThat(results).hasSize(1);
 				Document resultDoc = results.get(0);
@@ -141,7 +142,7 @@ class CassandraVectorStoreIT {
 				// Remove all documents from the store
 				store.delete(documents().stream().map(doc -> doc.getId()).toList());
 
-				results = store.similaritySearch(SearchRequest.query("Spring").withTopK(1));
+				results = store.similaritySearch(SearchRequest.builder().query("Spring").topK(1).build());
 				assertThat(results).isEmpty();
 			}
 		});
@@ -158,7 +159,8 @@ class CassandraVectorStoreIT {
 				List<Document> documents = documents();
 				store.add(documents);
 
-				List<Document> results = store.similaritySearch(SearchRequest.query("Spring").withTopK(1));
+				List<Document> results = store
+					.similaritySearch(SearchRequest.builder().query("Spring").topK(1).build());
 
 				assertThat(results).hasSize(1);
 				Document resultDoc = results.get(0);
@@ -173,7 +175,7 @@ class CassandraVectorStoreIT {
 				// Remove all documents from the store
 				store.delete(documents().stream().map(doc -> doc.getId()).toList());
 
-				results = store.similaritySearch(SearchRequest.query("Spring").withTopK(1));
+				results = store.similaritySearch(SearchRequest.builder().query("Spring").topK(1).build());
 				assertThat(results).isEmpty();
 			}
 		});
@@ -195,42 +197,50 @@ class CassandraVectorStoreIT {
 
 				store.add(List.of(bgDocument, nlDocument, bgDocument2));
 
-				List<Document> results = store.similaritySearch(SearchRequest.query("The World").withTopK(5));
+				List<Document> results = store
+					.similaritySearch(SearchRequest.builder().query("The World").topK(5).build());
 				assertThat(results).hasSize(3);
 
-				results = store.similaritySearch(SearchRequest.query("The World")
-					.withTopK(5)
-					.withSimilarityThresholdAll()
-					.withFilterExpression(java.lang.String.format("%s == 'NL'", CassandraVectorStore.DEFAULT_ID_NAME)));
+				results = store.similaritySearch(SearchRequest.builder()
+					.query("The World")
+					.topK(5)
+					.similarityThresholdAll()
+					.filterExpression(java.lang.String.format("%s == 'NL'", CassandraVectorStore.DEFAULT_ID_NAME))
+					.build());
 
 				assertThat(results).hasSize(1);
 				assertThat(results.get(0).getId()).isEqualTo(nlDocument.getId());
 
-				results = store.similaritySearch(SearchRequest.query("The World")
-					.withTopK(5)
-					.withSimilarityThresholdAll()
-					.withFilterExpression(
-							java.lang.String.format("%s == 'BG2'", CassandraVectorStore.DEFAULT_ID_NAME)));
+				results = store.similaritySearch(SearchRequest.builder()
+					.query("The World")
+					.topK(5)
+					.similarityThresholdAll()
+					.filterExpression(java.lang.String.format("%s == 'BG2'", CassandraVectorStore.DEFAULT_ID_NAME))
+					.build());
 
 				assertThat(results).hasSize(1);
 				assertThat(results.get(0).getId()).isEqualTo(bgDocument2.getId());
 
-				results = store.similaritySearch(SearchRequest.query("The World")
-					.withTopK(5)
-					.withSimilarityThresholdAll()
-					.withFilterExpression(java.lang.String.format("%s == 'BG' && year == 2020",
-							CassandraVectorStore.DEFAULT_ID_NAME)));
+				results = store.similaritySearch(SearchRequest.builder()
+					.query("The World")
+					.topK(5)
+					.similarityThresholdAll()
+					.filterExpression(
+							java.lang.String.format("%s == 'BG' && year == 2020", CassandraVectorStore.DEFAULT_ID_NAME))
+					.build());
 
 				assertThat(results).hasSize(1);
 				assertThat(results.get(0).getId()).isEqualTo(bgDocument.getId());
 
 				// cassandra server will throw an error
 				Assertions.assertThrows(SyntaxError.class,
-						() -> store.similaritySearch(SearchRequest.query("The World")
-							.withTopK(5)
-							.withSimilarityThresholdAll()
-							.withFilterExpression(java.lang.String.format("NOT(%s == 'BG' && year == 2020)",
-									CassandraVectorStore.DEFAULT_ID_NAME))));
+						() -> store.similaritySearch(SearchRequest.builder()
+							.query("The World")
+							.topK(5)
+							.similarityThresholdAll()
+							.filterExpression(java.lang.String.format("NOT(%s == 'BG' && year == 2020)",
+									CassandraVectorStore.DEFAULT_ID_NAME))
+							.build()));
 			}
 		});
 	}
@@ -249,14 +259,17 @@ class CassandraVectorStoreIT {
 
 				store.add(List.of(bgDocument, nlDocument, bgDocument2));
 
-				List<Document> results = store.similaritySearch(SearchRequest.query("The World").withTopK(5));
+				List<Document> results = store
+					.similaritySearch(SearchRequest.builder().query("The World").topK(5).build());
 				assertThat(results).hasSize(3);
 
 				Assertions.assertThrows(InvalidQueryException.class,
-						() -> store.similaritySearch(SearchRequest.query("The World")
-							.withTopK(5)
-							.withSimilarityThresholdAll()
-							.withFilterExpression("country == 'NL'")));
+						() -> store.similaritySearch(SearchRequest.builder()
+							.query("The World")
+							.topK(5)
+							.similarityThresholdAll()
+							.filterExpression("country == 'NL'")
+							.build()));
 			}
 		});
 	}
@@ -278,46 +291,57 @@ class CassandraVectorStoreIT {
 
 				store.add(List.of(bgDocument, nlDocument, bgDocument2));
 
-				List<Document> results = store.similaritySearch(SearchRequest.query("The World").withTopK(5));
+				List<Document> results = store
+					.similaritySearch(SearchRequest.builder().query("The World").topK(5).build());
 				assertThat(results).hasSize(3);
 
-				results = store.similaritySearch(SearchRequest.query("The World")
-					.withTopK(5)
-					.withSimilarityThresholdAll()
-					.withFilterExpression("country == 'NL'"));
+				results = store.similaritySearch(SearchRequest.builder()
+					.query("The World")
+					.topK(5)
+					.similarityThresholdAll()
+					.filterExpression("country == 'NL'")
+					.build());
 				assertThat(results).hasSize(1);
 				assertThat(results.get(0).getId()).isEqualTo(nlDocument.getId());
 
-				results = store.similaritySearch(SearchRequest.query("The World")
-					.withTopK(5)
-					.withSimilarityThresholdAll()
-					.withFilterExpression("country == 'BG'"));
+				results = store.similaritySearch(SearchRequest.builder()
+					.query("The World")
+					.topK(5)
+					.similarityThresholdAll()
+					.filterExpression("country == 'BG'")
+					.build());
 
 				assertThat(results).hasSize(2);
 				assertThat(results.get(0).getId()).isIn(bgDocument.getId(), bgDocument2.getId());
 				assertThat(results.get(1).getId()).isIn(bgDocument.getId(), bgDocument2.getId());
 
-				results = store.similaritySearch(SearchRequest.query("The World")
-					.withTopK(5)
-					.withSimilarityThresholdAll()
-					.withFilterExpression("country == 'BG' && year == 2020"));
+				results = store.similaritySearch(SearchRequest.builder()
+					.query("The World")
+					.topK(5)
+					.similarityThresholdAll()
+					.filterExpression("country == 'BG' && year == 2020")
+					.build());
 
 				assertThat(results).hasSize(1);
 				assertThat(results.get(0).getId()).isEqualTo(bgDocument.getId());
 
 				// cassandra server will throw an error
 				Assertions.assertThrows(SyntaxError.class,
-						() -> store.similaritySearch(SearchRequest.query("The World")
-							.withTopK(5)
-							.withSimilarityThresholdAll()
-							.withFilterExpression("country == 'BG' || year == 2020")));
+						() -> store.similaritySearch(SearchRequest.builder()
+							.query("The World")
+							.topK(5)
+							.similarityThresholdAll()
+							.filterExpression("country == 'BG' || year == 2020")
+							.build()));
 
 				// cassandra server will throw an error
 				Assertions.assertThrows(SyntaxError.class,
-						() -> store.similaritySearch(SearchRequest.query("The World")
-							.withTopK(5)
-							.withSimilarityThresholdAll()
-							.withFilterExpression("NOT(country == 'BG' && year == 2020)")));
+						() -> store.similaritySearch(SearchRequest.builder()
+							.query("The World")
+							.topK(5)
+							.similarityThresholdAll()
+							.filterExpression("NOT(country == 'BG' && year == 2020)")
+							.build()));
 			}
 		});
 	}
@@ -332,7 +356,8 @@ class CassandraVectorStoreIT {
 
 				store.add(List.of(document));
 
-				List<Document> results = store.similaritySearch(SearchRequest.query("Spring").withTopK(5));
+				List<Document> results = store
+					.similaritySearch(SearchRequest.builder().query("Spring").topK(5).build());
 
 				assertThat(results).hasSize(1);
 				Document resultDoc = results.get(0);
@@ -346,7 +371,7 @@ class CassandraVectorStoreIT {
 
 				store.add(List.of(sameIdDocument));
 
-				results = store.similaritySearch(SearchRequest.query("FooBar").withTopK(5));
+				results = store.similaritySearch(SearchRequest.builder().query("FooBar").topK(5).build());
 
 				assertThat(results).hasSize(1);
 				resultDoc = results.get(0);
@@ -366,7 +391,7 @@ class CassandraVectorStoreIT {
 				store.add(documents());
 
 				List<Document> fullResult = store
-					.similaritySearch(SearchRequest.query("Spring").withTopK(5).withSimilarityThresholdAll());
+					.similaritySearch(SearchRequest.builder().query("Spring").topK(5).similarityThresholdAll().build());
 
 				List<Double> scores = fullResult.stream().map(Document::getScore).toList();
 
@@ -374,8 +399,11 @@ class CassandraVectorStoreIT {
 
 				double similarityThreshold = (scores.get(0) + scores.get(1)) / 2;
 
-				List<Document> results = store.similaritySearch(
-						SearchRequest.query("Spring").withTopK(5).withSimilarityThreshold(similarityThreshold));
+				List<Document> results = store.similaritySearch(SearchRequest.builder()
+					.query("Spring")
+					.topK(5)
+					.similarityThreshold(similarityThreshold)
+					.build());
 
 				assertThat(results).hasSize(1);
 				Document resultDoc = results.get(0);

vector-stores/spring-ai-cassandra-store/src/test/java/org/springframework/ai/vectorstore/cassandra/CassandraVectorStoreObservationIT.java

@@ -120,7 +120,7 @@ public class CassandraVectorStoreObservationIT {
 			observationRegistry.clear();
 
 			List<Document> results = vectorStore
-				.similaritySearch(SearchRequest.query("What is Great Depression").withTopK(1));
+				.similaritySearch(SearchRequest.builder().query("What is Great Depression").topK(1).build());
 
 			assertThat(results).isNotEmpty();
 

vector-stores/spring-ai-cassandra-store/src/test/java/org/springframework/ai/vectorstore/cassandra/WikiVectorStoreExample.java

@@ -61,7 +61,7 @@ class WikiVectorStoreExample {
 			Assertions.assertNotNull(store);
 			store.checkSchemaValid();
 
-			store.similaritySearch(SearchRequest.query("Spring").withTopK(1));
+			store.similaritySearch(SearchRequest.builder().query("Spring").topK(1).build());
 		});
 	}
 
@@ -72,7 +72,7 @@ class WikiVectorStoreExample {
 			Assertions.assertNotNull(store);
 			store.checkSchemaValid();
 
-			var results = store.similaritySearch(SearchRequest.query("Spring").withTopK(1));
+			var results = store.similaritySearch(SearchRequest.builder().query("Spring").topK(1).build());
 			assertThat(results).hasSize(1);
 		});
 	}

vector-stores/spring-ai-chroma-store/src/test/java/org/springframework/ai/chroma/vectorstore/BasicAuthChromaWhereIT.java

@@ -83,13 +83,15 @@ public class BasicAuthChromaWhereIT {
 
 			String query = "Give me articles by john";
 
-			List<Document> results = vectorStore.similaritySearch(SearchRequest.query(query).withTopK(5));
+			List<Document> results = vectorStore.similaritySearch(SearchRequest.builder().query(query).topK(5).build());
 			assertThat(results).hasSize(3);
 
-			results = vectorStore.similaritySearch(SearchRequest.query(query)
-				.withTopK(5)
-				.withSimilarityThresholdAll()
-				.withFilterExpression("author in ['john', 'jill']"));
+			results = vectorStore.similaritySearch(SearchRequest.builder()
+				.query(query)
+				.topK(5)
+				.similarityThresholdAll()
+				.filterExpression("author in ['john', 'jill']")
+				.build());
 
 			assertThat(results).hasSize(2);
 			assertThat(results.stream().map(d -> d.getId()).toList()).containsExactlyInAnyOrder("1", "3");

vector-stores/spring-ai-chroma-store/src/test/java/org/springframework/ai/chroma/vectorstore/ChromaVectorStoreIT.java

@@ -24,13 +24,13 @@ import java.util.UUID;
 
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.condition.EnabledIfEnvironmentVariable;
-import org.springframework.ai.document.DocumentMetadata;
 import org.testcontainers.chromadb.ChromaDBContainer;
 import org.testcontainers.junit.jupiter.Container;
 import org.testcontainers.junit.jupiter.Testcontainers;
 
 import org.springframework.ai.chroma.ChromaImage;
 import org.springframework.ai.document.Document;
+import org.springframework.ai.document.DocumentMetadata;
 import org.springframework.ai.embedding.EmbeddingModel;
 import org.springframework.ai.openai.OpenAiEmbeddingModel;
 import org.springframework.ai.openai.api.OpenAiApi;
@@ -76,7 +76,8 @@ public class ChromaVectorStoreIT {
 
 			vectorStore.add(this.documents);
 
-			List<Document> results = vectorStore.similaritySearch(SearchRequest.query("Great").withTopK(1));
+			List<Document> results = vectorStore
+				.similaritySearch(SearchRequest.builder().query("Great").topK(1).build());
 
 			assertThat(results).hasSize(1);
 			Document resultDoc = results.get(0);
@@ -89,7 +90,8 @@ public class ChromaVectorStoreIT {
 			assertThat(vectorStore.delete(this.documents.stream().map(doc -> doc.getId()).toList()))
 				.isEqualTo(Optional.of(Boolean.TRUE));
 
-			List<Document> results2 = vectorStore.similaritySearch(SearchRequest.query("Great").withTopK(1));
+			List<Document> results2 = vectorStore
+				.similaritySearch(SearchRequest.builder().query("Great").topK(1).build());
 			assertThat(results2).hasSize(0);
 		});
 	}
@@ -117,7 +119,7 @@ public class ChromaVectorStoreIT {
 			// Remove all documents from the store
 			assertThat(vectorStore.delete(List.of(document.getId()))).isEqualTo(Optional.of(Boolean.TRUE));
 
-			results = vectorStore.similaritySearch(SearchRequest.query("Why is the sky blue?"));
+			results = vectorStore.similaritySearch(SearchRequest.builder().query("Why is the sky blue?").build());
 			assertThat(results).hasSize(0);
 		});
 	}
@@ -136,23 +138,29 @@ public class ChromaVectorStoreIT {
 
 			vectorStore.add(List.of(bgDocument, nlDocument));
 
-			var request = SearchRequest.query("The World").withTopK(5);
+			var request = SearchRequest.builder().query("The World").topK(5).build();
 
 			List<Document> results = vectorStore.similaritySearch(request);
 			assertThat(results).hasSize(2);
 
-			results = vectorStore
-				.similaritySearch(request.withSimilarityThresholdAll().withFilterExpression("country == 'Bulgaria'"));
+			results = vectorStore.similaritySearch(SearchRequest.from(request)
+				.similarityThresholdAll()
+				.filterExpression("country == 'Bulgaria'")
+				.build());
 			assertThat(results).hasSize(1);
 			assertThat(results.get(0).getId()).isEqualTo(bgDocument.getId());
 
-			results = vectorStore.similaritySearch(
-					request.withSimilarityThresholdAll().withFilterExpression("country == 'Netherlands'"));
+			results = vectorStore.similaritySearch(SearchRequest.from(request)
+				.similarityThresholdAll()
+				.filterExpression("country == 'Netherlands'")
+				.build());
 			assertThat(results).hasSize(1);
 			assertThat(results.get(0).getId()).isEqualTo(nlDocument.getId());
 
-			results = vectorStore.similaritySearch(
-					request.withSimilarityThresholdAll().withFilterExpression("NOT(country == 'Netherlands')"));
+			results = vectorStore.similaritySearch(SearchRequest.from(request)
+				.similarityThresholdAll()
+				.filterExpression("NOT(country == 'Netherlands')")
+				.build());
 			assertThat(results).hasSize(1);
 			assertThat(results.get(0).getId()).isEqualTo(bgDocument.getId());
 
@@ -174,7 +182,8 @@ public class ChromaVectorStoreIT {
 
 			vectorStore.add(List.of(document));
 
-			List<Document> results = vectorStore.similaritySearch(SearchRequest.query("Spring").withTopK(5));
+			List<Document> results = vectorStore
+				.similaritySearch(SearchRequest.builder().query("Spring").topK(5).build());
 
 			assertThat(results).hasSize(1);
 			Document resultDoc = results.get(0);
@@ -189,7 +198,7 @@ public class ChromaVectorStoreIT {
 
 			vectorStore.add(List.of(sameIdDocument));
 
-			results = vectorStore.similaritySearch(SearchRequest.query("FooBar").withTopK(5));
+			results = vectorStore.similaritySearch(SearchRequest.builder().query("FooBar").topK(5).build());
 
 			assertThat(results).hasSize(1);
 			resultDoc = results.get(0);
@@ -212,8 +221,9 @@ public class ChromaVectorStoreIT {
 
 			vectorStore.add(this.documents);
 
-			var request = SearchRequest.query("Great").withTopK(5);
-			List<Document> fullResult = vectorStore.similaritySearch(request.withSimilarityThresholdAll());
+			var request = SearchRequest.builder().query("Great").topK(5).build();
+			List<Document> fullResult = vectorStore
+				.similaritySearch(SearchRequest.from(request).similarityThresholdAll().build());
 
 			List<Double> scores = fullResult.stream().map(Document::getScore).toList();
 
@@ -221,7 +231,8 @@ public class ChromaVectorStoreIT {
 
 			double similarityThreshold = (scores.get(0) + scores.get(1)) / 2;
 
-			List<Document> results = vectorStore.similaritySearch(request.withSimilarityThreshold(similarityThreshold));
+			List<Document> results = vectorStore
+				.similaritySearch(SearchRequest.from(request).similarityThreshold(similarityThreshold).build());
 
 			assertThat(results).hasSize(1);
 			Document resultDoc = results.get(0);

vector-stores/spring-ai-chroma-store/src/test/java/org/springframework/ai/chroma/vectorstore/ChromaVectorStoreObservationIT.java

@@ -121,7 +121,7 @@ public class ChromaVectorStoreObservationIT {
 			observationRegistry.clear();
 
 			List<Document> results = vectorStore
-				.similaritySearch(SearchRequest.query("What is Great Depression").withTopK(1));
+				.similaritySearch(SearchRequest.builder().query("What is Great Depression").topK(1).build());
 
 			assertThat(results).isNotEmpty();
 

vector-stores/spring-ai-chroma-store/src/test/java/org/springframework/ai/chroma/vectorstore/TokenSecuredChromaWhereIT.java

@@ -82,13 +82,15 @@ public class TokenSecuredChromaWhereIT {
 					new Document("2", "Article by Jack", Map.of("author", "jack")),
 					new Document("3", "Article by Jill", Map.of("author", "jill"))));
 
-			var request = SearchRequest.query("Give me articles by john").withTopK(5);
+			var request = SearchRequest.builder().query("Give me articles by john").topK(5).build();
 
 			List<Document> results = vectorStore.similaritySearch(request);
 			assertThat(results).hasSize(3);
 
-			results = vectorStore.similaritySearch(
-					request.withSimilarityThresholdAll().withFilterExpression("author in ['john', 'jill']"));
+			results = vectorStore.similaritySearch(SearchRequest.from(request)
+				.similarityThresholdAll()
+				.filterExpression("author in ['john', 'jill']")
+				.build());
 
 			assertThat(results).hasSize(2);
 			assertThat(results.stream().map(d -> d.getId()).toList()).containsExactlyInAnyOrder("1", "3");
@@ -107,19 +109,23 @@ public class TokenSecuredChromaWhereIT {
 						new Document("2", "Article by Jack", Map.of("author", "jack", "article_type", "social")),
 						new Document("3", "Article by Jill", Map.of("author", "jill", "article_type", "paper"))));
 
-			var request = SearchRequest.query("Give me articles by john").withTopK(5);
+			var request = SearchRequest.builder().query("Give me articles by john").topK(5).build();
 
 			List<Document> results = vectorStore.similaritySearch(request);
 			assertThat(results).hasSize(3);
 
-			results = vectorStore.similaritySearch(request.withSimilarityThresholdAll()
-				.withFilterExpression("author in ['john', 'jill'] && 'article_type' == 'blog'"));
+			results = vectorStore.similaritySearch(SearchRequest.from(request)
+				.similarityThresholdAll()
+				.filterExpression("author in ['john', 'jill'] && 'article_type' == 'blog'")
+				.build());
 
 			assertThat(results).hasSize(1);
 			assertThat(results.get(0).getId()).isEqualTo("1");
 
-			results = vectorStore.similaritySearch(request.withSimilarityThresholdAll()
-				.withFilterExpression("author in ['john'] || 'article_type' == 'paper'"));
+			results = vectorStore.similaritySearch(SearchRequest.from(request)
+				.similarityThresholdAll()
+				.filterExpression("author in ['john'] || 'article_type' == 'paper'")
+				.build());
 
 			assertThat(results).hasSize(2);
 

vector-stores/spring-ai-coherence-store/src/test/java/org/springframework/ai/vectorstore/coherence/CoherenceVectorStoreIT.java

@@ -123,7 +123,7 @@ public class CoherenceVectorStoreIT {
 				vectorStore.add(this.documents);
 
 				List<Document> results = vectorStore
-					.similaritySearch(SearchRequest.query("What is Great Depression").withTopK(1));
+					.similaritySearch(SearchRequest.builder().query("What is Great Depression").topK(1).build());
 
 				assertThat(results).hasSize(1);
 				Document resultDoc = results.get(0);
@@ -134,7 +134,7 @@ public class CoherenceVectorStoreIT {
 				vectorStore.delete(this.documents.stream().map(doc -> doc.getId()).toList());
 
 				List<Document> results2 = vectorStore
-					.similaritySearch(SearchRequest.query("Great Depression").withTopK(1));
+					.similaritySearch(SearchRequest.builder().query("Great Depression").topK(1).build());
 				assertThat(results2).hasSize(0);
 
 				truncateMap(context, ((CoherenceVectorStore) vectorStore).getMapName());
@@ -160,44 +160,53 @@ public class CoherenceVectorStoreIT {
 
 				vectorStore.add(List.of(bgDocument, nlDocument, bgDocument2));
 
-				SearchRequest searchRequest = SearchRequest.query("The World").withTopK(5).withSimilarityThresholdAll();
+				SearchRequest searchRequest = SearchRequest.builder()
+					.query("The World")
+					.topK(5)
+					.similarityThresholdAll()
+					.build();
 
 				List<Document> results = vectorStore.similaritySearch(searchRequest);
 
 				assertThat(results).hasSize(3);
 
-				results = vectorStore.similaritySearch(searchRequest.withFilterExpression("country == 'NL'"));
+				results = vectorStore
+					.similaritySearch(SearchRequest.from(searchRequest).filterExpression("country == 'NL'").build());
 
 				assertThat(results).hasSize(1);
 				assertThat(results.get(0).getId()).isEqualTo(nlDocument.getId());
 
-				results = vectorStore.similaritySearch(searchRequest.withFilterExpression("country == 'BG'"));
+				results = vectorStore
+					.similaritySearch(SearchRequest.from(searchRequest).filterExpression("country == 'BG'").build());
 
 				assertThat(results).hasSize(2);
 				assertThat(results.get(0).getId()).isIn(bgDocument.getId(), bgDocument2.getId());
 				assertThat(results.get(1).getId()).isIn(bgDocument.getId(), bgDocument2.getId());
 
-				results = vectorStore
-					.similaritySearch(searchRequest.withFilterExpression("country == 'BG' && year == 2020"));
+				results = vectorStore.similaritySearch(
+						SearchRequest.from(searchRequest).filterExpression("country == 'BG' && year == 2020").build());
 
 				assertThat(results).hasSize(1);
 				assertThat(results.get(0).getId()).isEqualTo(bgDocument.getId());
 
-				results = vectorStore.similaritySearch(
-						searchRequest.withFilterExpression("(country == 'BG' && year == 2020) || (country == 'NL')"));
+				results = vectorStore.similaritySearch(SearchRequest.from(searchRequest)
+					.filterExpression("(country == 'BG' && year == 2020) || (country == 'NL')")
+					.build());
 
 				assertThat(results).hasSize(2);
 				assertThat(results.get(0).getId()).isIn(bgDocument.getId(), nlDocument.getId());
 				assertThat(results.get(1).getId()).isIn(bgDocument.getId(), nlDocument.getId());
 
-				results = vectorStore.similaritySearch(searchRequest
-					.withFilterExpression("NOT((country == 'BG' && year == 2020) || (country == 'NL'))"));
+				results = vectorStore.similaritySearch(SearchRequest.from(searchRequest)
+					.filterExpression("NOT((country == 'BG' && year == 2020) || (country == 'NL'))")
+					.build());
 
 				assertThat(results).hasSize(1);
 				assertThat(results.get(0).getId()).isEqualTo(bgDocument2.getId());
 
 				try {
-					vectorStore.similaritySearch(searchRequest.withFilterExpression("country == NL"));
+					vectorStore
+						.similaritySearch(SearchRequest.from(searchRequest).filterExpression("country == NL").build());
 					Assert.fail("Invalid filter expression should have been cached!");
 				}
 				catch (FilterExpressionTextParser.FilterExpressionParseException e) {
@@ -219,7 +228,8 @@ public class CoherenceVectorStoreIT {
 
 			vectorStore.add(List.of(document));
 
-			List<Document> results = vectorStore.similaritySearch(SearchRequest.query("Spring").withTopK(5));
+			List<Document> results = vectorStore
+				.similaritySearch(SearchRequest.builder().query("Spring").topK(5).build());
 
 			assertThat(results).hasSize(1);
 			Document resultDoc = results.get(0);
@@ -234,7 +244,7 @@ public class CoherenceVectorStoreIT {
 
 			vectorStore.add(List.of(sameIdDocument));
 
-			results = vectorStore.similaritySearch(SearchRequest.query("FooBar").withTopK(5));
+			results = vectorStore.similaritySearch(SearchRequest.builder().query("FooBar").topK(5).build());
 			assertThat(results).hasSize(1);
 			resultDoc = results.get(0);
 			assertThat(resultDoc.getId()).isEqualTo(document.getId());
@@ -253,8 +263,8 @@ public class CoherenceVectorStoreIT {
 
 			vectorStore.add(this.documents);
 
-			List<Document> fullResult = vectorStore
-				.similaritySearch(SearchRequest.query("Time Shelter").withTopK(5).withSimilarityThresholdAll());
+			List<Document> fullResult = vectorStore.similaritySearch(
+					SearchRequest.builder().query("Time Shelter").topK(5).similarityThresholdAll().build());
 
 			assertThat(fullResult).hasSize(3);
 
@@ -264,8 +274,11 @@ public class CoherenceVectorStoreIT {
 
 			double similarityThreshold = (scores.get(0) + scores.get(1)) / 2;
 
-			List<Document> results = vectorStore.similaritySearch(
-					SearchRequest.query("Time Shelter").withTopK(5).withSimilarityThreshold(similarityThreshold));
+			List<Document> results = vectorStore.similaritySearch(SearchRequest.builder()
+				.query("Time Shelter")
+				.topK(5)
+				.similarityThreshold(similarityThreshold)
+				.build());
 
 			assertThat(results).hasSize(1);
 			Document resultDoc = results.get(0);

vector-stores/spring-ai-elasticsearch-store/src/test/java/org/springframework/ai/vectorstore/elasticsearch/ElasticsearchVectorStoreIT.java

@@ -154,12 +154,12 @@ class ElasticsearchVectorStoreIT {
 			vectorStore.add(this.documents);
 
 			Awaitility.await()
-				.until(() -> vectorStore
-					.similaritySearch(SearchRequest.query("Great Depression").withTopK(1).withSimilarityThresholdAll()),
+				.until(() -> vectorStore.similaritySearch(
+						SearchRequest.builder().query("Great Depression").topK(1).similarityThresholdAll().build()),
 						hasSize(1));
 
-			List<Document> results = vectorStore
-				.similaritySearch(SearchRequest.query("Great Depression").withTopK(1).withSimilarityThresholdAll());
+			List<Document> results = vectorStore.similaritySearch(
+					SearchRequest.builder().query("Great Depression").topK(1).similarityThresholdAll().build());
 
 			assertThat(results).hasSize(1);
 			Document resultDoc = results.get(0);
@@ -173,8 +173,8 @@ class ElasticsearchVectorStoreIT {
 			vectorStore.delete(this.documents.stream().map(Document::getId).toList());
 
 			Awaitility.await()
-				.until(() -> vectorStore
-					.similaritySearch(SearchRequest.query("Great Depression").withTopK(1).withSimilarityThresholdAll()),
+				.until(() -> vectorStore.similaritySearch(
+						SearchRequest.builder().query("Great Depression").topK(1).similarityThresholdAll().build()),
 						hasSize(0));
 		});
 	}
@@ -197,73 +197,89 @@ class ElasticsearchVectorStoreIT {
 			vectorStore.add(List.of(bgDocument, nlDocument, bgDocument2));
 
 			Awaitility.await()
-				.until(() -> vectorStore
-					.similaritySearch(SearchRequest.query("The World").withTopK(5).withSimilarityThresholdAll()),
+				.until(() -> vectorStore.similaritySearch(
+						SearchRequest.builder().query("The World").topK(5).similarityThresholdAll().build()),
 						hasSize(3));
 
-			List<Document> results = vectorStore.similaritySearch(SearchRequest.query("The World")
-				.withTopK(5)
-				.withSimilarityThresholdAll()
-				.withFilterExpression("country == 'NL'"));
+			List<Document> results = vectorStore.similaritySearch(SearchRequest.builder()
+				.query("The World")
+				.topK(5)
+				.similarityThresholdAll()
+				.filterExpression("country == 'NL'")
+				.build());
 
 			assertThat(results).hasSize(1);
 			assertThat(results.get(0).getId()).isEqualTo(nlDocument.getId());
 
-			results = vectorStore.similaritySearch(SearchRequest.query("The World")
-				.withTopK(5)
-				.withSimilarityThresholdAll()
-				.withFilterExpression("country == 'BG'"));
+			results = vectorStore.similaritySearch(SearchRequest.builder()
+				.query("The World")
+				.topK(5)
+				.similarityThresholdAll()
+				.filterExpression("country == 'BG'")
+				.build());
 
 			assertThat(results).hasSize(2);
 			assertThat(results.get(0).getId()).isIn(bgDocument.getId(), bgDocument2.getId());
 			assertThat(results.get(1).getId()).isIn(bgDocument.getId(), bgDocument2.getId());
 
-			results = vectorStore.similaritySearch(SearchRequest.query("The World")
-				.withTopK(5)
-				.withSimilarityThresholdAll()
-				.withFilterExpression("country == 'BG' && year == 2020"));
+			results = vectorStore.similaritySearch(SearchRequest.builder()
+				.query("The World")
+				.topK(5)
+				.similarityThresholdAll()
+				.filterExpression("country == 'BG' && year == 2020")
+				.build());
 
 			assertThat(results).hasSize(1);
 			assertThat(results.get(0).getId()).isEqualTo(bgDocument.getId());
 
-			results = vectorStore.similaritySearch(SearchRequest.query("The World")
-				.withTopK(5)
-				.withSimilarityThresholdAll()
-				.withFilterExpression("country in ['BG']"));
+			results = vectorStore.similaritySearch(SearchRequest.builder()
+				.query("The World")
+				.topK(5)
+				.similarityThresholdAll()
+				.filterExpression("country in ['BG']")
+				.build());
 
 			assertThat(results).hasSize(2);
 			assertThat(results.get(0).getId()).isIn(bgDocument.getId(), bgDocument2.getId());
 			assertThat(results.get(1).getId()).isIn(bgDocument.getId(), bgDocument2.getId());
 
-			results = vectorStore.similaritySearch(SearchRequest.query("The World")
-				.withTopK(5)
-				.withSimilarityThresholdAll()
-				.withFilterExpression("country in ['BG','NL']"));
+			results = vectorStore.similaritySearch(SearchRequest.builder()
+				.query("The World")
+				.topK(5)
+				.similarityThresholdAll()
+				.filterExpression("country in ['BG','NL']")
+				.build());
 
 			assertThat(results).hasSize(3);
 
-			results = vectorStore.similaritySearch(SearchRequest.query("The World")
-				.withTopK(5)
-				.withSimilarityThresholdAll()
-				.withFilterExpression("country not in ['BG']"));
+			results = vectorStore.similaritySearch(SearchRequest.builder()
+				.query("The World")
+				.topK(5)
+				.similarityThresholdAll()
+				.filterExpression("country not in ['BG']")
+				.build());
 
 			assertThat(results).hasSize(1);
 			assertThat(results.get(0).getId()).isEqualTo(nlDocument.getId());
 
-			results = vectorStore.similaritySearch(SearchRequest.query("The World")
-				.withTopK(5)
-				.withSimilarityThresholdAll()
-				.withFilterExpression("NOT(country not in ['BG'])"));
+			results = vectorStore.similaritySearch(SearchRequest.builder()
+				.query("The World")
+				.topK(5)
+				.similarityThresholdAll()
+				.filterExpression("NOT(country not in ['BG'])")
+				.build());
 
 			assertThat(results).hasSize(2);
 			assertThat(results.get(0).getId()).isIn(bgDocument.getId(), bgDocument2.getId());
 			assertThat(results.get(1).getId()).isIn(bgDocument.getId(), bgDocument2.getId());
 
-			results = vectorStore.similaritySearch(SearchRequest.query("The World")
-				.withTopK(5)
-				.withSimilarityThresholdAll()
-				.withFilterExpression(
-						"activationDate > " + ZonedDateTime.parse("1970-01-01T00:00:02Z").toInstant().toEpochMilli()));
+			results = vectorStore.similaritySearch(SearchRequest.builder()
+				.query("The World")
+				.topK(5)
+				.similarityThresholdAll()
+				.filterExpression(
+						"activationDate > " + ZonedDateTime.parse("1970-01-01T00:00:02Z").toInstant().toEpochMilli())
+				.build());
 
 			assertThat(results).hasSize(1);
 			assertThat(results.get(0).getId()).isEqualTo(bgDocument2.getId());
@@ -272,7 +288,8 @@ class ElasticsearchVectorStoreIT {
 			vectorStore.delete(this.documents.stream().map(Document::getId).toList());
 
 			Awaitility.await()
-				.until(() -> vectorStore.similaritySearch(SearchRequest.query("The World").withTopK(1)), hasSize(0));
+				.until(() -> vectorStore.similaritySearch(SearchRequest.builder().query("The World").topK(1).build()),
+						hasSize(0));
 		});
 	}
 
@@ -290,11 +307,11 @@ class ElasticsearchVectorStoreIT {
 
 			Awaitility.await()
 				.until(() -> vectorStore
-					.similaritySearch(SearchRequest.query("Spring").withSimilarityThresholdAll().withTopK(5)),
+					.similaritySearch(SearchRequest.builder().query("Spring").similarityThresholdAll().topK(5).build()),
 						hasSize(1));
 
 			List<Document> results = vectorStore
-				.similaritySearch(SearchRequest.query("Spring").withSimilarityThresholdAll().withTopK(5));
+				.similaritySearch(SearchRequest.builder().query("Spring").similarityThresholdAll().topK(5).build());
 
 			assertThat(results).hasSize(1);
 			Document resultDoc = results.get(0);
@@ -307,7 +324,11 @@ class ElasticsearchVectorStoreIT {
 					"The World is Big and Salvation Lurks Around the Corner", Map.of("meta2", "meta2"));
 
 			vectorStore.add(List.of(sameIdDocument));
-			SearchRequest fooBarSearchRequest = SearchRequest.query("FooBar").withTopK(5).withSimilarityThresholdAll();
+			SearchRequest fooBarSearchRequest = SearchRequest.builder()
+				.query("FooBar")
+				.topK(5)
+				.similarityThresholdAll()
+				.build();
 
 			Awaitility.await()
 				.until(() -> vectorStore.similaritySearch(fooBarSearchRequest).get(0).getContent(),
@@ -339,7 +360,11 @@ class ElasticsearchVectorStoreIT {
 
 			vectorStore.add(this.documents);
 
-			SearchRequest query = SearchRequest.query("Great Depression").withTopK(50).withSimilarityThresholdAll();
+			SearchRequest query = SearchRequest.builder()
+				.query("Great Depression")
+				.topK(50)
+				.similarityThresholdAll()
+				.build();
 
 			Awaitility.await().until(() -> vectorStore.similaritySearch(query), hasSize(3));
 
@@ -351,8 +376,11 @@ class ElasticsearchVectorStoreIT {
 
 			double similarityThreshold = (scores.get(0) + scores.get(1)) / 2;
 
-			List<Document> results = vectorStore.similaritySearch(
-					SearchRequest.query("Great Depression").withTopK(50).withSimilarityThreshold(similarityThreshold));
+			List<Document> results = vectorStore.similaritySearch(SearchRequest.builder()
+				.query("Great Depression")
+				.topK(50)
+				.similarityThreshold(similarityThreshold)
+				.build());
 
 			assertThat(results).hasSize(1);
 			Document resultDoc = results.get(0);
@@ -367,7 +395,8 @@ class ElasticsearchVectorStoreIT {
 
 			Awaitility.await()
 				.until(() -> vectorStore.similaritySearch(
-						SearchRequest.query("Great Depression").withTopK(50).withSimilarityThresholdAll()), hasSize(0));
+						SearchRequest.builder().query("Great Depression").topK(50).similarityThresholdAll().build()),
+						hasSize(0));
 		});
 	}
 

vector-stores/spring-ai-elasticsearch-store/src/test/java/org/springframework/ai/vectorstore/elasticsearch/ElasticsearchVectorStoreObservationIT.java

@@ -156,13 +156,14 @@ public class ElasticsearchVectorStoreObservationIT {
 
 			Awaitility.await()
 				.until(() -> vectorStore
-					.similaritySearch(SearchRequest.query("What is Great Depression").withSimilarityThresholdAll())
+					.similaritySearch(
+							SearchRequest.builder().query("What is Great Depression").similarityThresholdAll().build())
 					.size(), greaterThan(1));
 
 			observationRegistry.clear();
 
 			List<Document> results = vectorStore
-				.similaritySearch(SearchRequest.query("What is Great Depression").withTopK(1));
+				.similaritySearch(SearchRequest.builder().query("What is Great Depression").topK(1).build());
 
 			assertThat(results).isNotEmpty();
 

vector-stores/spring-ai-gemfire-store/src/test/java/org/springframework/ai/vectorstore/gemfire/GemFireVectorStoreIT.java

@@ -115,8 +115,8 @@ public class GemFireVectorStoreIT {
 			vectorStore.delete(this.documents.stream().map(doc -> doc.getId()).toList());
 			Awaitility.await()
 				.atMost(1, java.util.concurrent.TimeUnit.MINUTES)
-				.until(() -> vectorStore.similaritySearch(SearchRequest.query("Great Depression").withTopK(3)),
-						hasSize(0));
+				.until(() -> vectorStore
+					.similaritySearch(SearchRequest.builder().query("Great Depression").topK(3).build()), hasSize(0));
 		});
 	}
 
@@ -128,10 +128,11 @@ public class GemFireVectorStoreIT {
 
 			Awaitility.await()
 				.atMost(1, java.util.concurrent.TimeUnit.MINUTES)
-				.until(() -> vectorStore.similaritySearch(SearchRequest.query("Great Depression").withTopK(1)),
-						hasSize(1));
+				.until(() -> vectorStore
+					.similaritySearch(SearchRequest.builder().query("Great Depression").topK(1).build()), hasSize(1));
 
-			List<Document> results = vectorStore.similaritySearch(SearchRequest.query("Great Depression").withTopK(5));
+			List<Document> results = vectorStore
+				.similaritySearch(SearchRequest.builder().query("Great Depression").topK(5).build());
 			Document resultDoc = results.get(0);
 			assertThat(resultDoc.getId()).isEqualTo(this.documents.get(2).getId());
 			assertThat(resultDoc.getContent()).contains("The Great Depression (1929–1939)" + " was an economic shock");
@@ -149,11 +150,11 @@ public class GemFireVectorStoreIT {
 			Document document = new Document(UUID.randomUUID().toString(), "Spring AI rocks!!",
 					Collections.singletonMap("meta1", "meta1"));
 			vectorStore.add(List.of(document));
-			SearchRequest springSearchRequest = SearchRequest.query("Spring").withTopK(5);
+			SearchRequest springSearchRequest = SearchRequest.builder().query("Spring").topK(5).build();
 			Awaitility.await()
 				.atMost(1, java.util.concurrent.TimeUnit.MINUTES)
-				.until(() -> vectorStore.similaritySearch(SearchRequest.query("Great Depression").withTopK(1)),
-						hasSize(1));
+				.until(() -> vectorStore
+					.similaritySearch(SearchRequest.builder().query("Great Depression").topK(1).build()), hasSize(1));
 			List<Document> results = vectorStore.similaritySearch(springSearchRequest);
 			Document resultDoc = results.get(0);
 			assertThat(resultDoc.getId()).isEqualTo(document.getId());
@@ -166,7 +167,7 @@ public class GemFireVectorStoreIT {
 					Collections.singletonMap("meta2", "meta2"));
 
 			vectorStore.add(List.of(sameIdDocument));
-			SearchRequest fooBarSearchRequest = SearchRequest.query("FooBar").withTopK(5);
+			SearchRequest fooBarSearchRequest = SearchRequest.builder().query("FooBar").topK(5).build();
 			results = vectorStore.similaritySearch(fooBarSearchRequest);
 
 			assertThat(results).hasSize(1);
@@ -187,19 +188,22 @@ public class GemFireVectorStoreIT {
 
 			Awaitility.await()
 				.atMost(1, java.util.concurrent.TimeUnit.MINUTES)
-				.until(() -> vectorStore
-					.similaritySearch(SearchRequest.query("Great Depression").withTopK(5).withSimilarityThresholdAll()),
+				.until(() -> vectorStore.similaritySearch(
+						SearchRequest.builder().query("Great Depression").topK(5).similarityThresholdAll().build()),
 						hasSize(3));
 
 			List<Document> fullResult = vectorStore
-				.similaritySearch(SearchRequest.query("Depression").withTopK(5).withSimilarityThresholdAll());
+				.similaritySearch(SearchRequest.builder().query("Depression").topK(5).similarityThresholdAll().build());
 
 			List<Double> scores = fullResult.stream().map(Document::getScore).toList();
 			assertThat(scores).hasSize(3);
 
 			double similarityThreshold = (scores.get(0) + scores.get(1)) / 2;
-			List<Document> results = vectorStore.similaritySearch(
-					SearchRequest.query("Depression").withTopK(5).withSimilarityThreshold(similarityThreshold));
+			List<Document> results = vectorStore.similaritySearch(SearchRequest.builder()
+				.query("Depression")
+				.topK(5)
+				.similarityThreshold(similarityThreshold)
+				.build());
 
 			assertThat(results).hasSize(1);
 

vector-stores/spring-ai-gemfire-store/src/test/java/org/springframework/ai/vectorstore/gemfire/GemFireVectorStoreObservationIT.java

@@ -149,14 +149,14 @@ public class GemFireVectorStoreObservationIT {
 
 			Awaitility.await()
 				.atMost(1, java.util.concurrent.TimeUnit.MINUTES)
-				.until(() -> vectorStore
-					.similaritySearch(SearchRequest.query("Great Depression").withTopK(5).withSimilarityThresholdAll()),
+				.until(() -> vectorStore.similaritySearch(
+						SearchRequest.builder().query("Great Depression").topK(5).similarityThresholdAll().build()),
 						hasSize(3));
 
 			observationRegistry.clear();
 
 			List<Document> results = vectorStore
-				.similaritySearch(SearchRequest.query("What is Great Depression").withTopK(1));
+				.similaritySearch(SearchRequest.builder().query("What is Great Depression").topK(1).build());
 
 			assertThat(results).isNotEmpty();
 

vector-stores/spring-ai-hanadb-store/src/main/java/org/springframework/ai/vectorstore/hanadb/HanaCloudVectorStore.java

@@ -177,7 +177,7 @@ public class HanaCloudVectorStore extends AbstractObservationVectorStore {
 
 	@Override
 	public List<Document> similaritySearch(String query) {
-		return similaritySearch(SearchRequest.query(query).withTopK(this.topK));
+		return similaritySearch(SearchRequest.builder().query(query).topK(this.topK).build());
 	}
 
 	@Override

vector-stores/spring-ai-hanadb-store/src/test/java/org/springframework/ai/vectorstore/hanadb/HanaVectorStoreObservationIT.java

@@ -121,7 +121,7 @@ public class HanaVectorStoreObservationIT {
 			observationRegistry.clear();
 
 			List<Document> results = vectorStore
-				.similaritySearch(SearchRequest.query("What is Great Depression").withTopK(1));
+				.similaritySearch(SearchRequest.builder().query("What is Great Depression").topK(1).build());
 
 			assertThat(results).isNotEmpty();
 

vector-stores/spring-ai-mariadb-store/src/test/java/org/springframework/ai/vectorstore/mariadb/MariaDBStoreIT.java

@@ -29,7 +29,6 @@ import java.util.UUID;
 import java.util.stream.Stream;
 import javax.sql.DataSource;
 import org.junit.Assert;
-import org.junit.jupiter.api.Disabled;
 import org.junit.jupiter.api.condition.EnabledIfEnvironmentVariable;
 import org.junit.jupiter.params.ParameterizedTest;
 import org.junit.jupiter.params.provider.Arguments;
@@ -42,7 +41,6 @@ import org.springframework.ai.openai.api.OpenAiApi;
 import org.springframework.ai.vectorstore.SearchRequest;
 import org.springframework.ai.vectorstore.VectorStore;
 import org.springframework.ai.vectorstore.filter.FilterExpressionTextParser.FilterExpressionParseException;
-import org.springframework.ai.vectorstore.mariadb.MariaDBVectorStore;
 import org.springframework.beans.factory.annotation.Value;
 import org.springframework.boot.SpringBootConfiguration;
 import org.springframework.boot.autoconfigure.EnableAutoConfiguration;
@@ -144,7 +142,7 @@ public class MariaDBStoreIT {
 				vectorStore.add(this.documents);
 
 				List<Document> results = vectorStore
-					.similaritySearch(SearchRequest.query("What is Great Depression").withTopK(1));
+					.similaritySearch(SearchRequest.builder().query("What is Great Depression").topK(1).build());
 
 				assertThat(results).hasSize(1);
 				Document resultDoc = results.get(0);
@@ -155,7 +153,7 @@ public class MariaDBStoreIT {
 				vectorStore.delete(this.documents.stream().map(doc -> doc.getId()).toList());
 
 				List<Document> results2 = vectorStore
-					.similaritySearch(SearchRequest.query("Great Depression").withTopK(1));
+					.similaritySearch(SearchRequest.builder().query("Great Depression").topK(1).build());
 				assertThat(results2).hasSize(0);
 
 				dropTable(context);
@@ -178,10 +176,12 @@ public class MariaDBStoreIT {
 
 			vectorStore.add(List.of(bgDocument, nlDocument, bgDocument2));
 
-			SearchRequest searchRequest = SearchRequest.query("The World")
-				.withFilterExpression(expression)
-				.withTopK(5)
-				.withSimilarityThresholdAll();
+			SearchRequest searchRequest = SearchRequest.builder()
+				.query("The World")
+				.filterExpression(expression)
+				.topK(5)
+				.similarityThresholdAll()
+				.build();
 
 			List<Document> results = vectorStore.similaritySearch(searchRequest);
 
@@ -209,51 +209,62 @@ public class MariaDBStoreIT {
 
 				vectorStore.add(List.of(bgDocument, nlDocument, bgDocument2));
 
-				SearchRequest searchRequest = SearchRequest.query("The World").withTopK(5).withSimilarityThresholdAll();
+				SearchRequest searchRequest = SearchRequest.builder()
+					.query("The World")
+					.topK(5)
+					.similarityThresholdAll()
+					.build();
 
 				List<Document> results = vectorStore.similaritySearch(searchRequest);
 
 				assertThat(results).hasSize(3);
 
-				results = vectorStore.similaritySearch(searchRequest.withFilterExpression("country == 'NL'"));
+				results = vectorStore
+					.similaritySearch(SearchRequest.from(searchRequest).filterExpression("country == 'NL'").build());
 
 				assertThat(results).hasSize(1);
 				assertThat(results.get(0).getId()).isEqualTo(nlDocument.getId());
 
-				results = vectorStore.similaritySearch(searchRequest.withFilterExpression("country == 'BG'"));
+				results = vectorStore
+					.similaritySearch(SearchRequest.from(searchRequest).filterExpression("country == 'BG'").build());
 
 				assertThat(results).hasSize(2);
 				assertThat(results.get(0).getId()).isIn(bgDocument.getId(), bgDocument2.getId());
 				assertThat(results.get(1).getId()).isIn(bgDocument.getId(), bgDocument2.getId());
 
-				results = vectorStore
-					.similaritySearch(searchRequest.withFilterExpression("country == 'BG' && year == 2020"));
+				results = vectorStore.similaritySearch(
+						SearchRequest.from(searchRequest).filterExpression("country == 'BG' && year == 2020").build());
 
 				assertThat(results).hasSize(1);
 				assertThat(results.get(0).getId()).isEqualTo(bgDocument.getId());
 
-				results = vectorStore.similaritySearch(
-						searchRequest.withFilterExpression("(country == 'BG' && year == 2020) || (country == 'NL')"));
+				results = vectorStore.similaritySearch(SearchRequest.from(searchRequest)
+					.filterExpression("(country == 'BG' && year == 2020) || (country == 'NL')")
+					.build());
 
 				assertThat(results).hasSize(2);
 				assertThat(results.get(0).getId()).isIn(bgDocument.getId(), nlDocument.getId());
 				assertThat(results.get(1).getId()).isIn(bgDocument.getId(), nlDocument.getId());
 
-				results = vectorStore.similaritySearch(searchRequest
-					.withFilterExpression("NOT((country == 'BG' && year == 2020) || (country == 'NL'))"));
+				results = vectorStore.similaritySearch(SearchRequest.from(searchRequest)
+					.filterExpression("NOT((country == 'BG' && year == 2020) || (country == 'NL'))")
+					.build());
 
 				assertThat(results).hasSize(1);
 				assertThat(results.get(0).getId()).isEqualTo(bgDocument2.getId());
 
-				results = vectorStore.similaritySearch(SearchRequest.query("The World")
-					.withTopK(5)
-					.withSimilarityThresholdAll()
-					.withFilterExpression("\"foo bar 1\" == 'bar.foo'"));
+				results = vectorStore.similaritySearch(SearchRequest.builder()
+					.query("The World")
+					.topK(5)
+					.similarityThresholdAll()
+					.filterExpression("\"foo bar 1\" == 'bar.foo'")
+					.build());
 				assertThat(results).hasSize(1);
 				assertThat(results.get(0).getId()).isEqualTo(bgDocument.getId());
 
 				try {
-					vectorStore.similaritySearch(searchRequest.withFilterExpression("country == NL"));
+					vectorStore
+						.similaritySearch(SearchRequest.from(searchRequest).filterExpression("country == NL").build());
 					Assert.fail("Invalid filter expression should have been cached!");
 				}
 				catch (FilterExpressionParseException e) {
@@ -278,7 +289,8 @@ public class MariaDBStoreIT {
 
 				vectorStore.add(List.of(document));
 
-				List<Document> results = vectorStore.similaritySearch(SearchRequest.query("Spring").withTopK(5));
+				List<Document> results = vectorStore
+					.similaritySearch(SearchRequest.builder().query("Spring").topK(5).build());
 
 				assertThat(results).hasSize(1);
 				Document resultDoc = results.get(0);
@@ -292,7 +304,7 @@ public class MariaDBStoreIT {
 
 				vectorStore.add(List.of(sameIdDocument));
 
-				results = vectorStore.similaritySearch(SearchRequest.query("FooBar").withTopK(5));
+				results = vectorStore.similaritySearch(SearchRequest.builder().query("FooBar").topK(5).build());
 
 				assertThat(results).hasSize(1);
 				resultDoc = results.get(0);
@@ -314,8 +326,8 @@ public class MariaDBStoreIT {
 
 				vectorStore.add(this.documents);
 
-				List<Document> fullResult = vectorStore
-					.similaritySearch(SearchRequest.query("Time Shelter").withTopK(5).withSimilarityThresholdAll());
+				List<Document> fullResult = vectorStore.similaritySearch(
+						SearchRequest.builder().query("Time Shelter").topK(5).similarityThresholdAll().build());
 
 				assertThat(fullResult).hasSize(3);
 
@@ -327,8 +339,11 @@ public class MariaDBStoreIT {
 
 				float threshold = (distances.get(0) + distances.get(1)) / 2;
 
-				List<Document> results = vectorStore.similaritySearch(
-						SearchRequest.query("Time Shelter").withTopK(5).withSimilarityThreshold(1 - threshold));
+				List<Document> results = vectorStore.similaritySearch(SearchRequest.builder()
+					.query("Time Shelter")
+					.topK(5)
+					.similarityThreshold(1 - threshold)
+					.build());
 
 				assertThat(results).hasSize(1);
 				Document resultDoc = results.get(0);

vector-stores/spring-ai-mariadb-store/src/test/java/org/springframework/ai/vectorstore/mariadb/MariaDBStoreObservationIT.java

@@ -28,7 +28,6 @@ import java.util.List;
 import java.util.Map;
 import javax.sql.DataSource;
 
-import org.junit.jupiter.api.Disabled;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.condition.EnabledIfEnvironmentVariable;
 import org.springframework.ai.document.Document;
@@ -36,12 +35,10 @@ import org.springframework.ai.embedding.EmbeddingModel;
 import org.springframework.ai.observation.conventions.SpringAiKind;
 import org.springframework.ai.observation.conventions.VectorStoreProvider;
 import org.springframework.ai.observation.conventions.VectorStoreSimilarityMetric;
-import org.springframework.ai.openai.OpenAiChatModel;
 import org.springframework.ai.openai.OpenAiEmbeddingModel;
 import org.springframework.ai.openai.api.OpenAiApi;
 import org.springframework.ai.vectorstore.SearchRequest;
 import org.springframework.ai.vectorstore.VectorStore;
-import org.springframework.ai.vectorstore.mariadb.MariaDBVectorStore;
 import org.springframework.ai.vectorstore.observation.DefaultVectorStoreObservationConvention;
 import org.springframework.ai.vectorstore.observation.VectorStoreObservationDocumentation.HighCardinalityKeyNames;
 import org.springframework.ai.vectorstore.observation.VectorStoreObservationDocumentation.LowCardinalityKeyNames;
@@ -134,7 +131,7 @@ public class MariaDBStoreObservationIT {
 			observationRegistry.clear();
 
 			List<Document> results = vectorStore
-				.similaritySearch(SearchRequest.query("What is Great Depression").withTopK(1));
+				.similaritySearch(SearchRequest.builder().query("What is Great Depression").topK(1).build());
 
 			assertThat(results).isNotEmpty();
 

vector-stores/spring-ai-milvus-store/src/test/java/org/springframework/ai/milvus/vectorstore/MilvusVectorStoreCustomFieldNamesIT.java

@@ -100,7 +100,8 @@ class MilvusVectorStoreCustomFieldNamesIT {
 
 				vectorStore.add(this.documents);
 
-				List<Document> fullResult = vectorStore.similaritySearch(SearchRequest.query("Spring"));
+				List<Document> fullResult = vectorStore
+					.similaritySearch(SearchRequest.builder().query("Spring").build());
 
 				List<Float> distances = fullResult.stream()
 					.map(doc -> (Float) doc.getMetadata().get("distance"))
@@ -110,8 +111,8 @@ class MilvusVectorStoreCustomFieldNamesIT {
 
 				float threshold = (distances.get(0) + distances.get(1)) / 2;
 
-				List<Document> results = vectorStore
-					.similaritySearch(SearchRequest.query("Spring").withTopK(5).withSimilarityThreshold(1 - threshold));
+				List<Document> results = vectorStore.similaritySearch(
+						SearchRequest.builder().query("Spring").topK(5).similarityThreshold(1 - threshold).build());
 
 				assertThat(results).hasSize(1);
 				Document resultDoc = results.get(0);
@@ -140,7 +141,8 @@ class MilvusVectorStoreCustomFieldNamesIT {
 
 				vectorStore.add(this.documents);
 
-				List<Document> fullResult = vectorStore.similaritySearch(SearchRequest.query("Spring"));
+				List<Document> fullResult = vectorStore
+					.similaritySearch(SearchRequest.builder().query("Spring").build());
 
 				List<Float> distances = fullResult.stream()
 					.map(doc -> (Float) doc.getMetadata().get("distance"))
@@ -150,8 +152,8 @@ class MilvusVectorStoreCustomFieldNamesIT {
 
 				float threshold = (distances.get(0) + distances.get(1)) / 2;
 
-				List<Document> results = vectorStore
-					.similaritySearch(SearchRequest.query("Spring").withTopK(5).withSimilarityThreshold(1 - threshold));
+				List<Document> results = vectorStore.similaritySearch(
+						SearchRequest.builder().query("Spring").topK(5).similarityThreshold(1 - threshold).build());
 
 				assertThat(results).hasSize(1);
 				Document resultDoc = results.get(0);
@@ -182,7 +184,8 @@ class MilvusVectorStoreCustomFieldNamesIT {
 
 				vectorStore.add(this.documents);
 
-				List<Document> fullResult = vectorStore.similaritySearch(SearchRequest.query("Spring"));
+				List<Document> fullResult = vectorStore
+					.similaritySearch(SearchRequest.builder().query("Spring").build());
 
 				List<Float> distances = fullResult.stream()
 					.map(doc -> (Float) doc.getMetadata().get("distance"))
@@ -192,8 +195,8 @@ class MilvusVectorStoreCustomFieldNamesIT {
 
 				float threshold = (distances.get(0) + distances.get(1)) / 2;
 
-				List<Document> results = vectorStore
-					.similaritySearch(SearchRequest.query("Spring").withTopK(5).withSimilarityThreshold(1 - threshold));
+				List<Document> results = vectorStore.similaritySearch(
+						SearchRequest.builder().query("Spring").topK(5).similarityThreshold(1 - threshold).build());
 
 				assertThat(results).hasSize(1);
 				Document resultDoc = results.get(0);

vector-stores/spring-ai-milvus-store/src/test/java/org/springframework/ai/milvus/vectorstore/MilvusVectorStoreIT.java

@@ -40,7 +40,6 @@ import org.springframework.ai.embedding.EmbeddingModel;
 import org.springframework.ai.embedding.TokenCountBatchingStrategy;
 import org.springframework.ai.openai.OpenAiEmbeddingModel;
 import org.springframework.ai.openai.api.OpenAiApi;
-import org.springframework.ai.milvus.vectorstore.MilvusVectorStore.MilvusVectorStoreConfig;
 import org.springframework.ai.vectorstore.SearchRequest;
 import org.springframework.ai.vectorstore.VectorStore;
 import org.springframework.beans.factory.annotation.Value;
@@ -101,7 +100,8 @@ public class MilvusVectorStoreIT {
 
 				vectorStore.add(this.documents);
 
-				List<Document> results = vectorStore.similaritySearch(SearchRequest.query("Spring").withTopK(1));
+				List<Document> results = vectorStore
+					.similaritySearch(SearchRequest.builder().query("Spring").topK(1).build());
 
 				assertThat(results).hasSize(1);
 				Document resultDoc = results.get(0);
@@ -114,7 +114,7 @@ public class MilvusVectorStoreIT {
 				// Remove all documents from the store
 				vectorStore.delete(this.documents.stream().map(doc -> doc.getId()).toList());
 
-				results = vectorStore.similaritySearch(SearchRequest.query("Spring").withTopK(1));
+				results = vectorStore.similaritySearch(SearchRequest.builder().query("Spring").topK(1).build());
 				assertThat(results).hasSize(0);
 			});
 	}
@@ -141,37 +141,46 @@ public class MilvusVectorStoreIT {
 
 				vectorStore.add(List.of(bgDocument, nlDocument, bgDocument2));
 
-				List<Document> results = vectorStore.similaritySearch(SearchRequest.query("The World").withTopK(5));
+				List<Document> results = vectorStore
+					.similaritySearch(SearchRequest.builder().query("The World").topK(5).build());
 				assertThat(results).hasSize(3);
 
-				results = vectorStore.similaritySearch(SearchRequest.query("The World")
-					.withTopK(5)
-					.withSimilarityThresholdAll()
-					.withFilterExpression("country == 'NL'"));
+				results = vectorStore.similaritySearch(SearchRequest.builder()
+					.query("The World")
+					.topK(5)
+					.similarityThresholdAll()
+					.filterExpression("country == 'NL'")
+					.build());
 				assertThat(results).hasSize(1);
 				assertThat(results.get(0).getId()).isEqualTo(nlDocument.getId());
 
-				results = vectorStore.similaritySearch(SearchRequest.query("The World")
-					.withTopK(5)
-					.withSimilarityThresholdAll()
-					.withFilterExpression("country == 'BG'"));
+				results = vectorStore.similaritySearch(SearchRequest.builder()
+					.query("The World")
+					.topK(5)
+					.similarityThresholdAll()
+					.filterExpression("country == 'BG'")
+					.build());
 
 				assertThat(results).hasSize(2);
 				assertThat(results.get(0).getId()).isIn(bgDocument.getId(), bgDocument2.getId());
 				assertThat(results.get(1).getId()).isIn(bgDocument.getId(), bgDocument2.getId());
 
-				results = vectorStore.similaritySearch(SearchRequest.query("The World")
-					.withTopK(5)
-					.withSimilarityThresholdAll()
-					.withFilterExpression("country == 'BG' && year == 2020"));
+				results = vectorStore.similaritySearch(SearchRequest.builder()
+					.query("The World")
+					.topK(5)
+					.similarityThresholdAll()
+					.filterExpression("country == 'BG' && year == 2020")
+					.build());
 
 				assertThat(results).hasSize(1);
 				assertThat(results.get(0).getId()).isEqualTo(bgDocument.getId());
 
-				results = vectorStore.similaritySearch(SearchRequest.query("The World")
-					.withTopK(5)
-					.withSimilarityThresholdAll()
-					.withFilterExpression("NOT(country == 'BG' && year == 2020)"));
+				results = vectorStore.similaritySearch(SearchRequest.builder()
+					.query("The World")
+					.topK(5)
+					.similarityThresholdAll()
+					.filterExpression("NOT(country == 'BG' && year == 2020)")
+					.build());
 
 				assertThat(results).hasSize(2);
 				assertThat(results.get(0).getId()).isIn(nlDocument.getId(), bgDocument2.getId());
@@ -196,7 +205,8 @@ public class MilvusVectorStoreIT {
 
 				vectorStore.add(List.of(document));
 
-				List<Document> results = vectorStore.similaritySearch(SearchRequest.query("Spring").withTopK(5));
+				List<Document> results = vectorStore
+					.similaritySearch(SearchRequest.builder().query("Spring").topK(5).build());
 
 				assertThat(results).hasSize(1);
 				Document resultDoc = results.get(0);
@@ -211,7 +221,7 @@ public class MilvusVectorStoreIT {
 
 				vectorStore.add(List.of(sameIdDocument));
 
-				results = vectorStore.similaritySearch(SearchRequest.query("FooBar").withTopK(5));
+				results = vectorStore.similaritySearch(SearchRequest.builder().query("FooBar").topK(5).build());
 
 				assertThat(results).hasSize(1);
 				resultDoc = results.get(0);
@@ -239,7 +249,7 @@ public class MilvusVectorStoreIT {
 				vectorStore.add(this.documents);
 
 				List<Document> fullResult = vectorStore
-					.similaritySearch(SearchRequest.query("Spring").withTopK(5).withSimilarityThresholdAll());
+					.similaritySearch(SearchRequest.builder().query("Spring").topK(5).similarityThresholdAll().build());
 
 				List<Double> scores = fullResult.stream().map(Document::getScore).toList();
 
@@ -247,8 +257,11 @@ public class MilvusVectorStoreIT {
 
 				double similarityThreshold = (scores.get(0) + scores.get(1)) / 2;
 
-				List<Document> results = vectorStore.similaritySearch(
-						SearchRequest.query("Spring").withTopK(5).withSimilarityThreshold(similarityThreshold));
+				List<Document> results = vectorStore.similaritySearch(SearchRequest.builder()
+					.query("Spring")
+					.topK(5)
+					.similarityThreshold(similarityThreshold)
+					.build());
 
 				assertThat(results).hasSize(1);
 				Document resultDoc = results.get(0);

vector-stores/spring-ai-milvus-store/src/test/java/org/springframework/ai/milvus/vectorstore/MilvusVectorStoreObservationIT.java

@@ -42,7 +42,6 @@ import org.springframework.ai.observation.conventions.VectorStoreProvider;
 import org.springframework.ai.observation.conventions.VectorStoreSimilarityMetric;
 import org.springframework.ai.openai.OpenAiEmbeddingModel;
 import org.springframework.ai.openai.api.OpenAiApi;
-import org.springframework.ai.milvus.vectorstore.MilvusVectorStore.MilvusVectorStoreConfig;
 import org.springframework.ai.vectorstore.SearchRequest;
 import org.springframework.ai.vectorstore.VectorStore;
 import org.springframework.ai.vectorstore.observation.DefaultVectorStoreObservationConvention;
@@ -125,7 +124,7 @@ public class MilvusVectorStoreObservationIT {
 			observationRegistry.clear();
 
 			List<Document> results = vectorStore
-				.similaritySearch(SearchRequest.query("What is Great Depression").withTopK(1));
+				.similaritySearch(SearchRequest.builder().query("What is Great Depression").topK(1).build());
 
 			assertThat(results).isNotEmpty();
 

vector-stores/spring-ai-mongodb-atlas-store/src/main/java/org/springframework/ai/vectorstore/mongodb/atlas/MongoDBAtlasVectorStore.java

@@ -312,7 +312,7 @@ public class MongoDBAtlasVectorStore extends AbstractObservationVectorStore impl
 
 	@Override
 	public List<Document> similaritySearch(String query) {
-		return similaritySearch(SearchRequest.query(query));
+		return similaritySearch(SearchRequest.builder().query(query).build());
 	}
 
 	@Override

vector-stores/spring-ai-mongodb-atlas-store/src/test/java/org/springframework/ai/vectorstore/mongodb/atlas/MongoDBAtlasVectorStoreIT.java

@@ -97,7 +97,8 @@ class MongoDBAtlasVectorStoreIT {
 			vectorStore.add(documents);
 			Thread.sleep(5000); // Await a second for the document to be indexed
 
-			List<Document> results = vectorStore.similaritySearch(SearchRequest.query("Great").withTopK(1));
+			List<Document> results = vectorStore
+				.similaritySearch(SearchRequest.builder().query("Great").topK(1).build());
 
 			assertThat(results).hasSize(1);
 			Document resultDoc = results.get(0);
@@ -109,7 +110,8 @@ class MongoDBAtlasVectorStoreIT {
 			// Remove all documents from the store
 			vectorStore.delete(documents.stream().map(Document::getId).collect(Collectors.toList()));
 
-			List<Document> results2 = vectorStore.similaritySearch(SearchRequest.query("Great").withTopK(1));
+			List<Document> results2 = vectorStore
+				.similaritySearch(SearchRequest.builder().query("Great").topK(1).build());
 			assertThat(results2).isEmpty();
 
 		});
@@ -126,7 +128,8 @@ class MongoDBAtlasVectorStoreIT {
 			vectorStore.add(List.of(document));
 			Thread.sleep(5000); // Await a second for the document to be indexed
 
-			List<Document> results = vectorStore.similaritySearch(SearchRequest.query("Spring").withTopK(5));
+			List<Document> results = vectorStore
+				.similaritySearch(SearchRequest.builder().query("Spring").topK(5).build());
 
 			assertThat(results).hasSize(1);
 			Document resultDoc = results.get(0);
@@ -140,7 +143,7 @@ class MongoDBAtlasVectorStoreIT {
 
 			vectorStore.add(List.of(sameIdDocument));
 
-			results = vectorStore.similaritySearch(SearchRequest.query("FooBar").withTopK(5));
+			results = vectorStore.similaritySearch(SearchRequest.builder().query("FooBar").topK(5).build());
 
 			assertThat(results).hasSize(1);
 			resultDoc = results.get(0);
@@ -165,37 +168,46 @@ class MongoDBAtlasVectorStoreIT {
 			vectorStore.add(List.of(bgDocument, nlDocument, bgDocument2));
 			Thread.sleep(5000); // Await a second for the document to be indexed
 
-			List<Document> results = vectorStore.similaritySearch(SearchRequest.query("The World").withTopK(5));
+			List<Document> results = vectorStore
+				.similaritySearch(SearchRequest.builder().query("The World").topK(5).build());
 			assertThat(results).hasSize(3);
 
-			results = vectorStore.similaritySearch(SearchRequest.query("The World")
-				.withTopK(5)
-				.withSimilarityThresholdAll()
-				.withFilterExpression("country == 'NL'"));
+			results = vectorStore.similaritySearch(SearchRequest.builder()
+				.query("The World")
+				.topK(5)
+				.similarityThresholdAll()
+				.filterExpression("country == 'NL'")
+				.build());
 			assertThat(results).hasSize(1);
 			assertThat(results.get(0).getId()).isEqualTo(nlDocument.getId());
 
-			results = vectorStore.similaritySearch(SearchRequest.query("The World")
-				.withTopK(5)
-				.withSimilarityThresholdAll()
-				.withFilterExpression("country == 'BG'"));
+			results = vectorStore.similaritySearch(SearchRequest.builder()
+				.query("The World")
+				.topK(5)
+				.similarityThresholdAll()
+				.filterExpression("country == 'BG'")
+				.build());
 
 			assertThat(results).hasSize(2);
 			assertThat(results.get(0).getId()).isIn(bgDocument.getId(), bgDocument2.getId());
 			assertThat(results.get(1).getId()).isIn(bgDocument.getId(), bgDocument2.getId());
 
-			results = vectorStore.similaritySearch(SearchRequest.query("The World")
-				.withTopK(5)
-				.withSimilarityThresholdAll()
-				.withFilterExpression("country == 'BG' && year == 2020"));
+			results = vectorStore.similaritySearch(SearchRequest.builder()
+				.query("The World")
+				.topK(5)
+				.similarityThresholdAll()
+				.filterExpression("country == 'BG' && year == 2020")
+				.build());
 
 			assertThat(results).hasSize(1);
 			assertThat(results.get(0).getId()).isEqualTo(bgDocument.getId());
 
-			results = vectorStore.similaritySearch(SearchRequest.query("The World")
-				.withTopK(5)
-				.withSimilarityThresholdAll()
-				.withFilterExpression("NOT(country == 'BG' && year == 2020)"));
+			results = vectorStore.similaritySearch(SearchRequest.builder()
+				.query("The World")
+				.topK(5)
+				.similarityThresholdAll()
+				.filterExpression("NOT(country == 'BG' && year == 2020)")
+				.build());
 
 			assertThat(results).hasSize(2);
 			assertThat(results.get(0).getId()).isIn(nlDocument.getId(), bgDocument2.getId());
@@ -220,7 +232,7 @@ class MongoDBAtlasVectorStoreIT {
 			Thread.sleep(5000); // Await a second for the document to be indexed
 
 			List<Document> fullResult = vectorStore
-				.similaritySearch(SearchRequest.query("Spring").withTopK(5).withSimilarityThresholdAll());
+				.similaritySearch(SearchRequest.builder().query("Spring").topK(5).similarityThresholdAll().build());
 			assertThat(fullResult).hasSize(3);
 
 			List<Double> scores = fullResult.stream().map(Document::getScore).toList();
@@ -230,7 +242,7 @@ class MongoDBAtlasVectorStoreIT {
 			double similarityThreshold = (scores.get(0) + scores.get(1)) / 2;
 
 			List<Document> results = vectorStore.similaritySearch(
-					SearchRequest.query("Spring").withTopK(5).withSimilarityThreshold(similarityThreshold));
+					SearchRequest.builder().query("Spring").topK(5).similarityThreshold(similarityThreshold).build());
 
 			assertThat(results).hasSize(1);
 			Document resultDoc = results.get(0);

vector-stores/spring-ai-mongodb-atlas-store/src/test/java/org/springframework/ai/vectorstore/mongodb/atlas/MongoDbVectorStoreObservationIT.java

@@ -141,7 +141,7 @@ public class MongoDbVectorStoreObservationIT {
 			observationRegistry.clear();
 
 			List<Document> results = vectorStore
-				.similaritySearch(SearchRequest.query("What is Great Depression").withTopK(1));
+				.similaritySearch(SearchRequest.builder().query("What is Great Depression").topK(1).build());
 
 			assertThat(results).isNotEmpty();
 

vector-stores/spring-ai-neo4j-store/src/test/java/org/springframework/ai/vectorstore/neo4j/Neo4jVectorStoreIT.java

@@ -86,7 +86,8 @@ class Neo4jVectorStoreIT {
 
 			vectorStore.add(this.documents);
 
-			List<Document> results = vectorStore.similaritySearch(SearchRequest.query("Great").withTopK(1));
+			List<Document> results = vectorStore
+				.similaritySearch(SearchRequest.builder().query("Great").topK(1).build());
 
 			assertThat(results).hasSize(1);
 			Document resultDoc = results.get(0);
@@ -99,7 +100,8 @@ class Neo4jVectorStoreIT {
 			// Remove all documents from the store
 			vectorStore.delete(this.documents.stream().map(Document::getId).toList());
 
-			List<Document> results2 = vectorStore.similaritySearch(SearchRequest.query("Great").withTopK(1));
+			List<Document> results2 = vectorStore
+				.similaritySearch(SearchRequest.builder().query("Great").topK(1).build());
 			assertThat(results2).isEmpty();
 		});
 	}
@@ -119,66 +121,80 @@ class Neo4jVectorStoreIT {
 
 			vectorStore.add(List.of(bgDocument, nlDocument, bgDocument2));
 
-			SearchRequest searchRequest = SearchRequest.query("The World").withTopK(5).withSimilarityThresholdAll();
+			SearchRequest searchRequest = SearchRequest.builder()
+				.query("The World")
+				.topK(5)
+				.similarityThresholdAll()
+				.build();
 
 			List<Document> results = vectorStore.similaritySearch(searchRequest);
 
 			assertThat(results).hasSize(3);
 
-			results = vectorStore.similaritySearch(searchRequest.withFilterExpression("country == 'NL'"));
+			results = vectorStore
+				.similaritySearch(SearchRequest.from(searchRequest).filterExpression("country == 'NL'").build());
 
 			assertThat(results).hasSize(1);
 			assertThat(results.get(0).getId()).isEqualTo(nlDocument.getId());
 
-			results = vectorStore.similaritySearch(searchRequest.withFilterExpression("country in ['NL']"));
+			results = vectorStore
+				.similaritySearch(SearchRequest.from(searchRequest).filterExpression("country in ['NL']").build());
 
 			assertThat(results).hasSize(1);
 			assertThat(results.get(0).getId()).isEqualTo(nlDocument.getId());
 
-			results = vectorStore.similaritySearch(searchRequest.withFilterExpression("country nin ['BG']"));
+			results = vectorStore
+				.similaritySearch(SearchRequest.from(searchRequest).filterExpression("country nin ['BG']").build());
 
 			assertThat(results).hasSize(1);
 			assertThat(results.get(0).getId()).isEqualTo(nlDocument.getId());
 
-			results = vectorStore.similaritySearch(searchRequest.withFilterExpression("country not in ['BG']"));
+			results = vectorStore
+				.similaritySearch(SearchRequest.from(searchRequest).filterExpression("country not in ['BG']").build());
 
 			assertThat(results).hasSize(1);
 			assertThat(results.get(0).getId()).isEqualTo(nlDocument.getId());
 
-			results = vectorStore.similaritySearch(searchRequest.withFilterExpression("country == 'BG'"));
+			results = vectorStore
+				.similaritySearch(SearchRequest.from(searchRequest).filterExpression("country == 'BG'").build());
 
 			assertThat(results).hasSize(2);
 			assertThat(results.get(0).getId()).isIn(bgDocument.getId(), bgDocument2.getId());
 			assertThat(results.get(1).getId()).isIn(bgDocument.getId(), bgDocument2.getId());
 
-			results = vectorStore
-				.similaritySearch(searchRequest.withFilterExpression("country == 'BG' && year == 2020"));
+			results = vectorStore.similaritySearch(
+					SearchRequest.from(searchRequest).filterExpression("country == 'BG' && year == 2020").build());
 
 			assertThat(results).hasSize(1);
 			assertThat(results.get(0).getId()).isEqualTo(bgDocument.getId());
 
-			results = vectorStore.similaritySearch(
-					searchRequest.withFilterExpression("(country == 'BG' && year == 2020) || (country == 'NL')"));
+			results = vectorStore.similaritySearch(SearchRequest.from(searchRequest)
+				.filterExpression("(country == 'BG' && year == 2020) || (country == 'NL')")
+				.build());
 
 			assertThat(results).hasSize(2);
 			assertThat(results.get(0).getId()).isIn(bgDocument.getId(), nlDocument.getId());
 			assertThat(results.get(1).getId()).isIn(bgDocument.getId(), nlDocument.getId());
 
-			results = vectorStore.similaritySearch(
-					searchRequest.withFilterExpression("NOT((country == 'BG' && year == 2020) || (country == 'NL'))"));
+			results = vectorStore.similaritySearch(SearchRequest.from(searchRequest)
+				.filterExpression("NOT((country == 'BG' && year == 2020) || (country == 'NL'))")
+				.build());
 
 			assertThat(results).hasSize(1);
 			assertThat(results.get(0).getId()).isEqualTo(bgDocument2.getId());
 
-			results = vectorStore.similaritySearch(SearchRequest.query("The World")
-				.withTopK(5)
-				.withSimilarityThresholdAll()
-				.withFilterExpression("\"foo bar 1\" == 'bar.foo'"));
+			results = vectorStore.similaritySearch(SearchRequest.builder()
+				.query("The World")
+				.topK(5)
+				.similarityThresholdAll()
+				.filterExpression("\"foo bar 1\" == 'bar.foo'")
+				.build());
 			assertThat(results).hasSize(1);
 			assertThat(results.get(0).getId()).isEqualTo(bgDocument.getId());
 
 			try {
-				vectorStore.similaritySearch(searchRequest.withFilterExpression("country == NL"));
+				vectorStore
+					.similaritySearch(SearchRequest.from(searchRequest).filterExpression("country == NL").build());
 				Assert.fail("Invalid filter expression should have been cached!");
 			}
 			catch (FilterExpressionTextParser.FilterExpressionParseException e) {
@@ -199,7 +215,8 @@ class Neo4jVectorStoreIT {
 
 			vectorStore.add(List.of(document));
 
-			List<Document> results = vectorStore.similaritySearch(SearchRequest.query("Spring").withTopK(5));
+			List<Document> results = vectorStore
+				.similaritySearch(SearchRequest.builder().query("Spring").topK(5).build());
 
 			assertThat(results).hasSize(1);
 			Document resultDoc = results.get(0);
@@ -214,7 +231,7 @@ class Neo4jVectorStoreIT {
 
 			vectorStore.add(List.of(sameIdDocument));
 
-			results = vectorStore.similaritySearch(SearchRequest.query("FooBar").withTopK(5));
+			results = vectorStore.similaritySearch(SearchRequest.builder().query("FooBar").topK(5).build());
 
 			assertThat(results).hasSize(1);
 			resultDoc = results.get(0);
@@ -236,7 +253,7 @@ class Neo4jVectorStoreIT {
 			vectorStore.add(this.documents);
 
 			List<Document> fullResult = vectorStore
-				.similaritySearch(SearchRequest.query("Great").withTopK(5).withSimilarityThresholdAll());
+				.similaritySearch(SearchRequest.builder().query("Great").topK(5).similarityThresholdAll().build());
 
 			List<Double> scores = fullResult.stream().map(Document::getScore).toList();
 
@@ -245,7 +262,7 @@ class Neo4jVectorStoreIT {
 			double similarityThreshold = (scores.get(0) + scores.get(1)) / 2;
 
 			List<Document> results = vectorStore.similaritySearch(
-					SearchRequest.query("Great").withTopK(5).withSimilarityThreshold(similarityThreshold));
+					SearchRequest.builder().query("Great").topK(5).similarityThreshold(similarityThreshold).build());
 
 			assertThat(results).hasSize(1);
 			Document resultDoc = results.get(0);

vector-stores/spring-ai-neo4j-store/src/test/java/org/springframework/ai/vectorstore/neo4j/Neo4jVectorStoreObservationIT.java

@@ -131,7 +131,7 @@ public class Neo4jVectorStoreObservationIT {
 			observationRegistry.clear();
 
 			List<Document> results = vectorStore
-				.similaritySearch(SearchRequest.query("What is Great Depression").withTopK(1));
+				.similaritySearch(SearchRequest.builder().query("What is Great Depression").topK(1).build());
 
 			assertThat(results).isNotEmpty();
 

vector-stores/spring-ai-opensearch-store/src/test/java/org/springframework/ai/vectorstore/opensearch/OpenSearchVectorStoreIT.java

@@ -134,12 +134,12 @@ class OpenSearchVectorStoreIT {
 			vectorStore.add(this.documents);
 
 			Awaitility.await()
-				.until(() -> vectorStore
-					.similaritySearch(SearchRequest.query("Great Depression").withTopK(1).withSimilarityThreshold(0)),
+				.until(() -> vectorStore.similaritySearch(
+						SearchRequest.builder().query("Great Depression").topK(1).similarityThreshold(0).build()),
 						hasSize(1));
 
-			List<Document> results = vectorStore
-				.similaritySearch(SearchRequest.query("Great Depression").withTopK(1).withSimilarityThreshold(0));
+			List<Document> results = vectorStore.similaritySearch(
+					SearchRequest.builder().query("Great Depression").topK(1).similarityThreshold(0).build());
 
 			assertThat(results).hasSize(1);
 			Document resultDoc = results.get(0);
@@ -153,8 +153,8 @@ class OpenSearchVectorStoreIT {
 			vectorStore.delete(this.documents.stream().map(Document::getId).toList());
 
 			Awaitility.await()
-				.until(() -> vectorStore
-					.similaritySearch(SearchRequest.query("Great Depression").withTopK(1).withSimilarityThreshold(0)),
+				.until(() -> vectorStore.similaritySearch(
+						SearchRequest.builder().query("Great Depression").topK(1).similarityThreshold(0).build()),
 						hasSize(0));
 		});
 	}
@@ -180,71 +180,88 @@ class OpenSearchVectorStoreIT {
 			vectorStore.add(List.of(bgDocument, nlDocument, bgDocument2));
 
 			Awaitility.await()
-				.until(() -> vectorStore.similaritySearch(SearchRequest.query("The World").withTopK(5)), hasSize(3));
+				.until(() -> vectorStore.similaritySearch(SearchRequest.builder().query("The World").topK(5).build()),
+						hasSize(3));
 
-			List<Document> results = vectorStore.similaritySearch(SearchRequest.query("The World")
-				.withTopK(5)
-				.withSimilarityThresholdAll()
-				.withFilterExpression("country == 'NL'"));
+			List<Document> results = vectorStore.similaritySearch(SearchRequest.builder()
+				.query("The World")
+				.topK(5)
+				.similarityThresholdAll()
+				.filterExpression("country == 'NL'")
+				.build());
 
 			assertThat(results).hasSize(1);
 			assertThat(results.get(0).getId()).isEqualTo(nlDocument.getId());
 
-			results = vectorStore.similaritySearch(SearchRequest.query("The World")
-				.withTopK(5)
-				.withSimilarityThresholdAll()
-				.withFilterExpression("country == 'BG'"));
+			results = vectorStore.similaritySearch(SearchRequest.builder()
+				.query("The World")
+				.topK(5)
+				.similarityThresholdAll()
+				.filterExpression("country == 'BG'")
+				.build());
 
 			assertThat(results).hasSize(2);
 			assertThat(results.get(0).getId()).isIn(bgDocument.getId(), bgDocument2.getId());
 			assertThat(results.get(1).getId()).isIn(bgDocument.getId(), bgDocument2.getId());
 
-			results = vectorStore.similaritySearch(SearchRequest.query("The World")
-				.withTopK(5)
-				.withSimilarityThresholdAll()
-				.withFilterExpression("country == 'BG' && year == 2020"));
+			results = vectorStore.similaritySearch(SearchRequest.builder()
+				.query("The World")
+				.topK(5)
+				.similarityThresholdAll()
+				.filterExpression("country == 'BG' && year == 2020")
+				.build());
 
 			assertThat(results).hasSize(1);
 			assertThat(results.get(0).getId()).isEqualTo(bgDocument.getId());
 
-			results = vectorStore.similaritySearch(SearchRequest.query("The World")
-				.withTopK(5)
-				.withSimilarityThresholdAll()
-				.withFilterExpression("country in ['BG']"));
+			results = vectorStore.similaritySearch(SearchRequest.builder()
+				.query("The World")
+				.topK(5)
+				.similarityThresholdAll()
+				.filterExpression("country in ['BG']")
+				.build());
 
 			assertThat(results).hasSize(2);
 			assertThat(results.get(0).getId()).isIn(bgDocument.getId(), bgDocument2.getId());
 			assertThat(results.get(1).getId()).isIn(bgDocument.getId(), bgDocument2.getId());
 
-			results = vectorStore.similaritySearch(SearchRequest.query("The World")
-				.withTopK(5)
-				.withSimilarityThresholdAll()
-				.withFilterExpression("country in ['BG','NL']"));
+			results = vectorStore.similaritySearch(SearchRequest.builder()
+				.query("The World")
+				.topK(5)
+				.similarityThresholdAll()
+				.filterExpression("country in ['BG','NL']")
+				.build());
 
 			assertThat(results).hasSize(3);
 
-			results = vectorStore.similaritySearch(SearchRequest.query("The World")
-				.withTopK(5)
-				.withSimilarityThresholdAll()
-				.withFilterExpression("country not in ['BG']"));
+			results = vectorStore.similaritySearch(SearchRequest.builder()
+				.query("The World")
+				.topK(5)
+				.similarityThresholdAll()
+				.filterExpression("country not in ['BG']")
+				.build());
 
 			assertThat(results).hasSize(1);
 			assertThat(results.get(0).getId()).isEqualTo(nlDocument.getId());
 
-			results = vectorStore.similaritySearch(SearchRequest.query("The World")
-				.withTopK(5)
-				.withSimilarityThresholdAll()
-				.withFilterExpression("NOT(country not in ['BG'])"));
+			results = vectorStore.similaritySearch(SearchRequest.builder()
+				.query("The World")
+				.topK(5)
+				.similarityThresholdAll()
+				.filterExpression("NOT(country not in ['BG'])")
+				.build());
 
 			assertThat(results).hasSize(2);
 			assertThat(results.get(0).getId()).isIn(bgDocument.getId(), bgDocument2.getId());
 			assertThat(results.get(1).getId()).isIn(bgDocument.getId(), bgDocument2.getId());
 
-			results = vectorStore.similaritySearch(SearchRequest.query("The World")
-				.withTopK(5)
-				.withSimilarityThresholdAll()
-				.withFilterExpression(
-						"activationDate > " + ZonedDateTime.parse("1970-01-01T00:00:02Z").toInstant().toEpochMilli()));
+			results = vectorStore.similaritySearch(SearchRequest.builder()
+				.query("The World")
+				.topK(5)
+				.similarityThresholdAll()
+				.filterExpression(
+						"activationDate > " + ZonedDateTime.parse("1970-01-01T00:00:02Z").toInstant().toEpochMilli())
+				.build());
 
 			assertThat(results).hasSize(1);
 			assertThat(results.get(0).getId()).isEqualTo(bgDocument2.getId());
@@ -253,7 +270,8 @@ class OpenSearchVectorStoreIT {
 			vectorStore.delete(this.documents.stream().map(Document::getId).toList());
 
 			Awaitility.await()
-				.until(() -> vectorStore.similaritySearch(SearchRequest.query("The World").withTopK(1)), hasSize(0));
+				.until(() -> vectorStore.similaritySearch(SearchRequest.builder().query("The World").topK(1).build()),
+						hasSize(0));
 		});
 	}
 
@@ -273,11 +291,11 @@ class OpenSearchVectorStoreIT {
 
 			Awaitility.await()
 				.until(() -> vectorStore
-					.similaritySearch(SearchRequest.query("Spring").withSimilarityThreshold(0).withTopK(5)),
+					.similaritySearch(SearchRequest.builder().query("Spring").similarityThreshold(0).topK(5).build()),
 						hasSize(1));
 
 			List<Document> results = vectorStore
-				.similaritySearch(SearchRequest.query("Spring").withSimilarityThreshold(0).withTopK(5));
+				.similaritySearch(SearchRequest.builder().query("Spring").similarityThreshold(0).topK(5).build());
 
 			assertThat(results).hasSize(1);
 			Document resultDoc = results.get(0);
@@ -290,7 +308,7 @@ class OpenSearchVectorStoreIT {
 					"The World is Big and Salvation Lurks Around the Corner", Map.of("meta2", "meta2"));
 
 			vectorStore.add(List.of(sameIdDocument));
-			SearchRequest fooBarSearchRequest = SearchRequest.query("FooBar").withTopK(5);
+			SearchRequest fooBarSearchRequest = SearchRequest.builder().query("FooBar").topK(5).build();
 
 			Awaitility.await()
 				.until(() -> vectorStore.similaritySearch(fooBarSearchRequest).get(0).getContent(),
@@ -325,9 +343,11 @@ class OpenSearchVectorStoreIT {
 
 			vectorStore.add(this.documents);
 
-			SearchRequest query = SearchRequest.query("Great Depression")
-				.withTopK(50)
-				.withSimilarityThreshold(SearchRequest.SIMILARITY_THRESHOLD_ACCEPT_ALL);
+			SearchRequest query = SearchRequest.builder()
+				.query("Great Depression")
+				.topK(50)
+				.similarityThreshold(SearchRequest.SIMILARITY_THRESHOLD_ACCEPT_ALL)
+				.build();
 
 			Awaitility.await().until(() -> vectorStore.similaritySearch(query), hasSize(3));
 
@@ -339,8 +359,11 @@ class OpenSearchVectorStoreIT {
 
 			double similarityThreshold = (scores.get(0) + scores.get(1)) / 2;
 
-			List<Document> results = vectorStore.similaritySearch(
-					SearchRequest.query("Great Depression").withTopK(50).withSimilarityThreshold(similarityThreshold));
+			List<Document> results = vectorStore.similaritySearch(SearchRequest.builder()
+				.query("Great Depression")
+				.topK(50)
+				.similarityThreshold(similarityThreshold)
+				.build());
 
 			assertThat(results).hasSize(1);
 			Document resultDoc = results.get(0);
@@ -354,8 +377,8 @@ class OpenSearchVectorStoreIT {
 			vectorStore.delete(this.documents.stream().map(Document::getId).toList());
 
 			Awaitility.await()
-				.until(() -> vectorStore
-					.similaritySearch(SearchRequest.query("Great Depression").withTopK(50).withSimilarityThreshold(0)),
+				.until(() -> vectorStore.similaritySearch(
+						SearchRequest.builder().query("Great Depression").topK(50).similarityThreshold(0).build()),
 						hasSize(0));
 		});
 	}
@@ -375,11 +398,11 @@ class OpenSearchVectorStoreIT {
 			vectorStore1.add(List.of(docInIndex1));
 			vectorStore2.add(List.of(docInIndex2));
 
-			List<Document> resultInIndex1 = vectorStore1
-				.similaritySearch(SearchRequest.query("Document in index 1").withTopK(1).withSimilarityThreshold(0));
+			List<Document> resultInIndex1 = vectorStore1.similaritySearch(
+					SearchRequest.builder().query("Document in index 1").topK(1).similarityThreshold(0).build());
 
-			List<Document> resultInIndex2 = vectorStore2
-				.similaritySearch(SearchRequest.query("Document in index 2").withTopK(1).withSimilarityThreshold(0));
+			List<Document> resultInIndex2 = vectorStore2.similaritySearch(
+					SearchRequest.builder().query("Document in index 2").topK(1).similarityThreshold(0).build());
 
 			// then
 			assertThat(resultInIndex1).hasSize(1);

vector-stores/spring-ai-opensearch-store/src/test/java/org/springframework/ai/vectorstore/opensearch/OpenSearchVectorStoreObservationIT.java

@@ -144,14 +144,14 @@ public class OpenSearchVectorStoreObservationIT {
 				.hasBeenStopped();
 
 			Awaitility.await()
-				.until(() -> vectorStore
-					.similaritySearch(SearchRequest.query("Great Depression").withTopK(1).withSimilarityThreshold(0)),
+				.until(() -> vectorStore.similaritySearch(
+						SearchRequest.builder().query("Great Depression").topK(1).similarityThreshold(0).build()),
 						hasSize(1));
 
 			observationRegistry.clear();
 
 			List<Document> results = vectorStore
-				.similaritySearch(SearchRequest.query("What is Great Depression").withTopK(1));
+				.similaritySearch(SearchRequest.builder().query("What is Great Depression").topK(1).build());
 
 			assertThat(results).isNotEmpty();
 
@@ -187,8 +187,8 @@ public class OpenSearchVectorStoreObservationIT {
 			vectorStore.delete(this.documents.stream().map(Document::getId).toList());
 
 			Awaitility.await()
-				.until(() -> vectorStore
-					.similaritySearch(SearchRequest.query("Great Depression").withTopK(1).withSimilarityThreshold(0)),
+				.until(() -> vectorStore.similaritySearch(
+						SearchRequest.builder().query("Great Depression").topK(1).similarityThreshold(0).build()),
 						hasSize(0));
 
 		});

vector-stores/spring-ai-opensearch-store/src/test/java/org/springframework/ai/vectorstore/opensearch/OpenSearchVectorStoreWithOllamaIT.java

@@ -137,12 +137,12 @@ class OpenSearchVectorStoreWithOllamaIT {
 			vectorStore.add(this.documents);
 
 			Awaitility.await()
-				.until(() -> vectorStore
-					.similaritySearch(SearchRequest.query("Great Depression").withTopK(1).withSimilarityThreshold(0)),
+				.until(() -> vectorStore.similaritySearch(
+						SearchRequest.builder().query("Great Depression").topK(1).similarityThreshold(0).build()),
 						hasSize(1));
 
-			List<Document> results = vectorStore
-				.similaritySearch(SearchRequest.query("Great Depression").withTopK(1).withSimilarityThreshold(0));
+			List<Document> results = vectorStore.similaritySearch(
+					SearchRequest.builder().query("Great Depression").topK(1).similarityThreshold(0).build());
 
 			assertThat(results).hasSize(1);
 			Document resultDoc = results.get(0);
@@ -156,8 +156,8 @@ class OpenSearchVectorStoreWithOllamaIT {
 			vectorStore.delete(this.documents.stream().map(Document::getId).toList());
 
 			Awaitility.await()
-				.until(() -> vectorStore
-					.similaritySearch(SearchRequest.query("Great Depression").withTopK(1).withSimilarityThreshold(0)),
+				.until(() -> vectorStore.similaritySearch(
+						SearchRequest.builder().query("Great Depression").topK(1).similarityThreshold(0).build()),
 						hasSize(0));
 		});
 	}

vector-stores/spring-ai-oracle-store/src/test/java/org/springframework/ai/vectorstore/oracle/OracleVectorStoreIT.java

@@ -130,7 +130,7 @@ public class OracleVectorStoreIT {
 				vectorStore.add(this.documents);
 
 				List<Document> results = vectorStore
-					.similaritySearch(SearchRequest.query("What is Great Depression").withTopK(1));
+					.similaritySearch(SearchRequest.builder().query("What is Great Depression").topK(1).build());
 
 				assertThat(results).hasSize(1);
 				Document resultDoc = results.get(0);
@@ -141,7 +141,7 @@ public class OracleVectorStoreIT {
 				vectorStore.delete(this.documents.stream().map(doc -> doc.getId()).toList());
 
 				List<Document> results2 = vectorStore
-					.similaritySearch(SearchRequest.query("Great Depression").withTopK(1));
+					.similaritySearch(SearchRequest.builder().query("Great Depression").topK(1).build());
 				assertThat(results2).hasSize(0);
 
 				dropTable(context, ((OracleVectorStore) vectorStore).getTableName());
@@ -167,51 +167,62 @@ public class OracleVectorStoreIT {
 
 				vectorStore.add(List.of(bgDocument, nlDocument, bgDocument2));
 
-				SearchRequest searchRequest = SearchRequest.query("The World").withTopK(5).withSimilarityThresholdAll();
+				SearchRequest searchRequest = SearchRequest.builder()
+					.query("The World")
+					.topK(5)
+					.similarityThresholdAll()
+					.build();
 
 				List<Document> results = vectorStore.similaritySearch(searchRequest);
 
 				assertThat(results).hasSize(3);
 
-				results = vectorStore.similaritySearch(searchRequest.withFilterExpression("country == 'NL'"));
+				results = vectorStore
+					.similaritySearch(SearchRequest.from(searchRequest).filterExpression("country == 'NL'").build());
 
 				assertThat(results).hasSize(1);
 				assertThat(results.get(0).getId()).isEqualTo(nlDocument.getId());
 
-				results = vectorStore.similaritySearch(searchRequest.withFilterExpression("country == 'BG'"));
+				results = vectorStore
+					.similaritySearch(SearchRequest.from(searchRequest).filterExpression("country == 'BG'").build());
 
 				assertThat(results).hasSize(2);
 				assertThat(results.get(0).getId()).isIn(bgDocument.getId(), bgDocument2.getId());
 				assertThat(results.get(1).getId()).isIn(bgDocument.getId(), bgDocument2.getId());
 
-				results = vectorStore
-					.similaritySearch(searchRequest.withFilterExpression("country == 'BG' && year == 2020"));
+				results = vectorStore.similaritySearch(
+						SearchRequest.from(searchRequest).filterExpression("country == 'BG' && year == 2020").build());
 
 				assertThat(results).hasSize(1);
 				assertThat(results.get(0).getId()).isEqualTo(bgDocument.getId());
 
-				results = vectorStore.similaritySearch(
-						searchRequest.withFilterExpression("(country == 'BG' && year == 2020) || (country == 'NL')"));
+				results = vectorStore.similaritySearch(SearchRequest.from(searchRequest)
+					.filterExpression("(country == 'BG' && year == 2020) || (country == 'NL')")
+					.build());
 
 				assertThat(results).hasSize(2);
 				assertThat(results.get(0).getId()).isIn(bgDocument.getId(), nlDocument.getId());
 				assertThat(results.get(1).getId()).isIn(bgDocument.getId(), nlDocument.getId());
 
-				results = vectorStore.similaritySearch(searchRequest
-					.withFilterExpression("NOT((country == 'BG' && year == 2020) || (country == 'NL'))"));
+				results = vectorStore.similaritySearch(SearchRequest.from(searchRequest)
+					.filterExpression("NOT((country == 'BG' && year == 2020) || (country == 'NL'))")
+					.build());
 
 				assertThat(results).hasSize(1);
 				assertThat(results.get(0).getId()).isEqualTo(bgDocument2.getId());
 
-				results = vectorStore.similaritySearch(SearchRequest.query("The World")
-					.withTopK(5)
-					.withSimilarityThresholdAll()
-					.withFilterExpression("\"foo bar 1\" == 'bar.foo'"));
+				results = vectorStore.similaritySearch(SearchRequest.builder()
+					.query("The World")
+					.topK(5)
+					.similarityThresholdAll()
+					.filterExpression("\"foo bar 1\" == 'bar.foo'")
+					.build());
 				assertThat(results).hasSize(1);
 				assertThat(results.get(0).getId()).isEqualTo(bgDocument.getId());
 
 				try {
-					vectorStore.similaritySearch(searchRequest.withFilterExpression("country == NL"));
+					vectorStore
+						.similaritySearch(SearchRequest.from(searchRequest).filterExpression("country == NL").build());
 					Assert.fail("Invalid filter expression should have been cached!");
 				}
 				catch (FilterExpressionTextParser.FilterExpressionParseException e) {
@@ -237,7 +248,8 @@ public class OracleVectorStoreIT {
 
 				vectorStore.add(List.of(document));
 
-				List<Document> results = vectorStore.similaritySearch(SearchRequest.query("Spring").withTopK(5));
+				List<Document> results = vectorStore
+					.similaritySearch(SearchRequest.builder().query("Spring").topK(5).build());
 
 				assertThat(results).hasSize(1);
 				Document resultDoc = results.get(0);
@@ -252,7 +264,7 @@ public class OracleVectorStoreIT {
 
 				vectorStore.add(List.of(sameIdDocument));
 
-				results = vectorStore.similaritySearch(SearchRequest.query("FooBar").withTopK(5));
+				results = vectorStore.similaritySearch(SearchRequest.builder().query("FooBar").topK(5).build());
 				assertThat(results).hasSize(1);
 				resultDoc = results.get(0);
 				assertThat(resultDoc.getId()).isEqualTo(document.getId());
@@ -275,8 +287,8 @@ public class OracleVectorStoreIT {
 
 				vectorStore.add(this.documents);
 
-				List<Document> fullResult = vectorStore
-					.similaritySearch(SearchRequest.query("Time Shelter").withTopK(5).withSimilarityThresholdAll());
+				List<Document> fullResult = vectorStore.similaritySearch(
+						SearchRequest.builder().query("Time Shelter").topK(5).similarityThresholdAll().build());
 
 				assertThat(fullResult).hasSize(3);
 
@@ -286,8 +298,11 @@ public class OracleVectorStoreIT {
 
 				double similarityThreshold = (scores.get(0) + scores.get(1)) / 2d;
 
-				List<Document> results = vectorStore.similaritySearch(
-						SearchRequest.query("Time Shelter").withTopK(5).withSimilarityThreshold(similarityThreshold));
+				List<Document> results = vectorStore.similaritySearch(SearchRequest.builder()
+					.query("Time Shelter")
+					.topK(5)
+					.similarityThreshold(similarityThreshold)
+					.build());
 
 				assertThat(results).hasSize(1);
 				Document resultDoc = results.get(0);

vector-stores/spring-ai-oracle-store/src/test/java/org/springframework/ai/vectorstore/oracle/OracleVectorStoreObservationIT.java

@@ -139,7 +139,7 @@ public class OracleVectorStoreObservationIT {
 			observationRegistry.clear();
 
 			List<Document> results = vectorStore
-				.similaritySearch(SearchRequest.query("What is Great Depression").withTopK(1));
+				.similaritySearch(SearchRequest.builder().query("What is Great Depression").topK(1).build());
 
 			assertThat(results).isNotEmpty();
 

vector-stores/spring-ai-pgvector-store/src/test/java/org/springframework/ai/vectorstore/pgvector/PgVectorStoreIT.java

@@ -148,7 +148,7 @@ public class PgVectorStoreIT {
 				vectorStore.add(this.documents);
 
 				List<Document> results = vectorStore
-					.similaritySearch(SearchRequest.query("What is Great Depression").withTopK(1));
+					.similaritySearch(SearchRequest.builder().query("What is Great Depression").topK(1).build());
 
 				assertThat(results).hasSize(1);
 				Document resultDoc = results.get(0);
@@ -159,7 +159,7 @@ public class PgVectorStoreIT {
 				vectorStore.delete(this.documents.stream().map(doc -> doc.getId()).toList());
 
 				List<Document> results2 = vectorStore
-					.similaritySearch(SearchRequest.query("Great Depression").withTopK(1));
+					.similaritySearch(SearchRequest.builder().query("Great Depression").topK(1).build());
 				assertThat(results2).hasSize(0);
 
 				dropTable(context);
@@ -184,10 +184,12 @@ public class PgVectorStoreIT {
 
 				vectorStore.add(List.of(bgDocument, nlDocument, bgDocument2));
 
-				SearchRequest searchRequest = SearchRequest.query("The World")
-					.withFilterExpression(expression)
-					.withTopK(5)
-					.withSimilarityThresholdAll();
+				SearchRequest searchRequest = SearchRequest.builder()
+					.query("The World")
+					.filterExpression(expression)
+					.topK(5)
+					.similarityThresholdAll()
+					.build();
 
 				List<Document> results = vectorStore.similaritySearch(searchRequest);
 
@@ -216,51 +218,62 @@ public class PgVectorStoreIT {
 
 				vectorStore.add(List.of(bgDocument, nlDocument, bgDocument2));
 
-				SearchRequest searchRequest = SearchRequest.query("The World").withTopK(5).withSimilarityThresholdAll();
+				SearchRequest searchRequest = SearchRequest.builder()
+					.query("The World")
+					.topK(5)
+					.similarityThresholdAll()
+					.build();
 
 				List<Document> results = vectorStore.similaritySearch(searchRequest);
 
 				assertThat(results).hasSize(3);
 
-				results = vectorStore.similaritySearch(searchRequest.withFilterExpression("country == 'NL'"));
+				results = vectorStore
+					.similaritySearch(SearchRequest.from(searchRequest).filterExpression("country == 'NL'").build());
 
 				assertThat(results).hasSize(1);
 				assertThat(results.get(0).getId()).isEqualTo(nlDocument.getId());
 
-				results = vectorStore.similaritySearch(searchRequest.withFilterExpression("country == 'BG'"));
+				results = vectorStore
+					.similaritySearch(SearchRequest.from(searchRequest).filterExpression("country == 'BG'").build());
 
 				assertThat(results).hasSize(2);
 				assertThat(results.get(0).getId()).isIn(bgDocument.getId(), bgDocument2.getId());
 				assertThat(results.get(1).getId()).isIn(bgDocument.getId(), bgDocument2.getId());
 
-				results = vectorStore
-					.similaritySearch(searchRequest.withFilterExpression("country == 'BG' && year == 2020"));
+				results = vectorStore.similaritySearch(
+						SearchRequest.from(searchRequest).filterExpression("country == 'BG' && year == 2020").build());
 
 				assertThat(results).hasSize(1);
 				assertThat(results.get(0).getId()).isEqualTo(bgDocument.getId());
 
-				results = vectorStore.similaritySearch(
-						searchRequest.withFilterExpression("(country == 'BG' && year == 2020) || (country == 'NL')"));
+				results = vectorStore.similaritySearch(SearchRequest.from(searchRequest)
+					.filterExpression("(country == 'BG' && year == 2020) || (country == 'NL')")
+					.build());
 
 				assertThat(results).hasSize(2);
 				assertThat(results.get(0).getId()).isIn(bgDocument.getId(), nlDocument.getId());
 				assertThat(results.get(1).getId()).isIn(bgDocument.getId(), nlDocument.getId());
 
-				results = vectorStore.similaritySearch(searchRequest
-					.withFilterExpression("NOT((country == 'BG' && year == 2020) || (country == 'NL'))"));
+				results = vectorStore.similaritySearch(SearchRequest.from(searchRequest)
+					.filterExpression("NOT((country == 'BG' && year == 2020) || (country == 'NL'))")
+					.build());
 
 				assertThat(results).hasSize(1);
 				assertThat(results.get(0).getId()).isEqualTo(bgDocument2.getId());
 
-				results = vectorStore.similaritySearch(SearchRequest.query("The World")
-					.withTopK(5)
-					.withSimilarityThresholdAll()
-					.withFilterExpression("\"foo bar 1\" == 'bar.foo'"));
+				results = vectorStore.similaritySearch(SearchRequest.builder()
+					.query("The World")
+					.topK(5)
+					.similarityThresholdAll()
+					.filterExpression("\"foo bar 1\" == 'bar.foo'")
+					.build());
 				assertThat(results).hasSize(1);
 				assertThat(results.get(0).getId()).isEqualTo(bgDocument.getId());
 
 				try {
-					vectorStore.similaritySearch(searchRequest.withFilterExpression("country == NL"));
+					vectorStore
+						.similaritySearch(SearchRequest.from(searchRequest).filterExpression("country == NL").build());
 					Assert.fail("Invalid filter expression should have been cached!");
 				}
 				catch (FilterExpressionParseException e) {
@@ -286,7 +299,8 @@ public class PgVectorStoreIT {
 
 				vectorStore.add(List.of(document));
 
-				List<Document> results = vectorStore.similaritySearch(SearchRequest.query("Spring").withTopK(5));
+				List<Document> results = vectorStore
+					.similaritySearch(SearchRequest.builder().query("Spring").topK(5).build());
 
 				assertThat(results).hasSize(1);
 				Document resultDoc = results.get(0);
@@ -300,7 +314,7 @@ public class PgVectorStoreIT {
 
 				vectorStore.add(List.of(sameIdDocument));
 
-				results = vectorStore.similaritySearch(SearchRequest.query("FooBar").withTopK(5));
+				results = vectorStore.similaritySearch(SearchRequest.builder().query("FooBar").topK(5).build());
 
 				assertThat(results).hasSize(1);
 				resultDoc = results.get(0);
@@ -324,8 +338,8 @@ public class PgVectorStoreIT {
 
 				vectorStore.add(this.documents);
 
-				List<Document> fullResult = vectorStore
-					.similaritySearch(SearchRequest.query("Time Shelter").withTopK(5).withSimilarityThresholdAll());
+				List<Document> fullResult = vectorStore.similaritySearch(
+						SearchRequest.builder().query("Time Shelter").topK(5).similarityThresholdAll().build());
 
 				assertThat(fullResult).hasSize(3);
 
@@ -335,8 +349,11 @@ public class PgVectorStoreIT {
 
 				double similarityThreshold = (scores.get(0) + scores.get(1)) / 2;
 
-				List<Document> results = vectorStore.similaritySearch(
-						SearchRequest.query("Time Shelter").withTopK(5).withSimilarityThreshold(similarityThreshold));
+				List<Document> results = vectorStore.similaritySearch(SearchRequest.builder()
+					.query("Time Shelter")
+					.topK(5)
+					.similarityThreshold(similarityThreshold)
+					.build());
 
 				assertThat(results).hasSize(1);
 				Document resultDoc = results.get(0);

vector-stores/spring-ai-pgvector-store/src/test/java/org/springframework/ai/vectorstore/pgvector/PgVectorStoreObservationIT.java

@@ -141,7 +141,7 @@ public class PgVectorStoreObservationIT {
 			observationRegistry.clear();
 
 			List<Document> results = vectorStore
-				.similaritySearch(SearchRequest.query("What is Great Depression").withTopK(1));
+				.similaritySearch(SearchRequest.builder().query("What is Great Depression").topK(1).build());
 
 			assertThat(results).isNotEmpty();
 

vector-stores/spring-ai-pinecone-store/src/test/java/org/springframework/ai/vectorstore/pinecone/PineconeVectorStoreIT.java

@@ -102,10 +102,11 @@ public class PineconeVectorStoreIT {
 			vectorStore.add(this.documents);
 
 			Awaitility.await()
-				.until(() -> vectorStore.similaritySearch(SearchRequest.query("Great Depression").withTopK(1)),
-						hasSize(1));
+				.until(() -> vectorStore
+					.similaritySearch(SearchRequest.builder().query("Great Depression").topK(1).build()), hasSize(1));
 
-			List<Document> results = vectorStore.similaritySearch(SearchRequest.query("Great Depression").withTopK(1));
+			List<Document> results = vectorStore
+				.similaritySearch(SearchRequest.builder().query("Great Depression").topK(1).build());
 
 			assertThat(results).hasSize(1);
 			Document resultDoc = results.get(0);
@@ -119,7 +120,8 @@ public class PineconeVectorStoreIT {
 			vectorStore.delete(this.documents.stream().map(doc -> doc.getId()).toList());
 
 			Awaitility.await()
-				.until(() -> vectorStore.similaritySearch(SearchRequest.query("Hello").withTopK(1)), hasSize(0));
+				.until(() -> vectorStore.similaritySearch(SearchRequest.builder().query("Hello").topK(1).build()),
+						hasSize(0));
 		});
 	}
 
@@ -140,28 +142,36 @@ public class PineconeVectorStoreIT {
 
 			vectorStore.add(List.of(bgDocument, nlDocument));
 
-			SearchRequest searchRequest = SearchRequest.query("The World");
+			SearchRequest searchRequest = SearchRequest.builder().query("The World").build();
 
-			Awaitility.await().until(() -> vectorStore.similaritySearch(searchRequest.withTopK(1)), hasSize(1));
+			Awaitility.await()
+				.until(() -> vectorStore.similaritySearch(SearchRequest.from(searchRequest).topK(1).build()),
+						hasSize(1));
 
-			List<Document> results = vectorStore.similaritySearch(searchRequest.withTopK(5));
+			List<Document> results = vectorStore.similaritySearch(SearchRequest.from(searchRequest).topK(5).build());
 			assertThat(results).hasSize(2);
 
-			results = vectorStore.similaritySearch(searchRequest.withTopK(5)
-				.withSimilarityThresholdAll()
-				.withFilterExpression("country == 'Bulgaria'"));
+			results = vectorStore.similaritySearch(SearchRequest.from(searchRequest)
+				.topK(5)
+				.similarityThresholdAll()
+				.filterExpression("country == 'Bulgaria'")
+				.build());
 			assertThat(results).hasSize(1);
 			assertThat(results.get(0).getId()).isEqualTo(bgDocument.getId());
 
-			results = vectorStore.similaritySearch(searchRequest.withTopK(5)
-				.withSimilarityThresholdAll()
-				.withFilterExpression("country == 'Netherlands'"));
+			results = vectorStore.similaritySearch(SearchRequest.from(searchRequest)
+				.topK(5)
+				.similarityThresholdAll()
+				.filterExpression("country == 'Netherlands'")
+				.build());
 			assertThat(results).hasSize(1);
 			assertThat(results.get(0).getId()).isEqualTo(nlDocument.getId());
 
-			results = vectorStore.similaritySearch(searchRequest.withTopK(5)
-				.withSimilarityThresholdAll()
-				.withFilterExpression("NOT(country == 'Netherlands')"));
+			results = vectorStore.similaritySearch(SearchRequest.from(searchRequest)
+				.topK(5)
+				.similarityThresholdAll()
+				.filterExpression("NOT(country == 'Netherlands')")
+				.build());
 
 			assertThat(results).hasSize(1);
 			assertThat(results.get(0).getId()).isEqualTo(bgDocument.getId());
@@ -169,7 +179,9 @@ public class PineconeVectorStoreIT {
 			// Remove all documents from the store
 			vectorStore.delete(List.of(bgDocument, nlDocument).stream().map(doc -> doc.getId()).toList());
 
-			Awaitility.await().until(() -> vectorStore.similaritySearch(searchRequest.withTopK(1)), hasSize(0));
+			Awaitility.await()
+				.until(() -> vectorStore.similaritySearch(SearchRequest.from(searchRequest).topK(1).build()),
+						hasSize(0));
 		});
 	}
 
@@ -186,7 +198,7 @@ public class PineconeVectorStoreIT {
 
 			vectorStore.add(List.of(document));
 
-			SearchRequest springSearchRequest = SearchRequest.query("Spring").withTopK(5);
+			SearchRequest springSearchRequest = SearchRequest.builder().query("Spring").topK(5).build();
 
 			Awaitility.await().until(() -> vectorStore.similaritySearch(springSearchRequest), hasSize(1));
 
@@ -205,7 +217,7 @@ public class PineconeVectorStoreIT {
 
 			vectorStore.add(List.of(sameIdDocument));
 
-			SearchRequest fooBarSearchRequest = SearchRequest.query("FooBar").withTopK(5);
+			SearchRequest fooBarSearchRequest = SearchRequest.builder().query("FooBar").topK(5).build();
 
 			Awaitility.await()
 				.until(() -> vectorStore.similaritySearch(fooBarSearchRequest).get(0).getContent(),
@@ -237,12 +249,12 @@ public class PineconeVectorStoreIT {
 			vectorStore.add(this.documents);
 
 			Awaitility.await()
-				.until(() -> vectorStore
-					.similaritySearch(SearchRequest.query("Depression").withTopK(50).withSimilarityThresholdAll()),
+				.until(() -> vectorStore.similaritySearch(
+						SearchRequest.builder().query("Depression").topK(50).similarityThresholdAll().build()),
 						hasSize(3));
 
 			List<Document> fullResult = vectorStore
-				.similaritySearch(SearchRequest.query("Depression").withTopK(5).withSimilarityThresholdAll());
+				.similaritySearch(SearchRequest.builder().query("Depression").topK(5).similarityThresholdAll().build());
 
 			List<Double> scores = fullResult.stream().map(Document::getScore).toList();
 
@@ -250,8 +262,11 @@ public class PineconeVectorStoreIT {
 
 			double similarityThreshold = (scores.get(0) + scores.get(1)) / 2;
 
-			List<Document> results = vectorStore.similaritySearch(
-					SearchRequest.query("Depression").withTopK(5).withSimilarityThreshold(similarityThreshold));
+			List<Document> results = vectorStore.similaritySearch(SearchRequest.builder()
+				.query("Depression")
+				.topK(5)
+				.similarityThreshold(similarityThreshold)
+				.build());
 
 			assertThat(results).hasSize(1);
 			Document resultDoc = results.get(0);
@@ -264,7 +279,8 @@ public class PineconeVectorStoreIT {
 			// Remove all documents from the store
 			vectorStore.delete(this.documents.stream().map(doc -> doc.getId()).toList());
 			Awaitility.await()
-				.until(() -> vectorStore.similaritySearch(SearchRequest.query("Hello").withTopK(1)), hasSize(0));
+				.until(() -> vectorStore.similaritySearch(SearchRequest.builder().query("Hello").topK(1).build()),
+						hasSize(0));
 		});
 	}
 

vector-stores/spring-ai-pinecone-store/src/test/java/org/springframework/ai/vectorstore/pinecone/PineconeVectorStoreObservationIT.java

@@ -131,13 +131,14 @@ public class PineconeVectorStoreObservationIT {
 				.hasBeenStopped();
 
 			Awaitility.await()
-				.until(() -> vectorStore.similaritySearch(SearchRequest.query("What is Great Depression").withTopK(1)),
+				.until(() -> vectorStore
+					.similaritySearch(SearchRequest.builder().query("What is Great Depression").topK(1).build()),
 						hasSize(1));
 
 			observationRegistry.clear();
 
 			List<Document> results = vectorStore
-				.similaritySearch(SearchRequest.query("What is Great Depression").withTopK(1));
+				.similaritySearch(SearchRequest.builder().query("What is Great Depression").topK(1).build());
 
 			assertThat(results).isNotEmpty();
 
@@ -171,7 +172,8 @@ public class PineconeVectorStoreObservationIT {
 			vectorStore.delete(this.documents.stream().map(doc -> doc.getId()).toList());
 
 			Awaitility.await()
-				.until(() -> vectorStore.similaritySearch(SearchRequest.query("Hello").withTopK(1)), hasSize(0));
+				.until(() -> vectorStore.similaritySearch(SearchRequest.builder().query("Hello").topK(1).build()),
+						hasSize(0));
 
 		});
 	}

vector-stores/spring-ai-qdrant-store/src/test/java/org/springframework/ai/vectorstore/qdrant/QdrantVectorStoreIT.java

@@ -30,12 +30,12 @@ import org.junit.jupiter.api.BeforeAll;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.condition.EnabledIfEnvironmentVariable;
 import org.junit.jupiter.api.condition.EnabledIfEnvironmentVariables;
-import org.springframework.ai.document.DocumentMetadata;
 import org.testcontainers.junit.jupiter.Container;
 import org.testcontainers.junit.jupiter.Testcontainers;
 import org.testcontainers.qdrant.QdrantContainer;
 
 import org.springframework.ai.document.Document;
+import org.springframework.ai.document.DocumentMetadata;
 import org.springframework.ai.embedding.EmbeddingModel;
 import org.springframework.ai.mistralai.MistralAiEmbeddingModel;
 import org.springframework.ai.mistralai.api.MistralAiApi;
@@ -101,7 +101,8 @@ public class QdrantVectorStoreIT {
 
 			vectorStore.add(this.documents);
 
-			List<Document> results = vectorStore.similaritySearch(SearchRequest.query("Great").withTopK(1));
+			List<Document> results = vectorStore
+				.similaritySearch(SearchRequest.builder().query("Great").topK(1).build());
 
 			assertThat(results).hasSize(1);
 			Document resultDoc = results.get(0);
@@ -113,7 +114,8 @@ public class QdrantVectorStoreIT {
 			// Remove all documents from the store
 			vectorStore.delete(this.documents.stream().map(doc -> doc.getId()).toList());
 
-			List<Document> results2 = vectorStore.similaritySearch(SearchRequest.query("Great").withTopK(1));
+			List<Document> results2 = vectorStore
+				.similaritySearch(SearchRequest.builder().query("Great").topK(1).build());
 			assertThat(results2).hasSize(0);
 		});
 	}
@@ -132,33 +134,43 @@ public class QdrantVectorStoreIT {
 
 			vectorStore.add(List.of(bgDocument, nlDocument));
 
-			var request = SearchRequest.query("The World").withTopK(5);
+			var request = SearchRequest.builder().query("The World").topK(5).build();
 
 			List<Document> results = vectorStore.similaritySearch(request);
 			assertThat(results).hasSize(2);
 
-			results = vectorStore
-				.similaritySearch(request.withSimilarityThresholdAll().withFilterExpression("country == 'Bulgaria'"));
+			results = vectorStore.similaritySearch(SearchRequest.from(request)
+				.similarityThresholdAll()
+				.filterExpression("country == 'Bulgaria'")
+				.build());
 			assertThat(results).hasSize(1);
 			assertThat(results.get(0).getId()).isEqualTo(bgDocument.getId());
 
-			results = vectorStore.similaritySearch(
-					request.withSimilarityThresholdAll().withFilterExpression("country == 'Netherlands'"));
+			results = vectorStore.similaritySearch(SearchRequest.from(request)
+				.similarityThresholdAll()
+				.filterExpression("country == 'Netherlands'")
+				.build());
 			assertThat(results).hasSize(1);
 			assertThat(results.get(0).getId()).isEqualTo(nlDocument.getId());
 
-			results = vectorStore.similaritySearch(
-					request.withSimilarityThresholdAll().withFilterExpression("NOT(country == 'Netherlands')"));
+			results = vectorStore.similaritySearch(SearchRequest.from(request)
+				.similarityThresholdAll()
+				.filterExpression("NOT(country == 'Netherlands')")
+				.build());
 			assertThat(results).hasSize(1);
 			assertThat(results.get(0).getId()).isEqualTo(bgDocument.getId());
 
-			results = vectorStore
-				.similaritySearch(request.withSimilarityThresholdAll().withFilterExpression("number in [3, 5, 12]"));
+			results = vectorStore.similaritySearch(SearchRequest.from(request)
+				.similarityThresholdAll()
+				.filterExpression("number in [3, 5, 12]")
+				.build());
 			assertThat(results).hasSize(1);
 			assertThat(results.get(0).getId()).isEqualTo(bgDocument.getId());
 
-			results = vectorStore
-				.similaritySearch(request.withSimilarityThresholdAll().withFilterExpression("number nin [3, 5, 12]"));
+			results = vectorStore.similaritySearch(SearchRequest.from(request)
+				.similarityThresholdAll()
+				.filterExpression("number nin [3, 5, 12]")
+				.build());
 			assertThat(results).hasSize(1);
 			assertThat(results.get(0).getId()).isEqualTo(nlDocument.getId());
 
@@ -179,7 +191,8 @@ public class QdrantVectorStoreIT {
 
 			vectorStore.add(List.of(document));
 
-			List<Document> results = vectorStore.similaritySearch(SearchRequest.query("Spring").withTopK(5));
+			List<Document> results = vectorStore
+				.similaritySearch(SearchRequest.builder().query("Spring").topK(5).build());
 
 			assertThat(results).hasSize(1);
 			Document resultDoc = results.get(0);
@@ -194,7 +207,7 @@ public class QdrantVectorStoreIT {
 
 			vectorStore.add(List.of(sameIdDocument));
 
-			results = vectorStore.similaritySearch(SearchRequest.query("FooBar").withTopK(5));
+			results = vectorStore.similaritySearch(SearchRequest.builder().query("FooBar").topK(5).build());
 
 			assertThat(results).hasSize(1);
 			resultDoc = results.get(0);
@@ -216,8 +229,9 @@ public class QdrantVectorStoreIT {
 
 			vectorStore.add(this.documents);
 
-			var request = SearchRequest.query("Great").withTopK(5);
-			List<Document> fullResult = vectorStore.similaritySearch(request.withSimilarityThresholdAll());
+			var request = SearchRequest.builder().query("Great").topK(5).build();
+			List<Document> fullResult = vectorStore
+				.similaritySearch(SearchRequest.from(request).similarityThresholdAll().build());
 
 			List<Double> scores = fullResult.stream().map(Document::getScore).toList();
 
@@ -225,7 +239,8 @@ public class QdrantVectorStoreIT {
 
 			double similarityThreshold = (scores.get(0) + scores.get(1)) / 2;
 
-			List<Document> results = vectorStore.similaritySearch(request.withSimilarityThreshold(similarityThreshold));
+			List<Document> results = vectorStore
+				.similaritySearch(SearchRequest.from(request).similarityThreshold(similarityThreshold).build());
 
 			assertThat(results).hasSize(1);
 			Document resultDoc = results.get(0);