# Submitting feedback for incremental learning **Note** Feature support varies by index type and search API being used. To see if this feature is supported for the index type and search API you’re using, see [Index types](https://docs.aws.amazon.com/kendra/latest/dg/hiw-index-types.html). Amazon Kendra uses incremental learning to improve search results. Using feedback from queries, incremental learning improves the ranking algorithms and optimizes search results for greater accuracy. For example, suppose that your users search for the phrase "health care benefits." If users consistently choose the second result from the list, over time Amazon Kendra boosts that result to the first place result. The boost decreases over time, so if users stop selecting a result, Amazon Kendra eventually removes it and shows another more popular result instead. This helps Amazon Kendra prioritize results based on relevance, age, and content. Incremental learning is activated for all indexes and for all [supported document types](https://docs.aws.amazon.com/kendra/latest/dg/index-document-types.html). Amazon Kendra starts learning as soon as you provide feedback, though it can take over 24 hours to see the results of the feedback. Amazon Kendra provides three methods for you to submit feedback: the AWS console, a JavaScript library that you can include on your search results page, and an API that you can use. Amazon Kendra accepts two types of user feedback: + **Clicks**—Information about which query results the user chose. The feedback includes the result ID and the Unix timestamp of the date and time that the search result was chosen. To submit click feedback, your application must collect click information from the activities of your users, and then submit that information to Amazon Kendra. You can collect click information with the console, the JavaScript library, and the Amazon Kendra API. + **Relevance**—Information about the relevance of a search result, which the user typically provides. The feedback contains the result ID and a relevance indicator (`RELEVANT` or `NOT_RELEVANT`). The user determines the relevance information. To submit relevance feedback, your application must provide a feedback mechanism that allows the user to choose the appropriate relevance for a query result, and then submit that information to Amazon Kendra. You can only collect relevance information with the console and the Amazon Kendra API. Feedback is used while the index is active. Feedback only affects the index that it is submitted to, it can't be used across indexes or for different accounts. You should provide additional user context when you query your Amazon Kendra index. When you provide user context, Amazon Kendra is able to tell if the feedback is provided by a single user or by multiple users and adjust search results accordingly. When you provide user context, the feedback for the query is associated with the specific user provided in the context. If you don't specify user context, you can provide a visitor ID that is used to group and aggregate queries. If you don't provide user context or a visitor ID, the feedback is anonymous and aggregated with other anonymous feedback. The following code shows how to include user context as a token or the visitor ID. ``` response = kendra.query( QueryText = query, IndexId = index, UserToken = { Token = "token" }) OR response = kendra.query( QueryText = query, IndexId = index, VisitorId = "visitor-id") ``` For web applications, you can use cookies, locations, or browser users to generate a visitor ID for each user. For head queries, the largest volume of queries, providing click-through feedback provides enough information to improve overall accuracy. For tail queries, those that are rare, subject matter experts should submit relevant and non-relevant feedback to improve accuracy for those queries. In addition to the console, you can use one of two methods: a JavaScript library or the [SubmitFeedback](https://docs.aws.amazon.com/kendra/latest/APIReference/API_SubmitFeedback.html) API. You should only use one method of gathering feedback. For best results, you should submit feedback within 24 hours of making the query. **Topics** + [Using the Amazon Kendra JavaScript library to submit feedback](feedback-javascript.md) + [Using the Amazon Kendra API to submit feedback](feedback-api.md) # Using the Amazon Kendra JavaScript library to submit feedback Amazon Kendra provides a JavaScript library that you can use to add click feedback to your search results page. To use the library, you insert a script tag in your client code that displays the search result, then add information to each of the document links in your result list. When a user chooses a link to view a document, click information is sent to Amazon Kendra. The library works with browsers that support JavaScript version ES6/ES2015. ## Step 1: Insert a script tag into your Amazon Kendra search application In your client code that renders the Amazon Kendra search results, insert a ``` The script asynchronously downloads the JavaScript library from an Amazon Kendra hosted CDN and initializes a global variable called `kendraFeedback` that allows you to set optional parameters. Replace *library download URL* and *feedback endpoint* with an identifier from the following table based on the region that hosts your Amazon Kendra index. | Region | Download URL | Feedback endpoint | | --- | --- | --- | | us-east-1 | https://d2zm0lpns956f8.cloudfront.net/ksf-v1.js | https://ujxwp5s92h.execute-api.us-east-1.amazonaws.com/prod/submit | | us-east-2 | https://d2crv7fufeg244.cloudfront.net/ksf-v1.js | https://i6h76zwzf3.execute-api.us-east-2.amazonaws.com/prod/submit | | us-west-2 | https://d2iezfpnpcoujy.cloudfront.net/ksf-v1.js | https://wg6nim909c.execute-api.us-west-2.amazonaws.com/prod/submit | | ca-central-1 | https://d1zbkfomowykaq.cloudfront.net/ksf-v1.js | https://budi8txevj.execute-api.ca-central-1.amazonaws.com/prod/submit | | eu-west-1 | https://d3gptlxtulu4us.cloudfront.net/ksf-v1.js | https://po2b11740b.execute-api.eu-west-1.amazonaws.com/prod/submit | | ap-southeast-1 | https://d1vvuam7g4taoe.cloudfront.net/ksf-v1.js | https://9je5uw7t5l.execute-api.ap-southeast-1.amazonaws.com/prod/submit | | ap-southeast-2 | https://dopqntoe6z0ce.cloudfront.net/ksf-v1.js | https://oovf4nvjj7.execute-api.ap-southeast-2.amazonaws.com/prod/submit | | ap-south-1 | https://d1ts9ouelsmk3g.cloudfront.net/ksf-v1.js | https://k1abnmd43b.execute-api.ap-south-1.amazonaws.com/prod/submit | | ap-northeast-1 | https://d3w0ybsa293kb4.cloudfront.net/ksf-v1.js | https://wg7rz0uzjh.execute-api.ap-northeast-1.amazonaws.com/prod/submit | | eu-west-2 | https://d1tsrujswld1d1.cloudfront.net/ksf-v1.js | https://qi7mct3x7f.execute-api.eu-west-2.amazonaws.com/prod/submit | For example, if your index is in US East (N. Virginia), *library download URL* is `https://d2zm0lpns956f8.cloudfront.net/ksf-v1.js` and *feedback endpoint* is `https://ujxwp5s92h.execute-api.us-east-1.amazonaws.com/prod/submit`. There are two optional settings that you can make for the Amazon Kendra JavaScript library: + `disableCookies` – By default, Amazon Kendra sets a cookie that uniquely identifies the user. Set this to `true` to disable the cookie. ``` kendraFeedback('disableCookie', 'true | false'); ``` `searchDivClassName` – By default, Amazon Kendra monitors all links on your search results page for clicks. Set this to a `
` class name to monitor only links in the specified class. ``` kendraFeedback('searchDivClassName', 'class name'); ``` ## Step 2: Add the feedback token to search results On your result page, add an HTML attribute called `data-kendra-token` to the anchor tag or immediate parent div tag that contains a link to the document from the query response. For example: ``` OR
``` A query response contains a token in the `feedbackToken` field. The token uniquely identifies the response if the user chooses it. Assign the value of the token to the `data-kendra-token` attribute. The Amazon Kendra JavaScript library looks for this token when the user chooses the result and submits it to an Amazon Kendra endpoint as feedback. The Amazon Kendra JavaScript library only submits the feedback token and other metadata such as the time the result was chosen and a unique visitor ID. ## Step 3: Test the feedback script To make sure that the JavaScript library is configured correctly and sending feedback to the right endpoint, do the following. This example uses the Chrome browser. 1. Open the Web developer tools in the browser. On Chrome, open the **Chrome menu** in the upper right corner of the browser, choose **More tools** and then choose **Developer tools**. 1. Make sure that there are no errors related to the Amazon Kendra JavaScript library in the console tab. 1. Make a search and choose any result. In the **Network** tab of the developer tools. You should see a request sent to the feedback endpoint, the token for the result, and a 200 OK status. # Using the Amazon Kendra API to submit feedback To use the Amazon Kendra API to submit query feedback, use the [SubmitFeedback](https://docs.aws.amazon.com/kendra/latest/APIReference/API_SubmitFeedback.html) API. To identify the query, you supply the index ID of the index that the query applies to, and the query ID returned in the response from the [Query](https://docs.aws.amazon.com/kendra/latest/APIReference/API_Query.html) API. The following example shows how to submit click and relevance feedback using the Amazon Kendra API. You can submit multiple sets of feedback through the `ClickFeedbackItems` and `RelevanceFeedbackItems` arrays. This example submits a single click and a single relevance feedback item. The feedback submittal uses the current time. **To submit feedback for a search (AWS SDK)** 1. You can use the following example code with the required values: 1. `index id`—The ID of the index that the query applies to. 1. `query id`—The query that you want to provide feedback on. 1. `result id`—The ID of the query result that you want to provide feedback on. The query response contains the result ID. 1. `relevance value`—Either `RELEVANT` (the query result is relevant) or `NOT_RELEVANT` (the query result is not relevant). ------ #### [ Python ] ``` import boto3 import time kendra = boto3.client("kendra") # Provide the index ID index_id = "index-id" # Provide the query ID query_id = "query-id" # Provide the search result ID result_id = "result-id" # Configure the feedback item feedback_item = {"ClickTime": int(time.time()), "ResultId":result_id} # Configure the relevance value relevance_value = "RELEVANT" relevance_item = {"RelevanceValue": relevance_value, "ResultId": result_id } response = kendra.submit_feedback( QueryId = query_id, IndexId = index_id, ClickFeedbackItems = [feedback_item], RelevanceFeedbackItems = [relevance_item] ) print("Submitted feedback for query: " + query_id) ``` ------ #### [ Java ] ``` package com.amazonaws.kendra; import java.time.Instant; import software.amazon.awssdk.services.kendra.KendraClient; import software.amazon.awssdk.services.kendra.model.ClickFeedback; import software.amazon.awssdk.services.kendra.model.RelevanceFeedback; import software.amazon.awssdk.services.kendra.model.RelevanceType; import software.amazon.awssdk.services.kendra.model.SubmitFeedbackRequest; import software.amazon.awssdk.services.kendra.model.SubmitFeedbackResponse; public class SubmitFeedbackExample { public static void main(String[] args) { KendraClient kendra = KendraClient.builder().build(); SubmitFeedbackRequest submitFeedbackRequest = SubmitFeedbackRequest .builder() .indexId("IndexId") .queryId("QueryId") .clickFeedbackItems( ClickFeedback .builder() .clickTime(Instant.now()) .resultId("ResultId") .build()) .relevanceFeedbackItems( RelevanceFeedback .builder() .relevanceValue(RelevanceType.RELEVANT) .resultId("ResultId") .build()) .build(); SubmitFeedbackResponse response = kendra.submitFeedback(submitFeedbackRequest); System.out.println("Feedback is submitted"); } } ``` ------ 1. Run the code. After the feedback has been submitted, the code displays a message.