Skip to main content

Search

This page covers search queries for finding items based on text queries. For query fundamentals, see Query Basics.

Search queries allow you to find items based on a text query. Shaped supports multiple search modes, from simple keyword matching to advanced personalized search.

Lexical search finds items that contain the exact keywords from the query, with optional fuzzy matching for typos. This is the simplest form of search and works well when users know exactly what they're looking for.

Prerequisites​

  1. Lexical search configured on searchable text fields
  2. A search query text

Query example​

SELECT *
FROM text_search(query='$query_text', mode='lexical', fuzziness=2, limit=20)

Semantic search uses vector embeddings to find items that are semantically similar to the query text, even if they don't contain the exact keywords. This enables users to find items by meaning rather than exact word matches.

Prerequisites​

  1. An engine with a text embedding configured
  2. A search query text

Query example​

SELECT *
FROM text_search(query='$query_text', mode='vector', 
                 text_embedding_ref='text_embedding', limit=20)

Hybrid search combines semantic and lexical search to return a blended list of results. This balances semantic understanding with exact keyword matching, providing better recall than either approach alone.

Prerequisites​

  1. An engine with a text embedding configured for vector search
  2. Lexical search configured on searchable text fields
  3. A search query text

Query example​

This example retrieves candidates from two sources (vector search and lexical search), then returns the blended results:

SELECT *
FROM text_search(query='$query_text', mode='vector', 
                 text_embedding_ref='text_embedding', limit=50),
     text_search(query='$query_text', mode='lexical', fuzziness=2, limit=50)
LIMIT 20

Tuning the blend​

You can adjust the limit on each retriever to control the balance between semantic and lexical results. A higher limit on one retriever will give it more influence on the final results.

Personalized hybrid search adds a scoring stage that re-ranks the blended search results based on user preferences. This is useful when you want search results that are both relevant to the query and personalized to the user's taste.

Prerequisites​

  1. An engine with a text embedding configured for vector search
  2. Lexical search configured on searchable text fields
  3. A trained scoring model (e.g., lightgbm, bert4rec)
  4. A user ID to personalize for
  5. A search query text

Query example​

This example retrieves candidates from both vector and lexical search, then scores them using a personalization model:

SELECT *
FROM text_search(query='$query_text', mode='vector', 
                 text_embedding_ref='text_embedding', limit=50),
     text_search(query='$query_text', mode='lexical', fuzziness=2, limit=50)
ORDER BY lightgbm
LIMIT 20

Combining multiple scoring models​

You can combine multiple scoring models using a weighted expression:

SELECT *
FROM text_search(query='$query_text', mode='vector', 
                 text_embedding_ref='text_embedding', limit=50),
     text_search(query='$query_text', mode='lexical', fuzziness=2, limit=50)
ORDER BY 0.7 * lightgbm + 0.3 * bert4rec
LIMIT 20

Blending retrieval scores with models​

Combine retrieval scores from multiple search retrievers with model predictions for more nuanced ranking:

SELECT *
FROM text_search(query='$query_text', mode='vector', 
                 text_embedding_ref='text_embedding', limit=50,
                 name='vector_search'),
     text_search(query='$query_text', mode='lexical', fuzziness=2, limit=50,
                 name='lexical_search')
ORDER BY 0.5 * retrieval.vector_search + 0.3 * retrieval.lexical_search + 
         0.2 * lightgbm
LIMIT 20

Using text encodings for semantic similarity​

Score search results using semantic similarity between user preferences and item text encodings:

SELECT *
FROM text_search(query='$query_text', mode='vector', 
                 text_embedding_ref='text_embedding', limit=50)
ORDER BY 0.7 * lightgbm + 0.3 * cosine_similarity(
  text_encoding(user, embedding_ref='text_embedding'), 
  text_encoding(item, embedding_ref='text_embedding'))
LIMIT 20

Incorporating item attributes in search ranking​

Boost or penalize search results based on item attributes like price, rating, or other metadata:

SELECT *
FROM text_search(query='$query_text', mode='vector', 
                 text_embedding_ref='text_embedding', limit=50),
     text_search(query='$query_text', mode='lexical', fuzziness=2, limit=50)
ORDER BY 0.6 * lightgbm - 0.05 * item.price + 0.2 * item.rating + 
         0.15 * item.review_count
LIMIT 20