Skip to main content

Search

Search queries allow you to find items based on a text query. Shaped supports three search modes:

  1. Hybrid search - combines semantic and lexical signals
  2. Semantic search - finds items by meaning using vector embeddings
  3. Lexical search - finds items by exact keyword matching

Hybrid search combines multiple retrieval strategies to return a blended list of results. Use hybrid search when you need to balance semantic understanding and exact keyword matching.

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:

{
  "query": {
    "type": "rank",
    "from": "item",
    "retrieve": [
      {
        "type": "text_search",
        "input_text_query": "$parameters.query_text",
        "mode": { "type": "vector", "text_embedding_ref": "text_embedding" },
        "limit": 50
      },
      {
        "type": "text_search",
        "input_text_query": "$parameters.query_text",
        "mode": { "type": "lexical", "fuzziness_edit_distance": 2 },
        "limit": 50
      }
    ],
    "limit": 20
  },
  "parameters": {
    "query_text": "Blue shirt"
  }
}

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.

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.

Prerequisites​

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

Query example​

{
  "query": {
    "type": "rank",
    "from": "item",
    "retrieve": [
      {
        "type": "text_search",
        "input_text_query": "$parameters.query_text",
        "mode": { "type": "vector", "text_embedding_ref": "text_embedding" },
        "limit": 20
      }
    ]
  },
  "parameters": {
    "query_text": "Blue shirt"
  }
}

Lexical search finds items that contain the exact keywords from the query, with optional fuzzy matching for typos.

Prerequisites​

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

Query example​

{
  "query": {
    "type": "rank",
    "from": "item",
    "retrieve": [
      {
        "type": "text_search",
        "input_text_query": "$parameters.query_text",
        "mode": { "type": "lexical", "fuzziness_edit_distance": 2 },
        "limit": 20
      }
    ]
  },
  "parameters": {
    "query_text": "Blue shirt"
  }
}