--- title: "search()" slug: "search-function" updated: 2025-02-14T01:43:08Z published: 2025-02-14T01:43:08Z canonical: "docs.xgen.ai/search-function" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.xgen.ai/llms.txt > Use this file to discover all available pages before exploring further. # search() This function performs a search using the given query and returns the results. ```javascript // Import the integration from the 'installation' step import { integration } from './xgenSdkIntegration'; const { search } = integration; search(query,options); ``` #### Params Parameters passed to the `search` function: | NAME/TYPE | DESCRIPTION | | --- | --- | | `query` string | The search term that will be used to find relevant products. | | REQUIRED `options` SearchOptions | Options used to control different settings within search. | #### Options The `search()` function accepts a JSON object of options: ```json {    "deploymentId": 1234    "page": 1    "context": {}    "skipHistory": true    "facets": true } ``` | NAME/TYPE | DESCRIPTION | | --- | --- | | REQUIRED `deploymentId` string | The deployment ID used for this search contains search engine settings and product filters, configurable within the platform. | | `page` number | The page number for the search results. Page numbers start at zero, with 60 products per page. Therefore, page 0 is the first page, page 1 the second, and so on. **Default:** `0` | | `pageSize` number | The amount of products that will be returned in the search result. **Default:** `60` | | `sortBy` string | The product field that the results will be sorted by. This overrides any sorting done within the engine settings. **Options:** `price` `update_date` | | `sortOrder` string | The direction in which the sorting from `sortBy` will be applied. **Options:** `asc` `desc` **Default:** `desc` | | `context` object | Dynamic filters change based on page context. The context object's key represents the variable in the filter, and its value substitutes that variable within the filter. Filters can be configured within the platform. | | `skipHistory` boolean | If set to true, this query will not be added to the user's search history. **Default:** `false` | | `facets` boolean | If set to true, the search response will contain all facets that have been configured within the product filter being used, along with the counts associated with each bucket. **Default:** `false` | | `autoRedirect` bootlean | If set to true, the page will automatically redirect to the given URL if a URL redirect keyword is searched. **Default:** `true` | #### Response The return value of the `search` function is a `Promise` that resolves to an array of objects containing the products that match the search result, plus facets and metadata. ```json {    "page": 0,    "total_result": 1705,    "cache_ttl_used": 86400,    "hrnn_n": 0,    "search_threshold_achieved": "Not triggered",    "behavior_id": "bdb7268b-ada6-4310-8353-f7b34713e1b5",    "response_engine": "ds",    "is_from_cache": true,    "is_sorted_by_hrnn": false,    "is_keyword_config_applied": false,    "is_ai_sorting_tried": false,    "is_neural": true,    "is_cached_filter_applied": true,    "is_url_redirect": false,    "products_list": [        { "prod_code": "xyz", "prod_name": "Fancy Dress", "prod_price": 3800, "image": "example.com/image/product_1.jpg" }, { "prod_code": "abc", "prod_name": "Fun Dress", "prod_price": 1800, "image": "example.com/image/product_2.jpg" }, { "prod_code": "def", "prod_name": "Nice Dress", "prod_price": 1800, "image": "example.com/image/product_3.jpg" }    ],    "product_code_variant_mapping": {},    "reason": [],    "search_term_matches": [],    "user_data": {},    "facet": {        "aggregations": {            "group": {                "color": {                    "buckets": [                        {                            "doc_count": 1510,                            "key": "-"                        },                        {                            "doc_count": 134,                            "key": "brown"                        },                        {                            "doc_count": 30,                            "key": "black"                        },                        {                            "doc_count": 20,                            "key": "tan"                        }                    ],                    "doc_count_error_upper_bound": 0,                    "sum_other_doc_count": 0                },                "is_in_stock": {                    "buckets": [                        {                            "doc_count": 1578,                            "key": "1"                        },                        {                            "doc_count": 127,                            "key": "0"                        }                    ],                    "doc_count_error_upper_bound": 0,                    "sum_other_doc_count": 0                },                "type": {                    "buckets": [                        {                            "doc_count": 1591,                            "key": "dresses"                        },                        {                            "doc_count": 106,                            "key": "shoes"                        },                        {                            "doc_count": 4,                            "key": "skirts"                        }                    ],                    "doc_count_error_upper_bound": 0,                    "sum_other_doc_count": 0                }            }        }    } } ``` The fields in the response are defined as follows: | NAME/TYPE | DESCRIPTION | | --- | --- | | `page` | This is current page of results, defaults to `0` unless pagination is used. | | `total_result` | The total number of results available for the query | | `cache_ttl_used` | Returns the interval set for this query's cache expiration | | `hrnn_n` | The number of products that will be sorted by the primary prediction model if this is configured | | `search_threshold_achieved` | Deprecated | | `behavior_id` | The ID of the Search Engine that was used (behavior is the technical name for a Search Engine) | | `response_engine` | This defines which engine supplied the results: DeepSearch, GenSearch, or HybridSearch | | `is_from_cache` | Whether or not the results came from the cache | | `is_sorted_by_hrnn` | Whether or not the results have been sorted by the primary prediction model | | `is_keyword_config_applied` | Boolean value if a keyword was matched and applied to this query | | `is_ai_sorting_tried` | Was there an attempt to sort the results by the primary prediction model | | `is_neural` | Boolean value that explains whether the request was intended to be DeepSearch or not | | `is_cache_filter_applied` | Deprecated | | `is_url_redirect` | Whether the result is a URL redirect or not | | `products_list` | The list of products returned by the query, limited to the number of results specified | | `product_code_variant_mapping` | A mapping of which variant specifically should be used for the product result | | `reason` | Deprecated | | `search_term_matches` | Deprecated | | `user_data` | Any relevant metadata about the user | | `facet` | The object that shows all facets available | #### Understanding the `facet` object The facet object returns the facets defined in the Product Filter associated with the deployment. The object can be nested, and has several basic terms that define the object: | NAME | DESCRIPTION | | --- | --- | | `aggregations` | The overall facet object | | `group` | A group of facets, which is the object that can be nested and which contains buckets | | `buckets` | A bucket is an array of potential options associated with a field (for example, a facet of “color” could have “red,” “green,” and “blue” as buckets | | `doc` | A single product is referred to as a “doc” within the response | There are also two pieces of metadata associated with facets: | NAME | DESCRIPTION | | --- | --- | | `doc_count_error_upper_bound` | Metadata related to any direct query errors in relation to faceting | | `sum_other_doc_count` | The number of products that were affected by errors | #### Basic search In this example we are getting products for the query “pants” for the deployment ID “3d8e3aa4-b1e9-4b1b-9ff6-ca4bc64806d0.” Once the promised is resolved, we are looping through and console logging and attribute. ```javascript // Get list of products for an element const { products, total, page, facets } = await search('pants', { deploymentId: '3d8e3aa4-b1e9-4b1b-9ff6-ca4bc64806d0' }); // Console log prod_code of each product recommended products.forEach(product => console.log(product.prod_code)); ``` #### Pagination In the previous example, we got a list of 60 products for the query “pants,” but what if we want the second page? Here we pass in `page: 1` to the options (remember counting starts at 0) so that we can get the next 60 products. ```javascript // Get list of products for an element const { products, total, page, facets } = await search('pants', { deploymentId: '3d8e3aa4-b1e9-4b1b-9ff6-ca4bc64806d0', page: 1 }); // Console log prod_code of each product recommended products.forEach(product => console.log(product.prod_code)); ``` #### Context In this example, we are searching for “jeans,” but passing in a context for `gender` and `category`. This means we are now able to use those two variables within product filters for this deployment. Since we have `gender: "male"` and `category: "pants"` this means we are able to configure the filters to only show male pants that match the search “jeans” and those values are dynamic and can be changed to a different gender or category. ```javascript const context = {  gender: 'male',  category: 'pants' } // Get list of products for an element const { products, total, page, facets } = await search('jeans', { deploymentId: '3d8e3aa4-b1e9-4b1b-9ff6-ca4bc64806d0', context }); ```