IBM Cloud Docs
Elasticsearch search integration set up

Elasticsearch search integration set up

Plus Enterprise IBM Cloud Pak for Data

Elasticsearch powers your assistants to perform different types of searches such as metric, structured, unstructured, and semantic with higher accuracy and relevance by leveraging enterprise content. The data analytics engine in Elasticsearch expands the scope of search integration to larger data sets in assistants. In addition to this integration, you can enable conversational search for Elasticsearch in your assistant that helps to answer queries in a conversational manner.

You can also integrate with IBM Watson® Discovery. For more information about integrating Discovery, see IBM Watson® Discovery search integration set up.

When you change an existing search integration to Discovery to connect to Elasticsearch or vice-versa, the settings of the existing search integration are overwritten. For example, when you change from Discovery to Elasticsearch, the configuration of Discovery is deleted completely from the assistant.

Selecting Elasticsearch

To select Elasticsearch as the default search integration, use one of the following procedures:

  • Selecting Elasticsearch search integration from the Integrations page

    1. After you create a watsonx Assistant instance, go to Home > Integrations.
    2. Click Open inside the Search tile to view the "Open Search" window.
    3. In the "Open Search" window, select the Draft option in the dropdown if you want to set up Elasticsearch in your assistant’s draft environment. If you want to set up Elasticsearch in your assistant’s live environment, select the Live option in the dropdown.
    4. In the following "Edit an existing new search integration" window, select the Elasticsearch tile.
  • Selecting Elasticsearch search integration from the Environments page

    1. After you create a watsonx Assistant instance, go to Home > Environments.

    2. Select the Draft tab if you want to set up Elasticsearch in the draft environment. If you want to set up Elasticsearch in the live environment, select the Live tab.

    3. In the Resolution methods section, click Add inside the Search tile under Extensions if you want to add a new Elasticsearch search integration.

      If you already added the Elasticsearch search integration, you see the Open button instead of Add inside the Search tile under Extensions.

    4. In the "Set up a new search extension" window, select the Elasticsearch tile to see the "Search integration" dialog.

      Select Elasticsearch

Setting up Elasticsearch

To set up Elasticsearch on your assistant, use the following procedure:

  1. In the first section of the "Search integration" window, provide the following fields to enable your assistant to connect to your Elasticsearch instance:

    • Elasticsearch url

    • Elasticsearch port (optional)

    • Choose an authentication type

      • If you select Basic authentication, you must provide Elasticsearch username and Elasticsearch password.
      • If you select API key, you must provide Elasticsearch API key.

      Search integration

  2. Click Next to go to the Select an index section. Select an index has two options:

    • To use an existing index, select Use my index.
    • To create a new index, select Upload documents to a new index in your Elasticsearch instance.

Using an existing index

  1. In the Select index section, click Use my index to connect to an existing Elasticsearch index. The Use my index option is selected as default in your Elasticsearch set up.

  2. In the Use my index option, type the Elasticsearch index name.

  3. Click Next to go to the Enable conversational search (optional) section.

  4. Conversational search is available only in the Plus and Enterprise plans of watsonx Assistant. In the Enable conversational search (optional) section, switch the Conversational Search toggle to on if you want to activate conversational search. If you don't want to activate conversational search, switch the toggle to off. For more information about conversational search, see conversational search.

  5. Click Save and then Close.

Uploading documents to a new index Beta

Before you upload documents, your Elasticsearch instance must have the following prerequisites:

  • Elasticsearch 8.8 or above.

  • A paid or trial subscription of the Elasticsearch instance such as the Platinum Edition of IBM Cloud Databases for Elasticsearch or the Platinum or Enterprise subscription offered by Elastic.co.

  • A Machine Learning (ML) node with a minimum of 4 GB memory to deploy the ELSER model. For more information about the ELSER requirements, see ELSER requirements.

  • The documents that you upload must be in English.

If your Elasticsearch instance do not have the prerequisites for uploading document, you see the Requirements not met error message.

If there is a delay or failure in uploading documents even after having the prerequisites, you can consider scaling the inference performance of the ELSER model deployment by setting up parameters such as number_of_allocations and threads_per_allocation. For more information about scaling the inference performance, see Start trained model deployment API.

To upload documents to a new index, use the following procedure:

  1. In the Select index section of the Elasticsearch window, click Upload documents to a new index in your Elasticsearch instance.

    watsonx Assistant passes the uploaded documents to your Elasticsearch instance for storage, chunking, and indexing.

  2. In the Configure result content section, provide the following fields to map the title, body, and URL to the search response:

    • Title

      Search result title. Use the title, name, or similar type of field from the collection as the search result title.

      You must select something for the title or no search result response is displayed in the Facebook and Slack integrations.

    • Body

      Search result description. Use an abstract, summary, or highlight field from the collection as the search result body.

      You must select something for the body or no search result response is displayed in the Facebook and Slack integrations.

    • URL

      This field can be populated with any footer content that you want to include at the end of the search result.

    When you configure the query body in the Advanced Elasticsearch Settings to search the nested documents, you must ensure that the Title, Body, and URL are from the fields of the inner documents in your Elasticsearch index. For more information about using nested queries, see Elasticsearch nested query.

  3. Expand the Advanced Elasticsearch settings section to see the following text boxes:

    • Configure the filter array for Elasticsearch

      You define the filter as an array of objects so that you can create filters to arrange the content per the query body. For more information, see Configuring the custom filters.

    • Configure the query body for Elasticsearch

      The query body is used to manipulate the user requests into a format that the search expects. It controls the query forms, search fields, filters, and query size. In the REST API, the query body is an object representing the POST body for the _search request to Elasticsearch. THe query body has a "$QUERY" token to represent the customer's query, and a "$FILTER" token to represent the array of filters that are defined either in the search settings or at the step level.

      By default, Elasticsearch integration uses keyword search. You can use advanced search such as semantic search with ELSER, KNN dense vector search, nested queries to search the nested documents, or hybrid search. For more information about using different types of query body examples, see Query body examples.

      For more information about the Elasticsearch _search API request body, see Elasticsearch search API request body.

      You cannot customize the query body in the assistant with an existing Elasticsearch configuration.

  4. Use the Message, No results found and Connectivity issue tabs to customize different messages to share with users based on the successfulness of the search.

    Search result messages
    Tab Scenario Example message
    Message Search results are returned I found this information that might be helpful:
    No results found No search results are found I searched my knowledge base for information that might address your query, but did not find anything useful to share.
    Connectivity issue I was unable to complete the search for some reason I might have information that could help address your query, but am unable to search my knowledge base at the moment.
  5. Switch the Conversational Search toggle to on if you want to activate conversational search. If you don't want to activate conversational search, switch the toggle to off.

  6. Conversational search is available only in the Plus and Enterprise plans of watsonx Assistant. If you switch the Conversational Search toggle to on, you can see the citation titles in your assistant responses. For more information about conversational search, see conversational search.

  7. Click Save to save your settings.

  8. Click the Documents tab in the Elasticsearch window.

    The Documents tab is enabled only if you select Upload documents to a new index in your Elasticsearch instance option.

  9. Click Upload button. In the Upload documents section, you can drag and drop your files or do a single click to upload documents directly to your assistant.

    You can upload up to 20 documents at a time. Each document file size must not exceed 25 KB. The total size of all documents must not exceed 50 MB.

    Elasticsearch upload document

  10. After you upload the documents, you can see the upload status of your documents in a table in the Elasticsearch window.

  11. Status Ready indicates that your files are available for search.

  12. If the status indicates Error, you can delete the file by clicking the three dots next to the Error and click Delete.

    Elasticsearch upload error

  13. Skip this step if you do not want to change Elasticsearch instance credentials. If you want to change the Elasticsearch instance credentials, click the Instance tab, edit the credentials, and then click Save.

  14. Click Save and then Close to end the Elasticsearch set up.

Configuring your assistant to use Elasticsearch

After you configure the Elasticsearch search integration, you must configure your assistant to use Elasticsearch when the customer response matches no action. For more information about updating No matches to use search, see Use search when no action matches.

Testing Elasticsearch

You can test search integration with Elasticsearch in actions preview, the preview page, or by using the preview link.

In this example, the user asks, Tell me about a custom extension.

Search results are pulled from your knowledge base when conversational search is off. The answer is, I searched my knowledge base and found this information which might be useful.

ConversationalSearchToggleOff

A text-based reply from the best results in your knowledge base displays when conversational search is on.

ConversationalSearchToggleOn