Using Semantic (Neural) Search

3min
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"
    }
}'
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
_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.
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”
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.
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:
The system understands the intent (exercise clothing that allows airflow).
It searches for products with relevant attributes, even if they don't explicitly use the words "breathable" or "workout".
The results might include moisture-wicking t-shirts, ventilated running shorts, and lightweight training shoes.
These results are then ranked based on their relevance to the query's meaning.
﻿
Did this page help you?
Semantic (Neural) Search
Integration with Other Services