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
)

Text reranking​

For text-heavy search, you can retrieve candidates (lexical, vector, or hybrid), then rerank with a heavier-weight scoring expression.

Common zero-shot rerankers include colbert_v2() and cross_encoder(). See the reference docs in ShapedQL.

Example (hybrid retrieval + ColBERTv2 reranking):

SELECT *
FROM text_search(
  query='$params.query',
  mode='vector',
  text_embedding_ref='text_embedding',
  limit=50,
  name='vector_search'
),
text_search(
  query='$params.query',
  mode='lexical',
  fuzziness=2,
  limit=50,
  name='lexical_search'
)
ORDER BY score(expression='colbert_v2(item, $params.query)')
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., click_through_rate, conversion_rate)
  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 score(expression='click_through_rate', input_user_id='$user_id', input_interactions_item_ids='$interaction_item_ids')
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 score(expression='0.7 * click_through_rate + 0.3 * conversion_rate', input_user_id='$user_id', input_interactions_item_ids='$interaction_item_ids')
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 score(expression='0.5 * retrieval.vector_search + 0.3 * retrieval.lexical_search + 0.2 * click_through_rate', input_user_id='$user_id', input_interactions_item_ids='$interaction_item_ids')
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 score(expression='0.7 * click_through_rate + 0.3 * cosine_similarity(text_encoding(user, embedding_ref=''text_embedding''), text_encoding(item, embedding_ref=''text_embedding''))', input_user_id='$user_id', input_interactions_item_ids='$interaction_item_ids')
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 score(expression='0.6 * click_through_rate - 0.05 * item.price + 0.2 * item.rating + 0.15 * item.review_count', input_user_id='$user_id', input_interactions_item_ids='$interaction_item_ids')
LIMIT 20