# Deploying Amazon Kendra **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). When it comes time to deploy Amazon Kendra search to your website, we provide source code that you can use with React to get a head start on your application. The source code is provided with no charge under a modified MIT license. You can use it as is or change it for your own needs. The provided React app is an example to help you get started. It's not a production ready app. To deploy a search application with no code and generate an endpoint URL to your search page with access control, see [Amazon Kendra Experience Builder](https://docs.aws.amazon.com/kendra/latest/dg/deploying-search-experience-no-code.html). The following example code adds Amazon Kendra search to an existing React web application: + [https://kendrasamples.s3.amazonaws.com/kendrasamples-react-app.zip](https://kendrasamples.s3.amazonaws.com/kendrasamples-react-app.zip)—Sample files that developers can use to build a functional search experience into their existing React web application. The examples are modeled after the search page of the Amazon Kendra console. They have the same features for searching and displaying search results. You can use the whole example, or you can choose just one of the features for your own use. To see the three components of the search page in the Amazon Kendra console, choose the code icon (****) from the right menu. Hover your pointer over each section to see a brief description of the component and to get the URL of the component's source. **Topics** + [ ## Overview ](#example-overview) + [ ## Prerequisites ](#example-prereqs) + [ ## Setting up the example ](#example-install) + [ ## Main search page ](#main-component) + [ ## Search component ](#search-component) + [ ## Results component ](#results-component) + [ ## Facets component ](#facets-component) + [ ## Pagination component ](#pagination-component) + [ # Building a search experience with no code ](deploying-search-experience-no-code.md) ## Overview You add the example code to an existing React web application to activate search. The example code includes a Readme file with steps to set up a new React development environment. The example data in the code example can be used to demonstrate a search. The search files and components in the example code are structured as follows: + Main search page (`Search.tsx`)—This is the main page that contains all of the components. This is where you integrate your application with the Amazon Kendra API. + Search bar—This is the component where a user enters a search term and calls the search function. + Results—This is the component that displays the results from Amazon Kendra. It has three components: Suggested answers, FAQ results, and recommended documents. + Facets—This is the component that shows the facets in the search results and allows you to choose a facet to narrow the search. + Pagination—This is the component that paginates the response from Amazon Kendra. ## Prerequisites Before you begin, you need the following: + Node.js and npm [installed](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm). Node.js version 19 or older is required. + Python 3 or Python 2 [downloaded and installed](https://www.python.org/downloads/). + [SDK for Java](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/setup.html) or [AWS SDK for JavaScript](https://docs.aws.amazon.com/sdk-for-javascript/latest/developer-guide/welcome.html) to make API calls to Amazon Kendra. + An existing React web application. The example code includes a Readme file with steps on how to set up a new React development environment, including using required frameworks/libraries. You can also follow the quick start instructions in the [React documentation on creating a React web app](https://create-react-app.dev/docs/getting-started). + The required libraries and dependencies configured in your development environment. The example code includes a Readme file that lists the required libraries and package dependencies. Note that `sass` is required, as `node-sass` is deprecated. If you previously installed `node-sass`, uninstall this and install `sass`. ## Setting up the example A complete procedure for adding Amazon Kendra search to a React application is in the Readme file included in the code example. **To get started using kendrasamples-react-app.zip** 1. Make sure you have completed the [Prerequisites](#example-prereqs), including downloading and installing Node.js and npm. 1. Download kendrasamples-react-app.zip and unzip. 1. Open your terminal and go to `aws-kendra-example-react-app/src/services/`. Open `local-dev-credentials.json` and provide your credentials. Do not add this file to any public repository. 1. Go to `aws-kendra-example-react-app` and install the dependencies in `package.json`. Run `npm install`. 1. Launch a demo version of your app on your local server. Run `npm start`. You can stop the local server by entering on your keyboard `Cmd/Ctrl + C`. 1. You can change the port or host (for example, IP address) by going to `package.json` and update the host and port: `"start": "HOST=[host] PORT=[port] react-scripts start"`. If you use Windows: `"start": "set HOST=[host] && set PORT=[port] && react-scripts start"`. 1. If you have a registered website domain, you can specify this in `package.json` after your app name. For example, `"homepage": "https://mywebsite.com"`. You must run `npm install` again to update new dependencies, and then run `npm start`. 1. To build the app, run `npm build`. Upload the contents of the build directory to your hosting provider. **Warning** The React app is **not** production ready. It's an example of deploying an app for Amazon Kendra search. ## Main search page The main search page (`Search.tsx`) contains all of the example search components. It includes the search bar component for output, the results components to display the response from the [Query](https://docs.aws.amazon.com/kendra/latest/APIReference/API_Query.html) API, and a pagination component for paging through the response. ## Search component The search component provides a text box to enter query text. The `onSearch` function is a hook that calls the main function in `Search.tsx` to make the Amazon Kendra [Query](https://docs.aws.amazon.com/kendra/latest/APIReference/API_Query.html) API call. ## Results component The results component shows the response from the `Query` API. The results are shown in three separate areas. + Suggested answers—These are the top results returned by the `Query` API. It contains up to three suggested answers. In the response, they have the result type `ANSWER`. + FAQ answers—These are the frequently asked questions results returned by the response. FAQs are added to the index separately. In the response, they have the type `QUESTION_ANSWER`. For more information, see [Questions and answers](https://docs.aws.amazon.com/kendra/latest/dg/in-creating-faq.html). + Recommended documents—These are additional documents that Amazon Kendra returns in the response. In the response from the `Query` API, they have the type `DOCUMENT`. The results components share a set of components for features like highlighting, titles, links, and more. The shared components must be present for the result components to work. ## Facets component The facets component lists the facets available in the search results. Each facet classifies the response along a specific dimension, such as author. You can refine the search to a specific facet by choosing one from the list. After you select a facet, the component calls `Query` with an attribute filter that restricts the search to documents that match the facet. ## Pagination component The pagination component allows you to display the search results from the `Query` API in multiple pages. It calls the `Query` API with the `PageSize` and `PageNumber` parameters to get a specific page of results. # Building a search experience with no code Deploying a search application with no code You can build and deploy an Amazon Kendra search application without the need for any front-end code. Amazon Kendra *Experience Builder* helps you build and deploy a fully functional search application in a few clicks so that you can start searching right away. You can custom design your search page and tune your search to tailor the experience to your users' needs. Amazon Kendra generates a unique, fully hosted endpoint URL of your search page to start searching your documents and FAQs. You can quickly build a proof of concept of your search experience and share it with others. You use the search experience template available in the builder to customize your search. You can invite others to collaborate in building your search experience, or evaluate search results for tuning purposes. Once your search experience is ready for your users to start searching, you simply share the secure endpoint URL. ## How the search Experience Builder works The overall process of building a search experience is as follows: 1. You create your search experience by giving it a name, description, and choosing your data sources you want to use for your search experience. 1. You configure your list of users and groups in AWS IAM Identity Center and then assign them access rights to your search experience. You include yourself as an owner of the experience. For more information, see [Providing access to your search page](#access-search-experience). 1. You open the Amazon Kendra Experience Builder to design and tune your search page. You can share your endpoint URL of your search experience with others who you assign own-edit access rights or view-search access rights. You call the [CreateExperience](https://docs.aws.amazon.com/kendra/latest/APIReference/API_CreateExperience.html) API to create and configure your search experience. If you use the console, you select your index and then select **Experiences** in the navigation menu to configure your experience. ## Design and tune your search experience Once you create and configure your search experience, you open the search experience using an endpoint URL to start customizing your search as an owner with editor access rights. You type your query into the search box, then customize your search using the editing options on the side panel to see how they apply to your page. When you are ready to publish, select **Publish**. You can also toggle between **Switch to live view**, to view the latest published version of your search page, and **Switch to build mode**, to edit or customize your search page. The following are ways you can customize your search experience. ### Filter Add faceted search or filter by document attributes. This includes custom attributes. You can add a filter using your own configured metadata fields. For example, to facet search by each city category, use a `_category` custom document attribute that contains all the city categories. ### Suggested answer Add machine learning generated answers to your users' queries. For example, *'How difficult is this course?'*. Amazon Kendra can retrieve the most relevant text across all documents referring to a course's difficulty and suggest the most relevant answer. ### FAQ Add a FAQ document to provide answers to frequently asked questions. For example, *'How many hours to complete this course?'*. Amazon Kendra can use the FAQ document containing the answer to this question and give the correct answer. ### Sort Add sorting of the search results so that your users can organize the results by relevancy, created time, last updated time, and other sorting criteria. ### Documents Configure how documents or search results are displayed on your search page. You can configure how many results display on the page, include pagination such as page numbers, activate a user feedback button, and arrange how document metadata fields are displayed in a search result. ### Language Select a language to filter the search results or documents in the selected language. ### Search box Configure the size and placeholder text of your search box, as well as allow query suggestions. ### Relevance tuning Add boosting to document metadata fields to place more weight on these fields when your users search for documents. You can add a weight that starts at 1 and incrementally increases to 10. You can boost text, date, and numeric field types. For example, to give `_last_updated_at` and `_created_at` more weight or importance than other fields, give these fields a weight of 1 to 10, depending on their importance. You can apply different relevance tuning configurations for each search application or experience. ## Providing access to your search page Access to your search experience is through IAM Identity Center. When you configure your search experience, you grant other people listed in your Identity Center directory access to your Amazon Kendra search page. They receive an email that directs them to sign in using their credentials in IAM Identity Center to access the search page. You must set up IAM Identity Center at the organization level or account holder level in AWS Organizations. For more information on setting up IAM Identity Center, see [Getting started with IAM Identity Center](https://docs.aws.amazon.com/kendra/latest/dg/getting-started-aws-sso.html). You activate user identities in IAM Identity Center with your search experience and assign *Viewer* or *Owner* access permissions using the API or the console. + **Viewer**: Allowed to issue queries, receive suggested answers relevant to their search, and contribute their feedback to Amazon Kendra so that it keeps improving the search. + **Owner**: Allowed to customize the design of the search page, tune the search, and use the search application as a *Viewer*. Disabling access to viewers in the console is currently not supported. To assign other people access to your search experience, you first activate user identities in IAM Identity Center with your Amazon Kendra experience by using the [ExperienceConfiguration](https://docs.aws.amazon.com/kendra/latest/APIReference/API_ExperienceConfiguration.html) object. You specify the field name that contains the identifiers of your users such as user name or email address. You then grant your list of users access to your search experience using the [AssociateEntitiesToExperience](https://docs.aws.amazon.com/kendra/latest/APIReference/API_AssociateEntitiesToExperience.html) API and define their permissions as *Viewer* or *Owner* using the [AssociatePersonasToEntities](https://docs.aws.amazon.com/kendra/latest/APIReference/API_AssociatePersonasToEntities.html) API. You specify each user or group using the [EntityConfiguration](https://docs.aws.amazon.com/kendra/latest/APIReference/API_EntityConfiguration.html) object and whether that user or group is a *Viewer* or *Owner* using the [EntityPersonaConfiguraton](https://docs.aws.amazon.com/kendra/latest/APIReference/API_EntityPersonaConfiguration.html) object. To assign other people access to your search experience using the console, you first need to create an experience and confirm your identity and that you are an owner. Then you can assign other users or groups as viewers or owners. In the console, select your index and then select **Experiences** in the navigation menu. After you create your experience, you can select your experience from the list. Go to **Access management** to assign users or groups as viewers or owners. ## Configuring a search experience The following is an example of configuring or creating a search experience. ------ #### [ Console ] **To create an Amazon Kendra search experience** 1. In the left navigation pane, under **Indexes**, select **Experiences** and then select **Create experience**. 1. On the **Configure experience** page, enter a name and description for your experience, choose your content sources, and choose the IAM role for your experience. For more information on IAM roles, see [IAM roles for Amazon Kendra experiences](https://docs.aws.amazon.com/kendra/latest/dg/iam-roles.html). 1. On the **Confirm your identity from an Identity Center directory** page, select your user ID such as your email. If you do not have an Identity Center directory, simply enter your full name and email to create an Identity Center directory. This includes you as a user of the experience and automatically assigns you owner access rights. 1. On the **Review to open Experience Builder** page, review your configuration details and select **Create experience and open Experience Builder** to start editing your search page. ------ #### [ CLI ] **To create an Amazon Kendra experience** ``` aws kendra create-experience \ --name experience-name \ --description "experience description" \ --index-id index-id \ --role-arn arn:aws:iam::account-id:role/role-name \ --configuration '{"ExperienceConfiguration":[{"ContentSourceConfiguration":{"DataSourceIds":["data-source-1","data-source-2"]}, "UserIdentityConfiguration":"identity attribute name"}]}' aws kendra describe-experience \ --endpoints experience-endpoint-URL(s) ``` ------ #### [ Python ] **To create an Amazon Kendra experience** ``` import boto3 from botocore.exceptions import ClientError import pprint import time kendra = boto3.client("kendra") print("Create an experience.") # Provide a name for the experience name = "experience-name" # Provide an optional description for the experience description = "experience description" # Provide the index ID for the experience index_id = "index-id" # Provide the IAM role ARN required for Amazon Kendra experiences role_arn = "arn:aws:iam::${account-id}:role/${role-name}" # Configure the experience configuration = {"ExperienceConfiguration": [{ "ContentSourceConfiguration":{"DataSourceIds":["data-source-1","data-source-2"]}, "UserIdentityConfiguration":"identity attribute name" }] } try: experience_response = kendra.create_experience( Name = name, Description = description, IndexId = index_id, RoleArn = role_arn, Configuration = configuration ) pprint.pprint(experience_response) experience_endpoints = experience_response["Endpoints"] print("Wait for Amazon Kendra to create the experience.") while True: # Get the details of the experience, such as the status experience_description = kendra.describe_experience( Endpoints = experience_endpoints ) status = experience_description["Status"] print(" Creating experience. Status: "+status) time.sleep(60) if status != "CREATING": break except ClientError as e: print("%s" % e) print("Program ends.") ``` ------ #### [ Java ] **To create an Amazon Kendra** ``` package com.amazonaws.kendra; import java.util.concurrent.TimeUnit; import software.amazon.awssdk.services.kendra.KendraClient; import software.amazon.awssdk.services.kendra.model.CreateExperienceRequest; import software.amazon.awssdk.services.kendra.model.CreateExperienceResponse; import software.amazon.awssdk.services.kendra.model.DescribeExperienceRequest; import software.amazon.awssdk.services.kendra.model.DescribeExperienceResponse; import software.amazon.awssdk.services.kendra.model.ExperienceStatus; public class CreateExperienceExample { public static void main(String[] args) throws InterruptedException { System.out.println("Create an experience"); String experienceName = "experience-name"; String experienceDescription = "experience description"; String indexId = "index-id"; String experienceRoleArn = "arn:aws:iam::account-id:role/role-name"; KendraClient kendra = KendraClient.builder().build(); CreateExperienceRequest createExperienceRequest = CreateExperienceRequest .builder() .name(experienceName) .description(experienceDescription) .roleArn(experienceRoleArn) .configuration( ExperienceConfiguration .builder() .contentSourceConfiguration( ContentSourceConfiguration( .builder() .dataSourceIds("data-source-1","data-source-2") .build() ) ) .userIdentityConfiguration( UserIdentityConfiguration( .builder() .identityAttributeName("identity-attribute-name") .build() ) ).build() ).build(); CreateExperienceResponse createExperienceResponse = kendra.createExperience(createExperienceRequest); System.out.println(String.format("Experience response %s", createExperienceResponse)); String experienceEndpoints = createExperienceResponse.endpoints(); System.out.println(String.format("Wait for Kendra to create the experience.", experienceEndpoints)); while (true) { DescribeExperienceRequest describeExperienceRequest = DescribeExperienceRequest.builder().endpoints(experienceEndpoints).build(); DescribeExperienceResponse describeEpxerienceResponse = kendra.describeExperience(describeExperienceRequest); ExperienceStatus status = describeExperienceResponse.status(); TimeUnit.SECONDS.sleep(60); if (status != ExperienceStatus.CREATING) { break; } } System.out.println("Experience creation is complete."); } } ``` ------