Configuring the plugin - Amazon Personalize
Fields for the personalized_search_ranking response processorCreating a pipeline with Amazon OpenSearch ServiceCreating a pipeline with open source OpenSearch
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Configuring the plugin

After you install the Amazon Personalize Search Ranking plugin, you're ready to configure it by creating an OpenSearch search pipeline.

A search pipeline is a set of request and response processors that run sequentially in the order that you create them. When you create a search pipeline for the plugin, you specify a personalized_search_ranking response processor. For information about search pipelines, see Search pipelines.

Fields for the personalized_search_ranking response processor

For the personalized_search_ranking response processor, you specify the following fields:

  • campaign_arn (required) – Specify the Amazon Resource Name (ARN) of the Amazon Personalize campaign to use to personalize results.

  • item_id_field (optional) – If the _id field for an indexed document in OpenSearch doesn't correspond with your Amazon Personalize itemIds, specify the name of the field that does. By default, the plugin assumes that the _id data matches the itemId in your Amazon Personalize data.

  • recipe (required) – Specify the name of the Amazon Personalize recipe to use. You can specify only aws-personalized-ranking.

  • weight (required) – Specify the emphasis that the response processor puts on personalization when it re-ranks results. Specify a value within a range of 0.0–1.0. The closer to 1.0 that it is, the more likely it is that results from Amazon Personalize rank higher. If you specify 0.0, no personalization occurs and OpenSearch takes precedence.

  • tag (optional) – Specify an identifier for the processor.

  • iam_role_arn (required for OpenSearch Service, optional for open source OpenSearch) – For OpenSearch Service, provide the Amazon Resource Name (ARN) for the role that you created when setting up permissions for OpenSearch Service to access your Amazon Personalize resources. If your OpenSearch Service and Amazon Personalize resources exist in different accounts, specify the role that grants AssumeRole permissions for OpenSearch Service. For more information, see Configuring permissions when resources are in different accounts.

    For open source OpenSearch, if you use multiple roles to restrict permissions for different groups of users in your organization, specify the ARN of the role that has permission to access Amazon Personalize. If you use only the Amazon credentials in your OpenSearch keystore, you can omit this field.

  • aws_region (required) – The Amazon Region where you created your Amazon Personalize campaign.

  • ignore_failure (optional) – Specify whether the plugin ignores any processor failures. For values, specify true or false. For your production environments, we recommend that you specify true to avoid any interruptions for query responses. For test environments, you can specify false to view any errors that the plugin generates.

  • external_account_iam_role_arn – If you use OpenSearch Service, and your Amazon Personalize and OpenSearch Service resources exist in different accounts, specify the ARN of the role that has permission to access your Amazon Personalize resources. This role must exist in the same account as your Amazon Personalize resources. For more information, see Configuring permissions when resources are in different accounts.

Creating a pipeline with Amazon OpenSearch Service

You can use the following Python code to create a search pipeline with a personalized_search_ranking response processor on an OpenSearch Service domain. Replace domain endpoint with your domain endpoint URL. For example: https://<domain name>.<Amazon region>.es-staging.amazonaws.com.

import requests
from requests_auth_aws_sigv4 import AWSSigV4

domain_endpoint = 'domain endpoint'
pipeline_name = 'pipeline name'
url = f'{domain_endpoint}/_search/pipeline/{pipeline_name}'
auth = AWSSigV4('es')

headers = {'Content-Type': 'application/json'}

body = {
  "description": "A pipeline to apply custom re-ranking from Amazon Personalize",
  "response_processors": [
    {
      "personalized_search_ranking" : {
        "campaign_arn" : "Amazon Personalize Campaign ARN",
        "item_id_field" : "productId",
        "recipe" : "aws-personalized-ranking",
        "weight" : "0.3",
        "tag" : "personalize-processor",
        "iam_role_arn": "Role ARN",
        "aws_region": "Amazon region",
        "ignore_failure": true
    }
  ]
}
try:
    response = requests.put(url, auth=auth, json=body, headers=headers, verify=False)
    print(response.text)
except Exception as e:
    print(f"Error: {e}")

After you create a search pipeline with a personalized_search_ranking response processor, you're ready to start applying the plugin to OpenSearch queries. You can apply it to an OpenSearch index or an individual OpenSearch query. For more information, see Applying the plugin to OpenSearch queries.

Creating a pipeline with open source OpenSearch

You can use the following curl command to create a search pipeline with a personalized_search_ranking response processor on an open source OpenSearch cluster.

curl -X PUT "http://localhost:9200/_search/pipeline/pipeline-name" -ku 'admin:admin' --insecure -H 'Content-Type: application/json' -d'
{
  "description": "A pipeline to apply custom re-ranking from Amazon Personalize",
  "response_processors" : [
    {
      "personalized_search_ranking" : {
        "campaign_arn" : "Amazon Personalize Campaign ARN",
        "item_id_field" : "productId",
        "recipe" : "aws-personalized-ranking",
        "weight" : "0.3",
        "tag" : "personalize-processor",
        "iam_role_arn": "Role ARN",
        "aws_region": "Amazon region",
        "ignore_failure": true
      }
    }
  ]
}'

After you create a search pipeline with a personalized_search_ranking response processor, you're ready to start applying the plugin to OpenSearch queries. You can apply it to an OpenSearch index or an individual OpenSearch query. For more information, see Applying the plugin to OpenSearch queries.