---
title: Using Semantic (Neural) Search
slug: user-documentation/using-semantic-neural-search
docTags: 
createdAt: 2025-02-17T07:55:46.713Z
---

To use neural search, you'll need to send a specific query to the **UpStart Commerce **API. Here's an example of how to structure your query:

```curl
curl --location 'https://nochannel-dev-1-api.nochannel-dev.upstart.team/v1/search/routes/catalog_live/search' \

--header 'Content-Type: application/json' \
--header 'X-Upstart-Tenant: YOUR_COMPANY' \
--header 'x-upstart-api-key: YOUR_API_KEY_HERE\
--data '{
    "search": {
        "_source": {
            "excludes": "*knn"
        },
        "query": {
            "nested": {
                "path": "dynamicProperties.neural_description_catalog_model_embedding",
                "query": {
                    "neural": {
                        "dynamicProperties.neural_description_catalog_model_embedding.knn": {
                            "query_text": "summer outfit",
                            "model_id": "catalog_model",
                            "k": 10
                        }
                    }
                }
            }
        }
    },
    "mostValuableQuery": {
        "query": "summer outfit"
    }
}'
```

## Key Components of the Query

1. **\_source.excludes**: This section defines the search fields you want to exclude. It is recommended when searching on an index with vectors to exclude \*knn fields since those are the ones that contain vectors. Vectors will still be searched through but not returned by the search response as they have no use on a storefront. This will make the search query faster and the response smaller.
2. **Nested query**: When using neural search a neural query within a nested query needs to be used all the time to search through all the vectors and not miss data. 
   - **Parameters**
     - **Path**: path to the field containing all the vectors
     - **Query**: query to be used with neural query. In neural search it will always be “neural”
3. **Neural Query Parameters**:
   - **dynamicProperties.neural\_description\_catalog\_model\_embedding.knn**: This is the field the query will search on. It represents the vector embedding of the product description, which has been processed by the catalog model to create a semantic representation of the text.
   - **model\_id**: "catalog\_model" - This specifies the machine learning model to use for the neural search. In this case, it's using the "catalog\_model" model, which is designed for catalog search.
   - **k**: 10 - This parameter determines the number of results the neural query will return. In this example, it will return the top 10 most relevant results based on the neural search.
4. **mostValuableQuery.query**: internal query value used for search query rules

## Example Use Case: Apparel Store

Let's say you run an online apparel store. A customer searches for "breathable*** workout gear***". With neural search:

1. The system understands the intent (exercise clothing that allows airflow).
2. It searches for products with relevant attributes, even if they don't explicitly use the words "*breathable*" or "*workout*".
3. The results might include moisture-wicking t-shirts, ventilated running shorts, and lightweight training shoes.
4. These results are then ranked based on their relevance to the query's meaning.