Searching with intent

You're throwing a party and want to make your famous pasta carbonara. You open your grocery app and go from one (virtual) aisle to another, picking ingredients one by one, and at the end you forget the eggs. What you actually want is to tell the app what you're cooking and get exactly that: no ingredients missed or forgotten, in a fraction of the time.

A few years ago, this would have been unthinkable. Language models changed that, and what used to sound like a gimmick is quickly becoming a requirement. We keep hearing from our customers that they want to give their shoppers what they want, not what they know how to find. And we've enabled exactly that with Medusa Search.

Capturing intent

Everyone knows how standard search works: keyword matching, facets, price ranges, and so on. It's great when you know exactly what you're looking for. But what happens when you don't?

Search "something warm for a rainy night" in a keyword search engine and you'll get nothing back. A semantic engine returns soup, hot chocolate, or some nice warm tea. That's where semantic search comes into the story.

The purpose of semantic search is to capture intent: find the things "closest" to what you've expressed. So how do we decide what's close and what's far? Think of every product as a location on a map, and the closer products are the more similar they are.

Under the hood, this happens in two steps. First, text is converted into an array of numbers, called a vector or embedding. Those are the coordinates on the map. Then the search engine compares the distance between your query's vector and the vectors of everything in your index.

The first step is done by an embedding model, a language model built for this purpose. Each model has different properties. On the Scale plan, you generate embeddings with the model of your choice and pass the vectors to Medusa Search. On Enterprise, Medusa can generate them for you out of the box.

The second step happens inside the search engine. It finds the items in your index that are closest to your query, which is the whole point of semantic search.

Constructing a good embedding string

A semantic search engine is only as smart as the data it's fed. For a grocery store, a high-quality embedding string typically includes these product properties:

Product Title & Brand: The exact name and maker (e.g., Barilla Spaghetti).

Category Hierarchy: The path that gives broader context (e.g., Pantry > Pasta & Noodles > Long Pasta).

Key Attributes: Weight, size, diet compatibility, or origin (e.g., 16oz, Vegan, Made in Italy).

Descriptive Text: The standard description of the product's flavor profile or texture.

Use Cases & Synonyms (crucial for groceries): Associated recipes, meal types, and alternative names (e.g., pasta carbonara, spaghetti with fatty meat and eggs).

For example, if you sell guanciale, you could construct the following string:

123456
Product Name: Premium Italian Guanciale. Brand: Volpi.
Category: Deli & Meat > Cured Meats > Bacon, Pancetta, Guanciale.
Attributes: 4oz, cubed, gluten-free, pork.
Description: Dry-cured pork belly infused with black pepper and sea salt.
Common uses: pasta carbonara, charcuterie boards, crisping for salads, Italian cooking.

A few things to keep in mind:

• Leave out what changes often. Price, stock levels, and IDs add noise to the embedding and are better handled with filters.
• Use the same template for every product. Embeddings are only comparable if the strings are built the same way.
• Let an LLM write the use cases. Nobody is going to hand-write recipes for 10,000 products. When you index a product, ask an LLM to generate the "Common uses" line from the rest of its data. It's a one-time cost per product, and it's what lets a search for "carbonara" find guanciale.

Enhancing the experience with LLMs

Semantic search is fast and affordable, but it still expects a fairly focused query. For a truly conversational experience, put an LLM in front of it.

This works as a two-stage process. First, shoppers chat with an LLM: they describe what they're cooking, share a photo of a recipe, and so on. Once they're done, you ask the LLM to turn the conversation into search queries, one for each item they need rather than a single string. The instruction can be something along these lines:

You turn a shopper's request into a list of short search queries for a grocery store's semantic product search engine, one query per product they need.

For example:

Shopper: "Making carbonara for 8 people on Saturday, one guest is vegetarian."

LLM output: ["spaghetti 2kg", "guanciale", "smoked tofu or mushrooms", "pecorino romano", "free-range eggs", "black pepper"]

Then run each query through Medusa Search, as text on Enterprise or as a vector you generate yourself on Scale. Take the top result for each query, and you have a full basket, eggs included.

The exact experience and prompt you build will differ a lot depending on your domain, but the basic principles still hold.

Getting started

Semantic search is available on the Scale and Enterprise plans on Medusa Cloud. On Scale, you bring your own embeddings, and on Enterprise Medusa can generate them for you. Learn more on our pricing page.

You can try Medusa Search against a demo catalog on our Search page. To add it to your own project, follow the getting started guide. You'll need Medusa v2.21.1 or later deployed on Cloud. The guide walks you through defining a product index, making it available to your storefront, and running your first search.

If you're building with an AI agent, paste the following prompt:

1
Fetch https://medusajs.com/search and set up search

For the embedding setup and examples of semantic queries, see our semantic search guide.