Package org.springframework.ai.vectorstore

Class SearchRequest

java.lang.Object
org.springframework.ai.vectorstore.SearchRequest
public final class SearchRequest extends Object
Similarity search request builder. Use the query(String), defaults() or from(SearchRequest) factory methods to create a new SearchRequest instance and then apply the 'with' methods to alter the default values.
Author:
Christian Tzolov

  • Field Details

    • SIMILARITY_THRESHOLD_ACCEPT_ALL

      public static final double SIMILARITY_THRESHOLD_ACCEPT_ALL
      Similarity threshold that accepts all search scores. 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.
      See Also:

    • DEFAULT_TOP_K

      public static final int DEFAULT_TOP_K
      Default value for the top 'k' similar results to return.
      See Also:

    • query

      public String query

  • Method Details

    • query

      public static SearchRequest query(String query)
      Create a new SearchRequest builder instance with specified embedding query string.
      Parameters:
      query - Text to use for embedding similarity comparison.
      Returns:
      Returns new SearchRequest builder instance.

    • defaults

      public static SearchRequest defaults()
      Create a new SearchRequest builder instance with an empty embedding query string. Use the withQuery(String query) to set/update the embedding query text.
      Returns:
      Returns new SearchRequest builder instance.

    • from

      public static SearchRequest from(SearchRequest originalSearchRequest)
      Copy an existing SearchRequest instance.
      Parameters:
      originalSearchRequest - SearchRequest instance to copy.
      Returns:
      Returns new SearchRequest builder instance.

    • withQuery

      public SearchRequest withQuery(String query)
      Parameters:
      query - Text to use for embedding similarity comparison.
      Returns:
      this builder.

    • withTopK

      public SearchRequest withTopK(int topK)
      Parameters:
      topK - the top 'k' similar results to return.
      Returns:
      this builder.

    • withSimilarityThreshold

      public SearchRequest withSimilarityThreshold(double threshold)
      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.
      Parameters:
      threshold - The lower bound of the similarity score.
      Returns:
      this builder.

    • withSimilarityThresholdAll

      public SearchRequest withSimilarityThresholdAll()
      Sets disables the similarity threshold by setting it to 0.0 - all results are accepted.
      Returns:
      this builder.

    • withFilterExpression

      public SearchRequest withFilterExpression(Filter.Expression expression)
      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 Document.getMetadata() schema is: 
      
 {
 "country": <Text>,
 "city": <Text>,
 "year": <Number>,
 "price": <Decimal>,
 "isActive": <Boolean>
 &#125;
      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: 
      
 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))));
      The Filter.Expression is portable across all vector stores.
      The FilterExpressionBuilder is a DSL creating expressions programmatically: 
      
 var b = new FilterExpressionBuilder();
 var exp = b.and(
 		b.eq("country", "UK"),
 		b.and(
 			b.gte("year", 2020),
 			b.eq("isActive", true)));
      The FilterExpressionTextParser converts textual, SQL like filter expression language into Filter.Expression: 
      
 var parser = new FilterExpressionTextParser();
 var exp = parser.parse("country == 'UK' && isActive == true && year >=2020");
      Parameters:
      expression - Filter.Expression instance used to define the metadata filter criteria. The 'null' value stands for no expression filters.
      Returns:
      this builder.

    • withFilterExpression

      public SearchRequest withFilterExpression(String textExpression)
      Document metadata filter expression. For example if your Document.getMetadata() has a schema like: 
      
 &#123;
 "country": <Text>,
 "city": <Text>,
 "year": <Number>,
 "price": <Decimal>,
 "isActive": <Boolean>
 &#125;
      then you can constrain the search result with metadata filter expressions like: 
      
 country == 'UK' && year >= 2020 && isActive == true
 Or
 country == 'BG' && (city NOT IN ['Sofia', 'Plovdiv'] || price < 134.34)
      This ensures that the response contains only embeddings that match the specified filer criteria.
      The declarative, SQL like, filter syntax is portable across all vector stores supporting the filter search feature.
      The FilterExpressionTextParser is used to convert the text filter expression into Filter.Expression.
      Parameters:
      textExpression - declarative, portable, SQL like, metadata filter syntax. The 'null' value stands for no expression filters.
      Returns:
      this.builder

    • getQuery

      public String getQuery()

    • getTopK

      public int getTopK()

    • getSimilarityThreshold

      public double getSimilarityThreshold()

    • getFilterExpression

      public Filter.Expression getFilterExpression()

    • hasFilterExpression

      public boolean hasFilterExpression()

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object