This API fetches search results and answers generated corresponding to the input query and the filters sent in the request body. This API returns results from all the data ingested into the SearchAssist application. You can sort the results, limit the number of search results, send additional search settings or request for qualified chunks for the generated answer using appropriate options in the request payload.
| Method | POST |
| Endpoint | <host_url>/searchassistapi/external/stream/<streamId>/advancedSearch |
| Content-Type | application/json |
| Authorization | auth: <JWT Token> |
| API Scope | Advanced Search |
Query Parameters
| Parameters | Description | Mandatory |
| Stream ID | Provide your application ID here. | |
| skip | This is the number of index records to skip while fetching the records. | No. When not provided, the default value of 0 is used. |
| limit | This is the number of index records to be fetched in each API call. | No. When not provided, the default value of 50 is used. |
Request Parameters
| Parameters | Description | Mandatory |
| query | Query string for search | Yes |
| queryType | This parameter can take one of the following two values:
|
No |
| metaFilters | This parameter can be used to define rules to filter out the search results. This parameter takes an array of rules with conditions. For example, in the following sample, we are adding a filter which has two rules that help you choose either the products .
"metaFilters": [ { "condition": "OR", "rules": [ { "fieldName": "productType", "fieldValue": [ "washing machines" ], "operator": "contains" }, { "fieldName": "price", "fieldValue": [ { "lte": "15" } ], "operator": "range" } ] }, ] |
No |
| answerMetaFilters | This parameter can be used to define rules to filter out the results from the Answer Index before using them for generating the answer. This parameter takes an array of rules with conditions. For example, in the following example, we are selecting chunks only where the source is ‘web’.
“answerMetaFilters”: [ { “condition”: “AND”, “rules”: [ { “fieldName”: “sourceType”, “fieldValue”: [ “web” ], “operator”: “contains” } ] }] |
No |
| sort | This parameter can be used to sort the results as per the index fields. For example, to sort the results in ascending order of the title, set this to:
"sort": [ { "fieldName": "title", "order": "asc" }] |
No |
| lang | The language used for the query. | No. By default, this is set to English. |
| customData | Custom data to be sent in the request. This data can be used to further process or filter the search results in the application. For example, you can use this field to set user context like user identity, location, etc. | No |
| SearchSettings | Search settings to be applied to the fields. The default search configuration of the application is overridden when this parameter is present in the request body. | No |
| maxNumOfResults | Max number of search results to be returned in the response. | Yes |
| facets | This parameter can be used to facets to refine the search results. Refer to the sample payload below for an example. | No |
| answerSearch | This can be set to true or false. When set to ‘true’, the response will include answers. Conversely, when set to ‘false’, the response will omit the answer to the query. However, you can still use the includeChunksinResponse field to see the qualified chunks in the response. By default, it is set to true. | No |
| includeChunksInResponse | This can be set to true or false. When set to true and if answers snippets are enabled, the response will also have the list of qualified chunks along with other parameters. The chunk information is stored in chunk_result
field in the response. |
No |
| IncludeMetaDataAnswers | This field can fetch specific chunk metadata fields in the Answer along with the default fields. The requested fields are returned as part of the graph_answer field in the response. For instance, to fetch the author name(a metadata field) and subtitle(a custom field) additionally from the chunks, include the following in the request payload. “IncludeMetaDataAnswers”: [“chunkMeta.author”, “subtitle”]. Note: 1. For metadata fields, use the field name along with the root name, such as chunkMeta.<x>, as shown in the above example. 2. If a metadata field listed in this object does not exist, the field is returned with a null value. |
No |
| IncludeMetaDataSearchResults | This parameter accepts an array that lists the specific fields to be included in the response, along with the default fields. The fields are returned in the results field in the response.
For example : to fetch the title and url from the meta fields, set the field as shown below. “IncludeMetaDataSearchResults”: [“meta_data.title”, “meta_data.url”] |
No |
Sample Request payload
{ "query": "show me shirts less than $20", "maxNumOfResults": 20, "queryType": "relevanceWithMetaFilter", "customData": { "userContext": { "userId": "u-cdd39325-b89e-517b-b3d6-18b75a5f09a6" } }, "sort": [ { "fieldName": "title", "order": "asc" } ], "metaFilters": [ { "condition": "OR", "rules": [ { "fieldName": "productType", "fieldValue": [ "jackets" ], "operator": "contains" }, { "fieldName": "price", "fieldValue": [ { "lte": "1500" } ], "operator": "range" } ] }, { "condition": "AND", "rules": [ { "fieldName": "productType", "fieldValue": [ "shirts" ], "operator": "contains" }, { "fieldName": "price", "fieldValue": [ { "lte": 1500 } ], "operator": "range" } ] } ], "facets": [ { "name": "MensWear", "subtype": "value", "size": 10, "sortConfig": { "sortBy": "count", "order": "desc" }, "fieldName": "productType" } ] } |
Response Format
Search Results are listed as results field in the response. Search results from different sources are separated by source name in the results field. If answerSearch is set to true, the answer for the given query is presented in the graph_answer field. If includeChunksInResponse is set to true, the chunk details are available in the chunk_result field.
The format of the API response is as shown below. Note that the response format can vary depending on the request payload.
Tips on using customData parameter in the Search APIs
The parameter, customData, in the request object can be used to send custom data to the SearchAssist application. This field can be used to set the userContext when performing the search through APIs. For example, if your search results depend on the location of the user and you have a business rule in the application that reads the ‘location’ field from the user context and returns responses based on the location. In such a scenario, when you are invoking any of the search APIs (live search, full search, or advanced search), you can send this field as part of userContext in the customData parameter as shown below.
"customData": { "userContext": { "location": "Germany" } }, |
Tips on using metaFilters and answerMetaFilters in the Search APIs
The parameter, metaFilters, can be used to define rules to filter out the search results. The rules can use any of the fields in the Search Index. Similarly, answerMetaFilters can be used to filter chunks used to generate answers. The answerMetaFilters uses chunk fields used in the Answer Index.
Both of these parameters expect an array of filters where each filter can have one or more rules. Here are some tips for defining metaFilters object.
- You can define more than one filter using these parameters.
- Each filter can have one or more rules to it.
- You can have more than one simple rule with logical operators AND or OR to form complex rules for a filter.
To learn more about the chunk fields that can be used to add answerMetaFilters, go to the Chunk Browser and see the JSON view. Similarly, use Workbench Simulator to view the fields that can be used to define metaFilters.