{"section":"tutorials","requestedLocale":"en","requestedSlug":"intelligent-search-semantic-search-beta","locale":"en","slug":"intelligent-search-semantic-search-beta","path":"docs/en/tutorials/beta/intelligent-search-beta/intelligent-search-semantic-search-beta.md","branch":"main","content":"> ℹ️ Semantic search is available exclusively as part of the Search Optimizer Agent, an additional search optimization service.\n> \n> This feature is in closed beta, and only participating customers can access it. If you're a VTEX client and want to adopt Search Optimizer Agent for your business, contact our [Commercial Support](https://help.vtex.com/en/docs/tracks/commercial-support). Additional fees may apply. If you're not a VTEX client but are interested in this solution, please complete our [contact form](https://vtex.com/en-us/contact/).\n\nIntelligent Search combines the precision of lexical techniques with the intelligence of Semantic search models to provide a relevant and seamless experience that aligns with user intent.\n\nThis strategy improves product discovery, increases conversions, and reduces friction in interactions, especially in large, different catalogs.\n\n## Key concepts\n\nIntelligent Search combines two key concepts:\n\n* **Lexical search**: Based on direct keyword match.\n* **Semantic search**: Interprets the meaning and intent behind a query.\n\nBoth concepts are described in more detail in the following sections.\n\n### Lexical search\n\nThe lexical layer of the search works based on a direct match between the query terms and the details that are indexed in the catalog — like product name, description, technical attributes, and others. This approach works well when the customer uses exact keywords or searches by product code.\n\n**Example:**\n\n* **Query:** `Nike Air Max 90 sneakers`\n\n   * The lexical search returns only products with that name in the catalog.\n\n### Semantic search\n\nThe semantic layer, based on **Natural Language Processing (NLP)** and **machine learning models**, interprets the meaning of words and their context. It recognizes synonyms, relates similar terms, and identifies user intention even when the query doesn't mention exact words in the catalog.\n\n**Example:**\n\n* **Query**: `shoes for running a marathon`\n\n   * The Semantic search understands that the user is looking for shoes optimized for long-distance performance and prioritizes products tailored for endurance running, even if they don't include 'marathon' in the description.\n\n* **Query**: `clothes for cold weather workouts`\n\n   * **Lexical**: May not find a direct match with 'cold weather workouts'.\n   * **Semantic**: Understands that the user is searching for sportswear with thermal protection and prioritizes items like thermal pants and long-sleeve shirts.\n\n## Intelligent Search approach\n\nThe Intelligent Search dynamically combines these two strategies. The platform uses semantic models trained for the retail context and enhances this interpretation with the established lexical structure of Intelligent Search.\n\nThis model considers:\n\n* Structured fields in the catalog (lexical)\n* Relationships between terms and synonyms (semantic)\n* Search context and user behavior\n* Statistical relevance and machine learning\n\nThe result is a search system that provides results that are more aligned with what consumers really want to find, even when using natural or ambiguous language.\n\nFor example, a technology ecommerce website can get specific searches for 'SSD A400 480GB', where lexical search is ideal, or informal searches like 'best storage for gaming', where Semantic search is better. Intelligent Search handles both queries efficiently.\n\nIn practice, if a customer types '16GB memory', for example, the lexical part identifies the exact capacity (16 GB) while the semantic component understands that 'memory' may refer to both RAM and memory cards, and prioritizes both categories for the most relevant products based on previous user behavior.\n\n## Advantages\n\nThe main advantages for consumer experience and store performance are:\n\n* **Increased conversion:** Delivering more relevant results reduces product discovery time, which can accelerate purchase decisions.\n* **Natural language comprehension:** Customers can search using everyday language, including full questions, vague terms, or informal language. For example, a customer might search `what is the best hiking shoe?`, and the search understands they're looking for shoes with specific features, such as a lug sole and water resistance.\n* **Support for complex discovery cases:** Ideal for catalogs that have products with more subjective descriptions (example: fashion, beauty, home decor), where the exact attribute may not explicitly be present, but user intent can be inferred.\n\n## How to test Semantic search\n\nBefore applying Semantic search to all customers in your store, you can test it to compare results with and without this feature. The testing method depends on your store's architecture.\n\n### Store Framework stores\n\nFor stores using [Store Framework](https://help.vtex.com/en/docs/tracks/frontend#store-framework), VTEX can create a test workspace and, if needed, configure an A/B test with VTEX's internal solution to compare results with and without Semantic search. To do this, contact [Support](https://help.vtex.com/en/docs/tutorials/how-does-vtex-support-work).\n\n### Headless or FastStore stores\n\nFor Headless stores or those using [FastStore](https://help.vtex.com/en/docs/tracks/frontend#faststore), Semantic search can be tested by adding a parameter to the URL of the call to the [Intelligent Search API](https://developers.vtex.com/docs/api-reference/intelligent-search-api-v1#get-/product-search/-facets-), without changing any store configuration.\n\nA *query string* is the part that appears after the `?` symbol at the end of a URL. It's used to send additional information to the server without changing the rest of the address, in the format `parameter=value`. When there's more than one parameter, they're separated by the `&` symbol.\n\nTo test Semantic search in a specific call, add the `semanticRatio` parameter to the *query string* of the search URL, in the format `?semanticRatio={weightValue}`. This parameter accepts values between `0` and `1`, which define how the search works:\n\n* `0`: Uses only lexical search. This is also the default behavior when the parameter isn't provided.\n* `1`: Uses only Semantic search.\n* `0.5`: Combines both models. Any value between `0` and `1` behaves like `0.5`.\n\n**Example:**\n\n* Without Semantic search:\n   `https://{accountName}.vtexcommercestable.com/api/intelligent-search/v1/product-search?query=baby%20formula`\n* With Semantic search:\n   `https://{accountName}.vtexcommercestable.com/api/intelligent-search/v1/product-search?query=baby%20formula&semanticRatio=0.5`\n\nSince the parameter is only added to the test call's URL, it doesn't change the store's configuration or affect other calls. This allows you to compare both versions side by side or use this URL in your own A/B testing tool to direct part of the traffic to the version with Semantic search.\n\n### Direct activation in production\n\nYou can also activate Semantic search directly for all calls made to the API, without needing to include the `semanticRatio` parameter in each request. This activation must be requested from [Support](https://help.vtex.com/en/docs/tutorials/how-does-vtex-support-work), and since it applies the change to all customers in the production store, it isn't recommended for testing."}