# Custom resources for training and deploying Amazon Personalize models
Custom resources

 If you are using a custom recipe, after you [import data](import-data.md) you are ready to create the custom resources for training and deploying Amazon Personalize models. You use these resources to get recommendations. When you create custom resources, you do the following: 

1. **Create and configure a solution:** Customize solution parameters and recipe-specific hyperparameters so the model meets your specific business needs. By default, new solution versions use automatic training to create solution versions at a configurable frequency. The default frequency is every 7 days. For more information about configuring a solution, see [Configuring a solution](customizing-solution-config.md). For more information about custom recipes in Amazon Personalize, see [Choosing a recipe](working-with-predefined-recipes.md). 

1. **Create a solution version (for solutions that don't use automatic training):** For solutions that use automatic training, solution version creation starts automatically after your solution is active. For solutions that use manual training, you manually create a solution version. The solution version generates Amazon Personalize recommendations or user segments. For more information about manually creating a solution version, see [Manually creating a solution version](creating-a-solution-version.md). To stop solution version creation, navigate to the solution version details page and choose **Stop**. For more information, see [Stopping the creation of a solution version](stop-solution-version.md).

1.  **Evaluate the solution version** – Use the metrics Amazon Personalize generates from the new solution version to evaluate the performance of the model. See [Evaluating an Amazon Personalize solution version with metrics](working-with-training-metrics.md). 

1. **Deploy the solution version with a campaign (only for real-time recommendations):** Create a campaign to deploy your solution version. You use the campaign when you request real-time recommendations. If you are getting batch recommendations, you don't need to create a campaign. For more information, see [Deploying an Amazon Personalize solution version with a campaignCreating a campaign](campaigns.md). If you want to change an existing campaign's settings, such as enabling metadata in recommendations, you must update your campaign. For more information, see [Updating an Amazon Personalize campaign's configuration](update-campaigns.md). 

**Topics**
+ [

# Configuring a custom solution in Amazon Personalize
](customizing-solution-config.md)
+ [

# Updating a solution to change its automatic training configuration
](updating-solution.md)
+ [

# Manually creating a solution version
](creating-a-solution-version.md)
+ [

# Stopping the creation of a solution version
](stop-solution-version.md)
+ [

# Evaluating an Amazon Personalize solution version with metrics
](working-with-training-metrics.md)
+ [

# Deploying an Amazon Personalize solution version with a campaign
](campaigns.md)
+ [

# Updating an Amazon Personalize campaign's configuration
](update-campaigns.md)

# Configuring a custom solution in Amazon Personalize
Configuring a solution

After you finish importing data, you are ready to create a solution. A *solution* refers to the combination of an Amazon Personalize recipe, customized training parameters, and one or more solution versions. A *solution version* refers to a trained machine learning model.

By default, all new solutions use automatic training to create a new solution version every 7 days. Automatic training occurs only if you imported bulk or real-time interaction data since the last training. This includes item interactions or, for solutions that use the Next-Best-Action recipe, action interactions data. Automatic training continues until you delete the solution. For more information, see [Configuring automatic training](solution-config-auto-training.md). 

If you have an existing solution, you can use the Amazon Personalize console to clone the solution. When you clone a solution, you can use the configuration of the existing solution as a starting point, such as the recipe and hyperparameters, and make any changes. For more information, see [Cloning a solution (console)](cloning-solution.md). 

You can create and configure a solution by using the console, AWS Command Line Interface (AWS CLI), or AWS SDKs. After you create a solution, you can view its configuration details on the solution's details page of the Amazon Personalize console, or with the [DescribeSolution](API_DescribeSolution.md) operation.

By default, all new solutions use automatic training. With automatic training, you incur training costs while your solution is active. To avoid unnecessary costs, when you are finished you can [update the solution](updating-solution.md) to turn off automatic training. For information about training costs, see [Amazon Personalize pricing](https://aws.amazon.com/personalize/pricing/).

**Topics**
+ [

# Creating a solution
](create-solution.md)
+ [

# Configuring automatic training
](solution-config-auto-training.md)
+ [

# Configuring columns used when training
](custom-config-columns.md)
+ [

# Optimizing a solution for an additional objective
](optimizing-solution-for-objective.md)
+ [

# Optimizing a solution with events configuration
](optimizing-solution-events-config.md)
+ [

# Hyperparameters and HPO
](customizing-solution-config-hpo.md)
+ [

# Choosing the item interaction data used for training
](event-values-types.md)
+ [

# Cloning a solution (console)
](cloning-solution.md)

# Creating a solution


You can create a custom solution with the Amazon Personalize console, AWS Command Line Interface (AWS CLI), or AWS SDKs. The following includes detailed steps to create a solution with the Amazon Personalize console and code examples that show how to create a solution with only the required fields. 

**Topics**
+ [

## Creating a solution (console)
](#configure-solution-console)
+ [

## Creating a solution (AWS CLI)
](#configure-solution-cli)
+ [

## Creating a solution (AWS SDKs)
](#configure-solution-sdk)

## Creating a solution (console)


**Important**  
By default, all new solutions use automatic training. With automatic training, you incur training costs while your solution is active. To avoid unnecessary costs, when you are finished you can [update the solution](updating-solution.md) to turn off automatic training. For information about training costs, see [Amazon Personalize pricing](https://aws.amazon.com/personalize/pricing/).

 To create a solution in the console, choose your dataset group and then specify a solution name, recipe, and optional training configuration. 

**To configure a solution (console)**

1. Open the Amazon Personalize console at [https://console.aws.amazon.com/personalize/home](https://console.aws.amazon.com/personalize/home), and sign in to your account.

1. On the **Dataset groups** page, choose your dataset group.

1. On the **Overview** page, for **Step 3**, do one of the following:
   + If you created a Domain dataset group, choose **Use custom resources**, and choose **Create solutions**.
   + If you created a Custom dataset group, choose **Create solutions**. 

1. For **Solution name**, specify a name for your solution.

1. For **Solution type**, choose the type of solution that you want to create. The type you choose determines what recipes are available. 
   + Choose **Item recommendation** to get item recommendations for your users. For example, personalized movie recommendations. 
   + Choose **Action recommendation** to get action recommendations for your users. For example, generate the next best action for a user, such as download your app. 
   + Choose **User segmentation** to get user segments (groups of users) based on your item data.

1. For **Recipe**, choose a recipe (see [Choosing a recipe](working-with-predefined-recipes.md)). 

1. For **Tags**, optionally add any tags. For more information about tagging Amazon Personalize resources, see [Tagging Amazon Personalize resources](tagging-resources.md).

1. Choose **Next**.

1. On the **Training configuration** page, customize the solution to meet your business requirements. 
   + In **Automatic training**, choose whether the solution uses automatic training. If you use automatic training, you can change the `Automatic training frequency`. The default training frequency is every 7 days. 

     We recommend using automatic training. It makes it easier for you to maintain recommendation relevance. Your training frequency depends on your business requirements, the recipe that you use, and how frequently you import data. For more information, see [Configuring automatic training](solution-config-auto-training.md). For information about maintaining relevance, see [Maintaining recommendation relevance](maintaining-relevance.md).
   + In **Hyperparameter configuration**, configure any hyperparameter options based on your recipe and business needs. Different recipes use different hyperparameters. For the hyperparameters available to you, see the individual recipes in [Choosing a recipe](working-with-predefined-recipes.md). 
   + In **Columns for training**, if your recipe generates item recommendations or user segments, optionally choose the columns that Amazon Personalize considers when creating solution versions. For more information, see [Configuring columns used when training](custom-config-columns.md). 
   + In **Event configuration**, if your Item interactions dataset has EVENT\$1TYPE or both EVENT\$1TYPE and EVENT\$1VALUE columns, optionally use the **Event type** and **Event value threshold** fields to choose the item interactions data that Amazon Personalize uses when training the model. For more information, see [Choosing the item interaction data used for training](event-values-types.md). 

      If you have multiple event types and use the User-Personalization-v2 recipe or Personalized-Ranking-v2 recipe, you can also specify different weights for different types. For example, you can configure a solution to give more weight to purchase events than click events. For more information, see [Optimizing a solution with events configuration](optimizing-solution-events-config.md). 
   + If you use either the [User-Personalization recipe](native-recipe-new-item-USER_PERSONALIZATION.md) or [Personalized-Ranking recipe](native-recipe-search.md) recipe, optionally specify an **Objective** and choose an **Objective sensitivity** to optimize your solution for an objective in addition to relevance. The objective sensitivity configures how Amazon Personalize balances recommending items based on your objective compared with relevance through interactions data. For more information, see [Optimizing a solution for an additional objective](optimizing-solution-for-objective.md).

1. Choose **Next** and review the solution details. You can't change your solution's configuration after you create it.

1. Choose **Create solution**. After you create a solution, Amazon Personalize starts creating your first solution version within an hour. When training starts, you can monitor it in the **Solution versions** section on the details page for you solution. Automatically created solution versions have a **Training type** of AUTOMATIC. 

    When the solution version is ACTIVE, you are ready to use it to get recommendations. How you use an active solution version depends on how you get recommendations:
   +  For real-time recommendations, you deploy an ACTIVE solution version with an Amazon Personalize campaign. You use the campaign to get recommendations for your users. See [Deploying an Amazon Personalize solution version with a campaignCreating a campaign](campaigns.md).
   + For batch recommendations, you specify an ACTIVE solution version when you create a batch inference job or batch segment job. See [Getting batch item recommendations](getting-batch-recommendations.md) or [Getting batch user segments](getting-user-segments.md).

## Creating a solution (AWS CLI)


**Important**  
By default, all new solutions use automatic training. With automatic training, you incur training costs while your solution is active. To avoid unnecessary costs, when you are finished you can [update the solution](updating-solution.md) to turn off automatic training. For information about training costs, see [Amazon Personalize pricing](https://aws.amazon.com/personalize/pricing/).

To create a solution with the AWS CLI, use the `create-solution` command. This command uses the [CreateSolution](API_CreateSolution.md) API operation. The following code shows you how to create a solution that uses automatic training. It automatically creates a new solution version every five days.

To use the code, update it to give the solution a name, specify the Amazon Resource Name (ARN) of your dataset group, optionally change the training frequency, and specify the ARN of the recipe to use. For information about recipes, see [Choosing a recipe](working-with-predefined-recipes.md). 

```
aws personalize create-solution \
--name solution name \
--dataset-group-arn dataset group ARN \
--recipe-arn recipe ARN \
--perform-auto-training \
--solution-config "{\"autoTrainingConfig\": {\"schedulingExpression\": \"rate(5 days)\"}}"
```
+ We recommend that you use automatic training. It makes it easier for you to maintain and improve recommendation relevance. By default, all new solutions use automatic training. The default training frequency is every 7 days. Your training frequency depends on your business requirements, the recipe that you use, and how frequently you import data. For more information, see [Configuring automatic training](solution-config-auto-training.md). 
+ Depending on your recipe, you can modify the code to configure recipe specific properties and hyperparameters (see [Hyperparameters and HPO](customizing-solution-config-hpo.md)), configure the columns used for training (see [Configuring columns used when training (AWS CLI)](custom-config-columns.md#custom-config-columns-cli)), or filter the item interactions data used for training (see [Choosing the item interaction data used for training](event-values-types.md)). 
+ If you use either the [User-Personalization recipe](native-recipe-new-item-USER_PERSONALIZATION.md) or [Personalized-Ranking recipe](native-recipe-search.md) recipe, you can optimize your solution for an objective, in addition to relevance. For more information, see [Optimizing a solution for an additional objective](optimizing-solution-for-objective.md).

After you create the solution, record the solution ARN for future use. With automatic training, solution version creation starts within one hour after the solution is ACTIVE. If you manually create a solution version within the hour, the solution skips the first automatic training. After training starts, you can get the solution version's Amazon Resource Name (ARN) with the [ListSolutionVersions](https://docs.aws.amazon.com/personalize/latest/dg/API_ListSolutionVersions.html) API operation. To get its status, use the [DescribeSolutionVersion](https://docs.aws.amazon.com/personalize/latest/dg/API_DescribeSolutionVersion.html) API operation. 

 When the solution version is ACTIVE, you are ready to use it to get recommendations. How you use an active solution version depends on how you get recommendations:
+  For real-time recommendations, you deploy an ACTIVE solution version with an Amazon Personalize campaign. You use the campaign to get recommendations for your users. See [Deploying an Amazon Personalize solution version with a campaignCreating a campaign](campaigns.md).
+ For batch recommendations, you specify an ACTIVE solution version when you create a batch inference job or batch segment job. See [Getting batch item recommendations](getting-batch-recommendations.md) or [Getting batch user segments](getting-user-segments.md).

## Creating a solution (AWS SDKs)


**Important**  
By default, all new solutions use automatic training. With automatic training, you incur training costs while your solution is active. To avoid unnecessary costs, when you are finished you can [update the solution](updating-solution.md) to turn off automatic training. For information about training costs, see [Amazon Personalize pricing](https://aws.amazon.com/personalize/pricing/).

To create a solution with AWS SDKs, use the [CreateSolution](API_CreateSolution.md) API operation. The following code shows you how to create a solution that uses automatic training. It automatically creates a new solution version every five days.

To use the code, update it to give the solution a name, specify the Amazon Resource Name (ARN) of your dataset group, optionally change the training frequency, and specify the ARN of the recipe that you want to use. For information about recipes, see [Choosing a recipe](working-with-predefined-recipes.md). 

------
#### [ SDK for Python (Boto3) ]

```
import boto3

personalize = boto3.client('personalize')

create_solution_response = personalize.create_solution(
  name = 'solution name',
  recipeArn = 'recipe ARN',
  datasetGroupArn = 'dataset group ARN',
  performAutoTraining = True,
  solutionConfig = {
    "autoTrainingConfig": {
      "schedulingExpression": "rate(5 days)"
    }
  }
)
solution_arn = create_solution_response['solutionArn']
print('solution_arn: ', solution_arn)
```

------
#### [ SDK for JavaScript v3 ]

```
import {
  CreateSolutionCommand,
  PersonalizeClient,
} from "@aws-sdk/client-personalize";

// create client
const personalizeClient = new PersonalizeClient({ region: "REGION" });

// set the solution parameters
export const solutionParam = {
  datasetGroupArn: "DATASET_GROUP_ARN" /* required */,
  recipeArn: "RECIPE_ARN" /* required */,
  name: "SOLUTION_NAME" /* required */,
  performAutoTraining: true /* optional, default is true */,
  solutionConfig: {
    autoTrainingConfig: {
      schedulingExpression:
        "rate(5 days)" /* optional, default is every 7 days */,
    },
  },
};

export const run = async () => {
  try {
    const response = await personalizeClient.send(
      new CreateSolutionCommand(solutionParam)
    );
    console.log("Success", response);
    return response; // For unit tests.
  } catch (err) {
    console.log("Error", err);
  }
};
run();
```

------
+ We recommend that you use automatic training. It makes it easier for you to maintain and improve recommendation relevance. By default, all new solutions use automatic training. The default training frequency is every 7 days. Your training frequency depends on your business requirements, the recipe that you use, and how frequently you import data. For more information, see [Configuring automatic training](solution-config-auto-training.md). 
+ Depending on your recipe, you can modify the code to configure recipe specific properties and hyperparameters (see [Hyperparameters and HPO](customizing-solution-config-hpo.md)), configure the columns used for training (see [Configuring columns used when training (AWS SDKs)](custom-config-columns.md#custom-configure-columns-sdk)), or filter the item interactions data used for training (see [Choosing the item interaction data used for training](event-values-types.md)). 
+ If you use either the [User-Personalization recipe](native-recipe-new-item-USER_PERSONALIZATION.md) or [Personalized-Ranking recipe](native-recipe-search.md) recipe, you can optimize your solution for an objective, in addition to relevance. For more information, see [Optimizing a solution for an additional objective](optimizing-solution-for-objective.md).

After you create the solution, record the solution ARN for future use. With automatic training, solution version creation starts within one hour after the solution is ACTIVE. If you manually create a solution version within the hour, the solution skips the first automatic training. After training starts, you can get the solution version's Amazon Resource Name (ARN) with the [ListSolutionVersions](https://docs.aws.amazon.com/personalize/latest/dg/API_ListSolutionVersions.html) API operation. To get its status, use the [DescribeSolutionVersion](https://docs.aws.amazon.com/personalize/latest/dg/API_DescribeSolutionVersion.html) API operation. 

You can use the following Python code to wait for automatic training to start. The `wait_for_training_to_start` method returns the ARN of the first solution version.

```
import time
import boto3


def wait_for_training_to_start(new_solution_arn):
    max_time = time.time() + 3 * 60 * 60    # 3 hours
    while time.time() < max_time:
        list_solution_versions_response = personalize.list_solution_versions(
            solutionArn=new_solution_arn
        )
        solution_versions = list_solution_versions_response.get('solutionVersions', [])
        if solution_versions:
            new_solution_version_arn = solution_versions[0]['solutionVersionArn']
            print(f"Solution version ARN: {new_solution_version_arn}")
            return new_solution_version_arn
        else:
            print(f"Training hasn't started yet. Training will start within the next hour.")
            time.sleep(60)


personalize = boto3.client('personalize')

solution_arn = "solution_arn"
solution_version_arn = wait_for_training_to_start(solution_arn)
```

 When the solution version is ACTIVE, you are ready to use it to get recommendations. How you use an active solution version depends on how you get recommendations:
+  For real-time recommendations, you deploy an ACTIVE solution version with an Amazon Personalize campaign. You use the campaign to get recommendations for your users. See [Deploying an Amazon Personalize solution version with a campaignCreating a campaign](campaigns.md).
+ For batch recommendations, you specify an ACTIVE solution version when you create a batch inference job or batch segment job. See [Getting batch item recommendations](getting-batch-recommendations.md) or [Getting batch user segments](getting-user-segments.md).

# Configuring automatic training


**Important**  
By default, all new solutions use automatic training. With automatic training, you incur training costs while your solution is active. To avoid unnecessary costs, when you are finished you can [update the solution](updating-solution.md) to turn off automatic training. For information about training costs, see [Amazon Personalize pricing](https://aws.amazon.com/personalize/pricing/).

When you create a solution, you can configure whether the solution uses automatic training. You can also configure the training frequency. For example, you can configure the solution to create a new solution version every five days.

By default, all new solutions use automatic training to create a new solution version every 7 days. Automatic training occurs only if you imported bulk or real-time interaction data since the last training. This includes item interactions or, for solutions that use the Next-Best-Action recipe, action interactions data. Automatic training continues until you delete the solution. 

We recommend that you use automatic training. It makes maintaining your solution easier. It removes the manual training required for the solution to learn from your most recent data. Without automatic training, you must manually create new solution versions for the solution to learn from your most recent data. This can result in stale recommendations and a lower conversion rate. For more information about maintaining Amazon Personalize recommendations, see [Maintaining recommendation relevance](maintaining-relevance.md). 

You can configure automatic training with the Amazon Personalize console, AWS Command Line Interface (AWS CLI), or AWS SDKs. For steps on configuring automatic training with the console, see [Creating a solution (console)](create-solution.md#configure-solution-console). 

After you create the solution, record the solution ARN for future use. With automatic training, solution version creation starts within one hour after the solution is ACTIVE. If you manually create a solution version within the hour, the solution skips the first automatic training. After training starts, you can get the solution version's Amazon Resource Name (ARN) with the [ListSolutionVersions](https://docs.aws.amazon.com/personalize/latest/dg/API_ListSolutionVersions.html) API operation. To get its status, use the [DescribeSolutionVersion](https://docs.aws.amazon.com/personalize/latest/dg/API_DescribeSolutionVersion.html) API operation. 

**Topics**
+ [

## Guidelines and requirements
](#auto-training-guidelines)
+ [

## Configuring automatic training (AWS CLI)
](#configure-solution-auto-training-cli)
+ [

## Configuring automatic training (SDKs)
](#configure-solution-auto-training-sdk)

## Guidelines and requirements


The following are guidelines and requirements for automatic training:
+  Automatic training occurs only if you imported bulk or real-time interaction data since the last training. This includes item interactions or, for solutions that use the Next-Best-Action recipe, action interactions data. 
+ Each training considers all of the data in your dataset group that you include in training. For information about configuring the columns used in training, see [Configuring columns used when training](custom-config-columns.md).
+ You can still manually create solution versions.
+ Automatic training starts within one hour after your solution is active. If you manually create a solution version within the hour, the solution skips the first automatic training. 
+ Training scheduling is based on training start date. For example, if your first solution version starts training at 7:00 pm, and you use weekly training, the next solution version will start training a week later at 7:00 pm. 
+ For all recipes, we recommend at least a weekly training frequency. You can specify a training frequency between 1 and 30 days. The default is every 7 days. 
  +  If you use User-Personalization-v2, User-Personalization, or Next-Best-Action, the solution automatically updates to consider new items or actions for recommendations. Automatic updates aren't the same as automatic training. An automatic update doesn't create a completely new solution version, and the model doesn't learn from your most recent data. To maintain your solution, your training frequency should still be at least weekly. For more formation about automatic updates, including additional guidelines and requirements, see [Automatic updates](use-case-recipe-features.md#automatic-updates).
  + If you use Trending-Now, Amazon Personalize automatically identifies the top trending items in your interactions data over a configurable interval of time. Trending-Now can recommend items added since the last training through bulk or streaming interactions data. Your training frequency should still be at least weekly. For more information, see [Trending-Now recipe](native-recipe-trending-now.md).
  + If you don't use a recipe with automatic updates or the Trending-Now recipe, Amazon Personalize considers new items for recommendations only after the next training. For example, if you use the Similar-Items recipe and add new items daily, you would have to use a daily automatic training frequency for these items to appear in recommendations that same day.

## Configuring automatic training (AWS CLI)


The following code shows you how to create a solution that automatically creates a solution version every five days. To turn off automatic training, set `perform-auto-training` to `false`. 

To change the training frequency, you can modify the `schedulingExpression` in the `autoTrainingConfig`. The expression must be in `rate(value unit)` format. For the value, specify a number between 1 and 30. For the unit, specify `day` or `days`. 

For a full explanation of the `create-solution` command, see [Creating a solution (AWS CLI)](create-solution.md#configure-solution-cli).

```
aws personalize create-solution \
--name solution name \
--dataset-group-arn dataset group ARN \
--recipe-arn recipe ARN \
--perform-auto-training \
--solution-config "{\"autoTrainingConfig\": {\"schedulingExpression\": \"rate(5 days)\"}}"
```

## Configuring automatic training (SDKs)


The following code shows you how to create a solution with automatic training with the AWS SDKs. The solution automatically creates a solution version every five days. To turn off automatic training, set `performAutoTraining` to `false`. 

To change the training frequency, you can modify the `schedulingExpression` in the `autoTrainingConfig`. The expression must be in `rate(value unit)` format. For the value, specify a number between 1 and 30. For the unit, specify `day` or `days`. 

For a full explanation of the CreateSolution API operation, see [Creating a solution (AWS SDKs)](create-solution.md#configure-solution-sdk).

------
#### [ SDK for Python (Boto3) ]

```
import boto3

personalize = boto3.client('personalize')

create_solution_response = personalize.create_solution(
  name = 'solution name',
  recipeArn = 'recipe ARN',
  datasetGroupArn = 'dataset group ARN',
  performAutoTraining = True,
  solutionConfig = {
    "autoTrainingConfig": {
      "schedulingExpression": "rate(5 days)"
    }
  }
)
solution_arn = create_solution_response['solutionArn']
print('solution_arn: ', solution_arn)
```

------
#### [ SDK for JavaScript v3 ]

```
import {
  CreateSolutionCommand,
  PersonalizeClient,
} from "@aws-sdk/client-personalize";

// create client
const personalizeClient = new PersonalizeClient({ region: "REGION" });

// set the solution parameters
export const solutionParam = {
  datasetGroupArn: "DATASET_GROUP_ARN" /* required */,
  recipeArn: "RECIPE_ARN" /* required */,
  name: "SOLUTION_NAME" /* required */,
  performAutoTraining: true /* optional, default is true */,
  solutionConfig: {
    autoTrainingConfig: {
      schedulingExpression:
        "rate(5 days)" /* optional, default is every 7 days */,
    },
  },
};

export const run = async () => {
  try {
    const response = await personalizeClient.send(
      new CreateSolutionCommand(solutionParam)
    );
    console.log("Success", response);
    return response; // For unit tests.
  } catch (err) {
    console.log("Error", err);
  }
};
run();
```

------

You can use the following Python code to wait for automatic training to start. The `wait_for_training_to_start` method returns the ARN of the first solution version.

```
import time
import boto3

def wait_for_training_to_start(new_solution_arn):
    max_time = time.time() + 3 * 60 * 60    # 3 hours
    while time.time() < max_time:
        list_solution_versions_response = personalize.list_solution_versions(
            solutionArn=new_solution_arn
        )
        solution_versions = list_solution_versions_response.get('solutionVersions', [])
        if solution_versions:
            new_solution_version_arn = solution_versions[0]['solutionVersionArn']
            print(f"Solution version ARN: {new_solution_version_arn}")
            return new_solution_version_arn
        else:
            print(f"Training hasn't started yet. Training will start within the next hour.")
            time.sleep(60)


personalize = boto3.client('personalize')

solution_arn = "solution_arn"
solution_version_arn = wait_for_training_to_start(solution_arn)
```

# Configuring columns used when training


**Important**  
By default, all new solutions use automatic training. With automatic training, you incur training costs while your solution is active. To avoid unnecessary costs, when you are finished you can [update the solution](updating-solution.md) to turn off automatic training. For information about training costs, see [Amazon Personalize pricing](https://aws.amazon.com/personalize/pricing/).

If your recipe generates item recommendations or user segments, you can modify the columns Amazon Personalize considers when creating a solution version (training a model). 

You can change the columns used when training to control what data Amazon Personalize uses when training a model (creating a solution version). You might do this to experiment with different combinations of training data. Or you might exclude columns without meaningful data. For example, might have a column that you want to use only to filter recommendations. You can exclude this column from training and Amazon Personalize considers it only when filtering.

You can't exclude EVENT\$1TYPE columns. By default, Amazon Personalize uses all columns that can be used when training. The following data is always excluded from training:
+ Columns with the boolean data type
+ [Impressions data](interactions-datasets.md#interactions-impressions-data)
+ Custom string fields that aren't categorical or textual

 You can't include impressions data in training, but if your use case or recipe uses it, Amazon Personalize uses impressions data to guide exploration when you get recommendations.

 If you have already created a solution and you want to modify the columns it uses when training, you can clone the solution. When you clone a solution, you can use the configuration of the existing solution as a starting point, such as the recipe and hyperparameters, and make any changes as necessary. For more information, see [Cloning a solution (console)](cloning-solution.md). 

You can configure the columns Amazon Personalize uses when training with the Amazon Personalize console, AWS Command Line Interface (AWS CLI), or AWS SDK. For information about choosing columns with the Amazon Personalize console, see the advanced configuration steps in [Creating a solution (console)](create-solution.md#configure-solution-console). After you create a solution, you can view the columns the solution uses on the solution's details page of the Amazon Personalize console, or with the [DescribeSolution](API_DescribeSolution.md) operation. 

**Topics**
+ [

## Configuring columns used when training (AWS CLI)
](#custom-config-columns-cli)
+ [

## Configuring columns used when training (AWS SDKs)
](#custom-configure-columns-sdk)

## Configuring columns used when training (AWS CLI)


To exclude columns from training, provide the `excludedDatasetColumns` object in the `trainingDataConfig` as part of the solution configuration. For each key, provide the dataset type. For each value, provide the list of columns to exclude. The following code shows how to exclude columns from training when you create a solution with the AWS CLI. 

```
aws personalize create-solution \
--name solution name \
--dataset-group-arn dataset group ARN \
--recipe-arn recipe ARN \
--solution-config "{\"trainingDataConfig\": {\"excludedDatasetColumns\": { \"datasetType\" : [ \"column1Name\", \"column2Name\"]}}}"
```

## Configuring columns used when training (AWS SDKs)


To exclude columns from training, provide the `excludedDatasetColumns` object in the `trainingDataConfig` as part of the solution configuration. For each key, provide the dataset type. For each value, provide the list of columns to exclude. The following code shows how to exclude columns from training when you create a solution with the SDK for Python (Boto3). 

```
import boto3

personalize = boto3.client('personalize')

create_solution_response = personalize.create_solution(
  name = 'solution name',
  recipeArn = 'recipe ARN',
  datasetGroupArn = 'dataset group ARN',
  solutionConfig = {
    "trainingDataConfig": {
      "excludedDatasetColumns": { 
          "datasetType": ["COLUMN_A", "COLUMN_B"]
      }
    }
  }
)
solution_arn = create_solution_response['solutionArn']
print('solution_arn: ', solution_arn)
```

# Optimizing a solution for an additional objective
Optimizing a solution for an additional objective

**Important**  
By default, all new solutions use automatic training. With automatic training, you incur training costs while your solution is active. To avoid unnecessary costs, when you are finished you can [update the solution](updating-solution.md) to turn off automatic training. For information about training costs, see [Amazon Personalize pricing](https://aws.amazon.com/personalize/pricing/).

 If you use the User-Personalization recipe or Personalized-Ranking recipe, you can optimize an Amazon Personalize solution for an objective in addition to maximum relevance, such as maximizing revenue.

 With item recommendation recipes, the primary objective of Amazon Personalize is to predict the most relevant items for your users based on historical and real-time item interactions data. These are the items your users will most likely interact with (for example, the items they will most likely click). If you have an additional objective, such as maximizing streaming minutes or increasing revenue, you can create a solution that generates recommendations based on both relevance and your objective. 

To optimize a solution for an additional objective, create a new solution with the User-Personalization recipe or Personalized-Ranking recipe and choose the numerical metadata column in your Items dataset that is related to your objective. When generating recommendations, Amazon Personalize gives more importance to items with higher values for this column of data. For example, you might choose a VIDEO\$1LENGTH column to maximize streaming minutes or a PRICE column to maximize revenue. 

You can use the Amazon Personalize console, AWS Command Line Interface (AWS CLI), or AWS SDKs. For information about using the Amazon Personalize console, see [Creating a solution (console)](create-solution.md#configure-solution-console). 

**Topics**
+ [

## Guidelines and requirements
](#optimize-objective-guidelines-req)
+ [

## Balancing objective emphasis and relevance
](#balancing-objective-emphasis)
+ [

## Measuring optimization performance
](#measuring-performance)
+ [

## Optimizing a solution (AWS CLI)
](#optimizing-solution-cli)
+ [

## Optimizing a solution (AWS SDKs)
](#optimizing-solution-sdk)
+ [

## Sample Jupyter notebook
](#optimization-objective-sample-notebooks)

## Guidelines and requirements


 Objective requirements are as follows: 
+ You can choose only one column for your objective.
+ The column must have a numerical type in your schema.
+ The column can't have a `null` type in your schema.

For more information about schemas and data types, see [Creating schema JSON files for Amazon Personalize schemas](how-it-works-dataset-schema.md).

## Balancing objective emphasis and relevance


 There can be a trade-off when recommending items based more on your objective than relevance. For example, if you want to increase revenue through recommendations, recommendations for only expensive items might make items less relevant for your users and decrease user engagement and conversion. 

To configure the balance between relevance and your objective, choose one of the following objective sensitivity levels when you create the solution: 
+ Off: Amazon Personalize uses primarily item interactions data to predict the most relevant items for your user.
+ Low: Amazon Personalize places less emphasis on your objective. Relevance through item interactions data is more important.
+ Medium: Amazon Personalize places equal emphasis on your objective and relevance through item interactions data.
+ High: Amazon Personalize places more emphasis on your objective. Relevance through item interactions data is less important.

## Measuring optimization performance


When you create a solution version (train a model) for a solution with an optimization objective, Amazon Personalize generates an `average_rewards_at_k` metric. The score for `average_rewards_at_k` tells you how well the solution version performs in achieving your objective. To calculate this metric, Amazon Personalize calculates the rewards for each user as follows:

`rewards_per_user = total rewards from the user's interactions with their top 25 reward generating recommendations / total rewards from the user's interactions with recommendations`

The final `average_rewards_at_k` is the average of all `rewards_per_user` normalized to be a decimal value less than or equal to 1 and greater than 0. The closer the value is to 1, the more gains on average per user you can expect from recommendations.

For example, if your objective is to maximize revenue from clicks, Amazon Personalize calculates each user score by dividing total revenue generated by the items the user clicked from their top 25 most expensive recommendations by the revenue from all of the recommended items the user clicked. Amazon Personalize then returns a normalized average of all user scores. The closer the `average_rewards_at_k` is to 1, the more revenue on average you can expect to gain per user from recommendations.

For more information about generating metrics, see [Evaluating an Amazon Personalize solution version with metrics](working-with-training-metrics.md).

## Optimizing a solution (AWS CLI)


 You can optimize for an objective only with the User-Personalization or Personalized-Ranking recipe. To optimize a solution for an additional objective using the AWS CLI, create a new solution and specify your objective details using the `optimizationObjective` key in the `solutionConfig` object. The `optimizationObjective` has the following fields: 
+ `itemAttribute`: Specify the name of the numerical metadata column from the Items dataset that relates to your objective.
+ `objectiveSensitivity`: Specify the level of emphasis that the solution places on your objective when generating recommendations. The objective sensitivity level configures how Amazon Personalize balances recommending items based on your objective versus relevance through item interaction datas data. The `objectiveSensitivity` can be `OFF`, LOW, `MEDIUM` or `HIGH`. For more information, see [Balancing objective emphasis and relevance](#balancing-objective-emphasis). 

The following is an example of the `create-solution` AWS CLI command. Replace the `solution name`, `dataset group arn`, and `recipe arn` values with your own. 

For `optimizationObjective`, replace `COLUMN_NAME` with the numerical metadata column name from the Items dataset that is related to your objective. For `objectiveSensitivity`, specify OFF, LOW, MEDIUM, or HIGH.

```
aws personalize create-solution \
--name solution name \
--dataset-group-arn dataset group arn \
--recipe-arn recipe arn \
--solution-config "{\"optimizationObjective\":{\"itemAttribute\":\"COLUMN_NAME\",\"objectiveSensitivity\":\"MEDIUM\"}}"
```

When your solution is ready, create a new solution version (for an example command see [Creating a solution (AWS CLI)](create-solution.md#configure-solution-cli)). Once you create a solution version, you can view the optimization performance with the solution version metrics. See [Measuring optimization performance](#measuring-performance).

## Optimizing a solution (AWS SDKs)


You can optimize for an objective only with the User-Personalization or Personalized-Ranking recipe. 

To optimize a solution for an additional objective using the AWS SDKs, create a new solution and specify your objective details using the `optimizationObjective` key in the `solutionConfig` object for the solution. The `optimizationObjective` has the following fields: 
+ `itemAttribute`: Specify the name of the numerical metadata column from the dataset group's Items dataset that relates to your objective.
+ `objectiveSensitivity`: Specify the level of emphasis that the solution places on your objective when generating recommendations. The objective sensitivity level configures how Amazon Personalize balances recommending items based on your objective versus relevance through item interaction datas data. The `objectiveSensitivity` can be `OFF`, `LOW`, `MEDIUM` or `HIGH`. For more information, see [Balancing objective emphasis and relevance](#balancing-objective-emphasis).

Use the following code to create a solution with an additional objective with the AWS SDK for Python (Boto3) or the AWS SDK for Java 2.x.

When your solution is ready, create a new solution version (for example code see [Creating a solution version (AWS SDKs)](creating-a-solution-version.md#create-solution-version-sdk)). Once you create a solution version, you can view the optimization performance with the solution version metrics. See [Measuring optimization performance](#measuring-performance).

------
#### [ SDK for Python (Boto3) ]

 To create a solution that is optimized for an additional objective, use the following `create_solution` method. Replace the `solution name`, `dataset group arn`, and `recipe arn` values with your own. 

For `optimizationObjective`, replace `COLUMN_NAME` with the numerical metadata column name from the Items dataset that is related to your objective. For `objectiveSensitivity`, specify OFF, LOW, MEDIUM, or HIGH.

```
import boto3

personalize = boto3.client('personalize')

create_solution_response = personalize.create_solution(
    name= 'solution name', 
    recipeArn = 'recipe arn', 
    datasetGroupArn = 'dataset group arn',
    solutionConfig = {
        "optimizationObjective": {
            "itemAttribute": "COLUMN_NAME",
            "objectiveSensitivity": "MEDIUM"
        }
    }
)
solution_arn = create_solution_response['solutionArn']
print('solution_arn: ', solution_arn)
```

------
#### [ SDK for Java 2.x ]

To create a solution that is optimized for an additional objective, use the following `createPersonalizeSolution` method and pass the following as parameters: an Amazon Personalize service client, the dataset group's Amazon Resource Name (ARN), a solution name, the recipe ARN, the item attribute, and the objective sensitivity level.

```
public static String createPersonalizeSolution(PersonalizeClient personalizeClient, 
                                             String datasetGroupArn, 
                                             String solutionName, 
                                             String recipeArn,
                                             String itemAttribute, 
                                             String objectiveSensitivity) {
    
    try {
        OptimizationObjective optimizationObjective = OptimizationObjective.builder()
            .itemAttribute(itemAttribute)
            .objectiveSensitivity(objectiveSensitivity)
            .build();
    
        SolutionConfig solutionConfig = SolutionConfig.builder()
            .optimizationObjective(optimizationObjective)
            .build();

        CreateSolutionRequest solutionRequest = CreateSolutionRequest.builder()
            .name(solutionName)
            .datasetGroupArn(datasetGroupArn)
            .recipeArn(recipeArn)
            .solutionConfig(solutionConfig)
            .build();

        CreateSolutionResponse solutionResponse = personalizeClient.createSolution(solutionRequest);
        
        return solutionResponse.solutionArn();

    } catch (PersonalizeException e) {
        System.err.println(e.awsErrorDetails().errorMessage());
        System.exit(1);
    }
    return "";
```

------
#### [ SDK for JavaScript v3 ]

```
// Get service clients and commands using ES6 syntax.
import { CreateSolutionCommand, PersonalizeClient } from
  "@aws-sdk/client-personalize";
  
// create the personalizeClient
const personalizeClient = new PersonalizeClient({ region: "REGION"});

// set the solution parameters.
export const createSolutionParam = {
  datasetGroupArn: 'DATASET_GROUP_ARN',              /* required */
  recipeArn: 'RECIPE_ARN',                           /* required */
  name: 'NAME',                                      /* required */
  solutionConfig: {
    optimizationObjective: {
      itemAttribute: "COLUMN_NAME",           /* specify the numerical column from the Items dataset related to your objective */
      objectiveSensitivity: "MEDIUM"          /* specify OFF, LOW, MEDIUM, or HIGH */
    }
  }
};

export const run = async () => {
  try {
    const response = await personalizeClient.send(new CreateSolutionCommand(createSolutionParam));
    console.log("Success", response);
    return response; // For unit tests.
  } catch (err) {
    console.log("Error", err);
  }
};
run();
```

------

## Sample Jupyter notebook
Sample notebook

For a sample Jupyter notebook that shows how to create a solution that is optimized for an additional objective based item metadata, see the [objective\$1optimization](https://github.com/aws-samples/amazon-personalize-samples/tree/master/next_steps/core_use_cases/objective_optimization) folder of the [Amazon Personalize samples](https://github.com/aws-samples/amazon-personalize-samples) GitHub repository

# Optimizing a solution with events configuration
Optimizing a solution with events configuration

**Important**  
By default, all new solutions use automatic training. With automatic training, you incur training costs while your solution is active. To avoid unnecessary costs, when you are finished you can [update the solution](updating-solution.md) to turn off automatic training. For information about training costs, see [Amazon Personalize pricing](https://aws.amazon.com/personalize/pricing/).

 If you use the User-Personalization-v2 recipe or Personalized-Ranking-v2 recipe, you can optimize an Amazon Personalize solution with an events configuration. 

 With item recommendation recipes, the primary objective of Amazon Personalize to predict the most relevant items for your users based on historical and real-time item interactions data. However, the interaction may carry additional information like whether a user clicked or purchase a certain item. You can record this by recording the event's type ([Event type and event value data](interactions-datasets.md#event-type-and-event-value-data)). When you configure a solution, you can have the solution give different weights to different interaction event types. For example, you can configure a solution to give more weight to `purchase` events than `click` events.

To have a solution give different weights to different event types, you specify the event types and their corresponding weights in the solution's event configuration. Additionally, you can set an event value threshold to exclude interactions with event value below that threshold. For example, if your EVENT\$1VALUE data for events with an EVENT\$1TYPE of watch is the percentage of a video that a user watched, if you set the event value threshold to 0.5, and the event type to watch, Amazon Personalize trains the model using only watch interaction events with an EVENT\$1VALUE greater than or equal to 0.5. 

 The weights associated with event types will determine their importance. An event type with higher weight will cause the trained model to more likely recommend an item that would be interacted with that event type. For example, if you specified “purchase” with a higher weight than “click” and the model learned that a user would either click item B or purchase item C with his or her interaction history, the model will rank item C higher. 

To optimize a solution with events config, you create a new solution with the User-Personalization-v2 recipe or Personalized-Ranking-v2 recipe and specify an events configuration. You can also update an existing solution ([Updating a solution to change its automatic training configuration](updating-solution.md)) with an events configuration. 

You can use the Amazon Personalize console, AWS Command Line Interface (AWS CLI), or AWS SDKs. For information about using the Amazon Personalize console, see [Creating a solution (console)](create-solution.md#configure-solution-console). 

**Topics**
+ [

## Guidelines and requirements
](#optimize-event-config-guidelines-req)
+ [

## Measuring performance with event weight configuration
](#optimize-event-configuration-measuring-performance)
+ [

## Optimizing a solution (AWS CLI)
](#optimize-event-configuration-cli)
+ [

## Optimizing a solution (AWS SDKs)
](#optimize-event-configuration-sdk)

## Guidelines and requirements


 The following are guidelines and requirements for events configuration: 
+ To configure weights for different event types, your Item interactions dataset dataset must have an EVENT\$1TYPE column and optionally an EVENT\$1VALUE column.
+ You can specify a list of event parameters in the configuration. Include all event types you want to be considered for solution creation. You can specify maximum of 10 different event types.
+ You can specify event weight for each event type. Event weight must be between 0.0 and 1.0. Only the ratio of weights between event types matter. For example, setting an event type “purchase” with weight 0.3 and an event type “click” with weight 0.1 will have the same effect as setting “purchase with weight 0.6 and ”click“ with weight 0.2.
+ You can update the event configuration for an existing solution using the [UpdateSolution](https://docs.aws.amazon.com/personalize/latest/dg/API_UpdateSolution.html) API operation.

## Measuring performance with event weight configuration


 When you create a solution version (train a model) for a solution with an events configuration, Amazon Personalize generates an `normalized_discounted_cumulative_gain_with_event_weights_at_k` metric. The score for `normalized_discounted_cumulative_gain_with_event_weights_at_k` tells you how well the solution version performs considering the events weight you set for each event types. 

 It is similar to normalized discounted cumulative gain (NDCG) at K but the reward for each correct prediction will be weighted. In contrast, in the original NDCG at K, each correct prediction will all carry a weight of 1. For example, with “purchase” of weight 0.3 and “click” of weight 0.1, correctly predicting “purchase” item will get a reward of 1.5 while predicting “click” item will get a reward of 0.5. 

For more information about generating metrics, see [Evaluating an Amazon Personalize solution version with metrics](working-with-training-metrics.md).

## Optimizing a solution (AWS CLI)


You can optimize with events configuration with the User-Personalization-v2 or Personalized-Ranking-v2 recipe.

 To optimize a solution with events configuration using the AWS CLI, create a new solution and specify your events configuration details using the `eventsConfig` key in the `solutionConfig` object. The `eventsConfig` has a key of `eventParametersList` under which you can specify up to 10 eventParameters. Each `eventParameter` has the following fields:
+ eventType: specify the event type you want to be considered for solution creation.
+ eventValueThreshold: specify the event value threshold. Only events with event value greater or equal to this threshold will be considered for solution creation.
+ weight: specify the weight for each event type. A higher weight means higher importance of the event type for the created solution.

The following is an example of the create-solution AWS CLI command. Replace the `solution name`, `dataset group arn`, and `recipe arn` values with your own. 

```
aws personalize create-solution \
--name solution name \
--dataset-group-arn dataset group arn \
--recipe-arn recipe arn \
--solution-config "{\"eventsConfig\":{\"eventParametersList\":[{\"eventType\":\"Purchase\", \"eventValueThreshold\":0.1, \"weight\":0.3}, {\"eventType\":\"Click\", \"weight\":0.1}]}"
```

When your solution is ready, create a new solution version (for an example command see [Creating a solution (AWS CLI)](create-solution.md#configure-solution-cli)). Once you create a solution version, you can view the optimization performance with the solution version metrics. See [Measuring optimization performance](optimizing-solution-for-objective.md#measuring-performance).

## Optimizing a solution (AWS SDKs)


You can optimize with events configuration with the User-Personalization-v2 or Personalized-Ranking-v2 recipe.

 To optimize a solution with events configuration using the AWS SDKs, create a new solution and specify your events configuration details using the `eventsConfig` key in the `solutionConfig` object. The `eventsConfig` has a key of `eventParametersList` under which you can specify up to 10 `eventParameters`. Each `eventParameter` has the following fields:
+ eventType: specify the event type you want to be considered for solution creation.
+ eventValueThreshold: specify the event value threshold. Only events with event value greater or equal to this threshold will be considered for solution creation.
+ weight: specify the weight for each event type. A higher weight means higher importance of the event type for the created solution.

------
#### [ SDK for Python (Boto3) ]

```
import boto3

personalize = boto3.client('personalize')

create_solution_response = personalize.create_solution(
    name= 'solution name', 
    recipeArn = 'recipe arn', 
    datasetGroupArn = 'dataset group arn',
    solutionConfig = {
       "eventsConfig": {
          "eventParametersList": [
             {"eventType":"Purchase", 
              "eventValueThreshold":0.1, 
              "weight":0.3}, 
             {"eventType":"Click", 
              "weight":0.1}
          ]
       }
    }
)
solution_arn = create_solution_response['solutionArn']
print('solution_arn: ', solution_arn)
```

------
#### [ SDK for Java 2.x ]

```
public static String createPersonalizeSolution(PersonalizeClient personalizeClient, 
							  String datasetGroupArn, 
							  String solutionName, 
							  String recipeArn,
							  ) {
    
try {
    EventsConfig eventsConfig = EventsConfig.builder()
        .eventsParameterList(eventsParameterList)
        .build();

    SolutionConfig solutionConfig = SolutionConfig.builder()
        .eventsConfig(eventsConfig)
        .build();

    CreateSolutionRequest solutionRequest = CreateSolutionRequest.builder()
        .name(solutionName)
        .datasetGroupArn(datasetGroupArn)
        .recipeArn(recipeArn)
        .solutionConfig(solutionConfig)
        .build();

    CreateSolutionResponse solutionResponse = personalizeClient.createSolution(solutionRequest);
    
    return solutionResponse.solutionArn();

} catch (PersonalizeException e) {
    System.err.println(e.awsErrorDetails().errorMessage());
    System.exit(1);
}
return "";
```

------

When your solution is ready, create a new solution version (for an example command see [Creating a solution (AWS SDKs)](create-solution.md#configure-solution-sdk)). Once you create a solution version, you can view the optimization performance with the solution version metrics. See [Measuring optimization performance](optimizing-solution-for-objective.md#measuring-performance).

# Hyperparameters and HPO


**Important**  
By default, all new solutions use automatic training. With automatic training, you incur training costs while your solution is active. To avoid unnecessary costs, when you are finished you can [update the solution](updating-solution.md) to turn off automatic training. For information about training costs, see [Amazon Personalize pricing](https://aws.amazon.com/personalize/pricing/).

You specify hyperparameters before training to optimize the trained model for your particular use case. This contrasts with model parameters whose values are determined during the training process.

Hyperparameters are specified using the `algorithmHyperParameters` key that is part of the [SolutionConfig](API_SolutionConfig.md) object that is passed to the [CreateSolution](API_CreateSolution.md) operation.

A condensed version of the `CreateSolution` request is below. The example includes the `solutionConfig` object. You use `solutionConfig` to override the default parameters of a recipe. 

```
{
  "name": "string",
  "recipeArn": "string",
  "eventType": "string",
  "solutionConfig": {
      "optimizationObjective": {
          "itemAttribute": "string",
          "objectiveSensitivity": "string"
      },
      "eventValueThreshold": "string",
      "featureTransformationParameters": {
          "string" : "string"
      },
      "algorithmHyperParameters": {
          "string" : "string"
      },
      "hpoConfig": {
          "algorithmHyperParameterRanges": {
              ...
          },
          "hpoResourceConfig": {
              "maxNumberOfTrainingJobs": "string",
              "maxParallelTrainingJobs": "string"
          }
      },
  },
}
```

Different recipes use different hyperparameters. For the available hyperparameters, see the individual recipes in [Choosing a recipe](working-with-predefined-recipes.md).

## Enabling hyperparameter optimization


Hyperparameter optimization (HPO), or tuning, is the task of choosing optimal hyperparameters for a specific learning objective. The optimal hyperparameters are determined by running many training jobs using different values from the specified ranges of possibilities. 

With [User-Personalization-v2](native-recipe-user-personalization-v2.md) and [Personalized-Ranking-v2](native-recipe-personalized-ranking-v2.md), if you turn on automatic training, Amazon Personalize automatically performs HPO every 90 days. Without automatic training, no HPO occurs. For all other recipes, you must enable HPO. To use HPO, set `performHPO` to `true`, and include the `hpoConfig` object.

Hyperparameters can be categorical, continuous, or integer-valued. The `hpoConfig` object has keys that correspond to each of these types, where you specify the hyperparameters and their ranges. You must provide each type in your request, but if a recipe doesn't have a parameter of a type, you can leave it empty. For example, User-Personalization does not have a tunable hyperparameter of continuous type. So for the `continousHyperParameterRange`, you would pass an empty array. 

The following code shows how to create a solution with HPO enabled using the SDK for Python (Boto3). The solution in the example uses the [User-Personalization recipe](native-recipe-new-item-USER_PERSONALIZATION.md) recipe and has HPO set to `true`. The code provides a value for `hidden_dimension` and the `categoricalHyperParameterRanges` and `integerHyperParameterRanges`. The `continousHyperParameterRange` is empty and the `hpoResourceConfig` sets the `maxNumberOfTrainingJobs` and `maxParallelTrainingJobs`. 

```
import boto3

personalize = boto3.client('personalize')

create_solution_response = personalize.create_solution(
    name = "solution name",
    datasetGroupArn = 'arn:aws:personalize:region:accountId:dataset-group/datasetGroupName',
    recipeArn = 'arn:aws:personalize:::recipe/aws-user-personalization',
    performHPO = True,
    solutionConfig = {
        "algorithmHyperParameters": {
          "hidden_dimension": "55"
        },
        "hpoConfig": {
          "algorithmHyperParameterRanges": {
              "categoricalHyperParameterRanges": [
                  {
                      "name": "recency_mask",
                      "values": [ "true", "false"]
                  }
              ],
              "integerHyperParameterRanges": [
                  {
                      "name": "bptt",
                      "minValue": 2,
                      "maxValue": 22
                  }
              ],
              "continuousHyperParameterRanges": [

              ]
          },
          "hpoResourceConfig": {
              "maxNumberOfTrainingJobs": "4",
              "maxParallelTrainingJobs": "2"
          }
        }
    }
)
```

For more information about HPO, see [Automatic model tuning](https://docs.aws.amazon.com/sagemaker/latest/dg/automatic-model-tuning.html). 

## Viewing hyperparameters


You can view the hyperparameters of the solution by calling the [DescribeSolution](API_DescribeSolution.md) operation. The following sample shows a `DescribeSolution` output. After creating a solution version (training a model), you can also view hyperparameters with the [DescribeSolutionVersion](API_DescribeSolutionVersion.md) operation.

```
{
  "solution": {
    "name": "hpo_coonfig_solution",
    "solutionArn": "arn:aws:personalize:region:accountId:solution/solutionName",
    "performHPO": true,
    "performAutoML": false,
    "recipeArn": "arn:aws:personalize:::recipe/aws-user-personalization",
    "datasetGroupArn": "arn:aws:personalize:region:accountId:dataset-group/datasetGroupName",
    "eventType": "click",
    "solutionConfig": {
      "hpoConfig": {
        "hpoResourceConfig": {
          "maxNumberOfTrainingJobs": "4",
          "maxParallelTrainingJobs": "2"
        },
        "algorithmHyperParameterRanges": {
          "integerHyperParameterRanges": [
            {
              "name": "training.bptt",
              "minValue": 2,
              "maxValue": 22
            }
          ],
          "continuousHyperParameterRanges": [],
          "categoricalHyperParameterRanges": [
            {
              "name": "data.recency_mask",
              "values": [
                "true",
                "false"
              ]
            }
          ]
        }
      },
      "algorithmHyperParameters": {
        "hidden_dimension": "55"
      }
    },
    "status": "ACTIVE",
    "creationDateTime": "2022-07-08T12:12:48.565000-07:00",
    "lastUpdatedDateTime": "2022-07-08T12:12:48.565000-07:00"
  }
}
```

# Choosing the item interaction data used for training


**Important**  
By default, all new solutions use automatic training. With automatic training, you incur training costs while your solution is active. To avoid unnecessary costs, when you are finished you can [update the solution](updating-solution.md) to turn off automatic training. For information about training costs, see [Amazon Personalize pricing](https://aws.amazon.com/personalize/pricing/).

You can choose the events in an Item interactions dataset that Amazon Personalize uses when creating a solution version (training a model). Choosing item interaction data before training allows you to use only a relevant subset of your data for training or remove noise to train a more optimized model. For more information about Item interactions datasets, see [Item interaction data](interactions-datasets.md).

**Note**  
If you use User-Personalization-v2 or Personalized-Ranking-v2, your training cost is based on your item interactions data before filtering by event type or value. For more information about pricing, see [Amazon Personalize pricing](https://aws.amazon.com/personalize/pricing/). 

You can choose item interaction data as follows:
+ **Choose records based on type** – When you configure a solution, if your Item interactions dataset includes event types in an EVENT\$1TYPE column, you can optionally specify an event type to use in training. For example, if your Item interactions dataset includes *purchase*, *click*, and *watch* event types, and you want Amazon Personalize to train the model with only *watch* events, when you configure your solution, you would provide *watch* as the `event type` that Amazon Personalize uses in training. 

  If you have multiple event types and use the User-Personalization-v2 recipe or Personalized-Ranking-v2 recipe, when you configure a custom solution you can specify different weights for different types. For example, you can configure a solution to give more weight to purchase events than click events. For more information, see [Optimizing a solution with events configuration](optimizing-solution-events-config.md).

   If your Item interactions dataset has multiple event types in an EVENT\$1TYPE column, and you do not provide an event type when you configure your solution, Amazon Personalize uses all item interaction data for training with equal weight regardless of type. 
+ **Choose records based on type and value ** – When you configure a solution, if your Item interactions dataset includes EVENT\$1TYPE and EVENT\$1VALUE fields, you can set a specific value as a threshold to exclude records from training. For example, if your EVENT\$1VALUE data for events with an EVENT\$1TYPE of *watch* is the percentage of a video that a user watched, if you set the event value threshold to 0.5, and the event type to *watch*, Amazon Personalize trains the model using only *watch* interaction events with an EVENT\$1VALUE greater than or equal to 0.5. 

The following code shows how to use the SDK for Python (Boto3) to create a solution that uses only `watch` events where the use watched more than half of the video.

```
import boto3

personalize = boto3.client('personalize')

create_solution_response = personalize.create_solution(
    name = 'solution name',
    datasetGroupArn = 'arn:aws:personalize:region:accountId:dataset-group/datasetGroupName',
    recipeArn = 'arn:aws:personalize:::recipe/aws-user-personalization-v2',
    eventType = 'watch',
    solutionConfig = {
        "eventValueThreshold": "0.5"
    }
)

# Store the solution ARN
solution_arn = create_solution_response['solutionArn']

# Use the solution ARN to get the solution status
solution_description = personalize.describe_solution(solutionArn = solution_arn)['solution']
print('Solution status: ' + solution_description['status'])
```

# Cloning a solution (console)


 When you create a new solution, you can use the Amazon Personalize console to clone a solution. When you clone a solution, you can use the configuration of the existing solution as a starting point, such as the recipe and hyperparameters, and make any changes as necessary. This is useful if you want to make one change to a solution, but leave all other properties unchanged. For example, adding a new column of training data to your dataset. In this case, you would clone a solution, give the solution a name, change the columns used when training, and leave all other properties unchanged. 

## Cloning a solution


To clone a solution, you choose the existing solution, and choose the **Clone solution** option. Then give the new solution a name, and modify the relevant fields. 

**To clone a solution**

1. Open the Amazon Personalize console at [https://console.aws.amazon.com/personalize/home](https://console.aws.amazon.com/personalize/home) and sign in to your account.

1.  On the **Dataset groups** page, choose your dataset group. 

1.  Choose **Custom resources** and choose **Solutions**. 

1.  Choose the solution that you want to clone. 

1. Choose **Actions**, and choose **Clone solution**.

1. Give the new solution a name.

1. Make any changes to the solution details and advanced configuration. Amazon Personalize pre-populates these fields with values from the existing solution. For information about each field, see [Configuring a custom solution in Amazon Personalize](customizing-solution-config.md).

# Updating a solution to change its automatic training configuration
Updating a solution

After you create a solution, you can change its automatic training configuration and its events configuration:
+ You can turn automatic training on or off, and you can change the training frequency. 
  + If you turn on automatic training, the first automatic training starts within one hour after the solution update completes. If you manually create a solution version within the hour, the solution skips the first automatic training. 
  + If you modify the solution’s training frequency, the training schedule resets and a new solution version starts training within the hour. Solution version creation continues at the new frequency, where day 1 is the day you update the solution.
+ You can update the solutions events configuration. If the solution already has an events configuration specified, the new events config will replace the original one. For information about optimizing a solution for an event configuration, see [Optimizing a solution with events configuration](optimizing-solution-events-config.md).

You can update a solution with the Amazon Personalize console, AWS Command Line Interface, or AWS SDKs. Solution updates can take a few minutes. While the update is in progress, you can create solution versions for the solution but you can't delete the solution. Until the update completes, the solution uses the previous configuration. For more information about automatic training, see [Configuring automatic training](solution-config-auto-training.md). 

**Topics**
+ [

## Updating a solution (console)
](#update-solution-console)
+ [

## Updating a solution (AWS CLI)
](#update-solution-cli)
+ [

## Updating a solution (AWS SDKs)
](#update-solution-sdk)

## Updating a solution (console)


 To update a solution in the console, navigate to the solution, choose update, and specify the new configuration to use.

**To configure a solution**

1. Open the Amazon Personalize console at [https://console.aws.amazon.com/personalize/home](https://console.aws.amazon.com/personalize/home), and sign in to your account.

1. On the **Dataset groups** page, choose your dataset group.

1. In the navigation pane, choose **Custom resources** and choose **Solutions and recipes**.

1. Choose your solution and choose **Update** in the top right.

1. In **Automatic training**, modify whether the solution uses automatic training. If automatic training is on, you can change the `Automatic training frequency`. The default training frequency is every 7 days.

1. Choose **Update solution**. You can find the status of the solution update on the details page of your solution.

## Updating a solution (AWS CLI)


To update a solution with the AWS Command Line Interface, use the `update-solution` command. This command uses the [UpdateSolution](API_UpdateSolution.md) API operation. The following code shows you how to update a solution to use automatic training with a training frequency of 5 days. To turn off auto training, specify `--no-perform-auto-training` and omit the `solution-update-config`.

The default training frequency is every 7 days. The expression must be in `rate(value unit)` format. For the value, specify a number between 1 and 30. For the unit, specify `day` or `days`.

```
aws personalize update-solution \
--solution-arn solution ARN \
--perform-auto-training \
--solution-update-config "{\"autoTrainingConfig\": {\"schedulingExpression\": \"rate(5 days)\"}}"
```

To get the status of the update, use the `describe-solution` command (which uses the [DescribeSolution](API_DescribeSolution.md) API operation) and find the update status in the `latestSolutionUpdate`. 

## Updating a solution (AWS SDKs)


To update a solution with the AWS SDKs, use the [UpdateSolution](API_UpdateSolution.md) API operation. The following code shows you how to use the SDK for Python (Boto3) to update a solution to use automatic training with a training frequency of 5 days. The code gets the status of the update with the [DescribeSolution](API_DescribeSolution.md) API operation. 

The default training frequency is every 7 days. The expression must be in `rate(value unit)` format. For the value, specify a number between 1 and 30. For the unit, specify `day` or `days`.

```
import boto3

personalize = boto3.client('personalize')

update_solution_response = personalize.update_solution(
    solutionArn='SOLUTION ARN',
    performAutoTraining=True,
    solutionUpdateConfig={
        "autoTrainingConfig": {
            "schedulingExpression": "rate(5 days)"
        }
    }
)
describe_solution_response = personalize.describe_solution(
    solutionArn='SOLUTION ARN'
)
update_status = describe_solution_response["solution"]["latestSolutionUpdate"]["status"]
print(f"Update status: {update_status}")
```

# Manually creating a solution version


After you complete [Configuring a custom solution in Amazon Personalize](customizing-solution-config.md), you are ready to start training:
+  If your solution uses automatic training, the solution creates solution versions for you at the training frequency you specify. By default, all new solutions use automatic training to create a new solution version every 7 days. You can still manually create solution versions. For more information, see [Configuring automatic training](solution-config-auto-training.md).
+ If you turn off auto training for your solution or you want to manually train, you can manually create a solution version. A *solution version* refers to a trained machine learning model. You can create a solution version using the console, AWS Command Line Interface (AWS CLI), or AWS SDKs. If your solution version has a status of CREATE\$1PENDING or CREATE\$1IN\$1PROGRESS, you can use the [StopSolutionVersionCreation](API_StopSolutionVersionCreation.md) operation to stop the solution version creation process. See [Stopping the creation of a solution version](stop-solution-version.md). 

If training does not complete because of an error, you are not charged for the training. If your solution version has a status of CREATE\$1PENDING or CREATE\$1IN\$1PROGRESS, you can stop the solution version creation process. To stop solution version creation, navigate to the solution version details page and choose **Stop**. For more information, see [Stopping the creation of a solution version](stop-solution-version.md).

**Topics**
+ [

## Creating a solution version (console)
](#create-solution-version-console)
+ [

## Creating a solution version (AWS CLI)
](#create-solution-version-cli)
+ [

## Creating a solution version (AWS SDKs)
](#create-solution-version-sdk)

## Creating a solution version (console)


To manually create a new solution version with the Amazon Personalize console, you start training from the details page of your solution.

**To create a new solution version**

1. Open the Amazon Personalize console at [https://console.aws.amazon.com/personalize/home](https://console.aws.amazon.com/personalize/home) and sign into your account.

1. Navigate to the dataset groups page and choose the dataset group with your new solution.

1. In the navigation pane, under **Custom resources**, choose **Solutions and recipes**. 

1. On the **Solution and recipes** page, choose the solution you want to create a solution version for.

1. On the solution overview page, choose **Create solution version** to start training a new model.

On the solution details page, you can track training progress in the **Solution versions** section. When training is complete, the status is **Active** you can evaluate it using metrics supplied by Amazon Personalize. For more information, see [Evaluating an Amazon Personalize solution version with metrics](working-with-training-metrics.md).

 When the solution version is ACTIVE, you are ready to use it to get recommendations. How you use an active solution version depends on how you get recommendations:
+  For real-time recommendations, you deploy an ACTIVE solution version with an Amazon Personalize campaign. You use the campaign to get recommendations for your users. See [Deploying an Amazon Personalize solution version with a campaignCreating a campaign](campaigns.md).
+ For batch recommendations, you specify an ACTIVE solution version when you create a batch inference job or batch segment job. See [Getting batch item recommendations](getting-batch-recommendations.md) or [Getting batch user segments](getting-user-segments.md).

## Creating a solution version (AWS CLI)


When your solution is ACTIVE, train the model by running the following command. Replace `solution arn` with the solution Amazon Resource Name (ARN) from [Configuring a custom solution in Amazon Personalize](customizing-solution-config.md).

```
aws personalize create-solution-version \
  --solution-arn solution arn
```

The solution version ARN is displayed, for example:

```
{
  "solutionVersionArn": "arn:aws:personalize:us-west-2:acct-id:solution/SolutionName/<version-id>"
}
```

Check the training status of the solution version by using the `describe-solution-version` command. Provide the solution version ARN that was returned in the previous step. For more information about the API, see [DescribeSolutionVersion](API_DescribeSolutionVersion.md).

```
aws personalize describe-solution-version \
  --solution-version-arn solution version arn
```

The properties of the solution version and the training `status` are displayed. Initially, the status shows as CREATE PENDING, for example:

```
{
  "solutionVersion": {
      "solutionVersionArn": "arn:aws:personalize:us-west-2:acct-id:solution/solutionName/<version-id>",
      ...,
      "status": "CREATE PENDING"
  }
}
```

Training is complete when the `status` is `ACTIVE` and you can evaluate it using metrics supplied by Amazon Personalize. For more information, see [Evaluating an Amazon Personalize solution version with metrics](working-with-training-metrics.md). If training does not complete because of an error, you are not charged for the training. 

If your solution version has a status of CREATE\$1PENDING or CREATE\$1IN\$1PROGRESS, you can use the [StopSolutionVersionCreation](API_StopSolutionVersionCreation.md) operation to stop the solution version creation process. See [Stopping the creation of a solution version](stop-solution-version.md).

 When the solution version is ACTIVE, you are ready to use it to get recommendations. How you use an active solution version depends on how you get recommendations:
+  For real-time recommendations, you deploy an ACTIVE solution version with an Amazon Personalize campaign. You use the campaign to get recommendations for your users. See [Deploying an Amazon Personalize solution version with a campaignCreating a campaign](campaigns.md).
+ For batch recommendations, you specify an ACTIVE solution version when you create a batch inference job or batch segment job. See [Getting batch item recommendations](getting-batch-recommendations.md) or [Getting batch user segments](getting-user-segments.md).

## Creating a solution version (AWS SDKs)


When your solution is ACTIVE, use the following code to create a solution version. Specify the Amazon Resource Name (ARN) from [Configuring a custom solution in Amazon Personalize](customizing-solution-config.md). Use the [DescribeSolutionVersion](API_DescribeSolutionVersion.md) operation to retrieve the solution version's status.

------
#### [ SDK for Python (Boto3) ]

```
import boto3

personalize = boto3.client('personalize')
# Store the solution ARN
solution_arn = 'solution arn'
        
# Use the solution ARN to get the solution status.
solution_description = personalize.describe_solution(solutionArn = 'solution_arn')['solution']
print('Solution status: ' + solution_description['status'])

# Use the solution ARN to create a solution version.
print ('Creating solution version')
response = personalize.create_solution_version(solutionArn = solution_arn)
solution_version_arn = response['solutionVersionArn']
print('Solution version ARN: ' + solution_version_arn)

# Use the solution version ARN to get the solution version status.
solution_version_description = personalize.describe_solution_version(
    solutionVersionArn = solution_version_arn)['solutionVersion']
print('Solution version status: ' + solution_version_description['status'])
```

------
#### [ SDK for Java 2.x ]

```
public static String createPersonalizeSolutionVersion(PersonalizeClient personalizeClient, String solutionArn) {
        long maxTime = 0;
        long waitInMilliseconds = 30 * 1000; // 30 seconds
        String solutionStatus = "";
        String solutionVersionStatus = "";
        String solutionVersionArn = "";

        try {
            DescribeSolutionRequest describeSolutionRequest = DescribeSolutionRequest.builder()
                .solutionArn(solutionArn)
                .build();
            
            maxTime = Instant.now().getEpochSecond() + 3 * 60 * 60;

            // Wait until solution is active. 
            while (Instant.now().getEpochSecond() < maxTime) {

                solutionStatus = personalizeClient.describeSolution(describeSolutionRequest).solution().status();
                System.out.println("Solution status: " + solutionStatus);

                if (solutionStatus.equals("ACTIVE") || solutionStatus.equals("CREATE FAILED")) {
                    break;
                }
                try {
                    Thread.sleep(waitInMilliseconds);
                } catch (InterruptedException e) {
                    System.out.println(e.getMessage());
                }
            }
            
            // Once the solution is active, start creating a solution version.
            
            if (solutionStatus.equals("ACTIVE")) {

                CreateSolutionVersionRequest createSolutionVersionRequest = CreateSolutionVersionRequest.builder()
                    .solutionArn(solutionArn)
                    .build();
                
                CreateSolutionVersionResponse createSolutionVersionResponse = personalizeClient.createSolutionVersion(createSolutionVersionRequest);
                solutionVersionArn = createSolutionVersionResponse.solutionVersionArn();

                System.out.println("Solution version ARN: " + solutionVersionArn);

                DescribeSolutionVersionRequest describeSolutionVersionRequest = DescribeSolutionVersionRequest.builder() 
                    .solutionVersionArn(solutionVersionArn)
                    .build();
                
                maxTime = Instant.now().getEpochSecond() + 3 * 60 * 60;
                
                while (Instant.now().getEpochSecond() < maxTime) {

                    // Use the solution version ARN to get the solution version status.
                    solutionVersionStatus = personalizeClient.describeSolutionVersion(describeSolutionVersionRequest).solutionVersion().status();
                    System.out.println("Solution version status: " + solutionVersionStatus);
    
                    if (solutionVersionStatus.equals("ACTIVE") || solutionVersionStatus.equals("CREATE FAILED")) {
                        break;
                    }
                    try {
                        Thread.sleep(waitInMilliseconds);
                    } catch (InterruptedException e) {
                        System.out.println(e.getMessage());
                    }
                }
                return solutionVersionArn;
            }
        } catch(PersonalizeException e) {
            System.err.println(e.awsErrorDetails().errorMessage());
            System.exit(1);
        }
        return "";
    }
```

------
#### [ SDK for JavaScript v3 ]

```
// Get service clients module and commands using ES6 syntax.
import { CreateSolutionVersionCommand } from "@aws-sdk/client-personalize";
import { personalizeClient } from "./libs/personalizeClients.js";
// Or, create the client here.
// const personalizeClient = new PersonalizeClient({ region: "REGION"});

// Set the solution version parameters.
export const solutionVersionParam = {
  solutionArn: "SOLUTION_ARN" /* required */,
};

export const run = async () => {
  try {
    const response = await personalizeClient.send(
      new CreateSolutionVersionCommand(solutionVersionParam),
    );
    console.log("Success", response);
    return response; // For unit tests.
  } catch (err) {
    console.log("Error", err);
  }
};
run();
```

------



To check the current solution version status, call the [DescribeSolutionVersion](API_DescribeSolutionVersion.md) operation and pass the ARN of the solution version returned from the `CreateSolutionVersion` operation. Training is complete when the `status` is `ACTIVE` and you can evaluate it using metrics supplied by Amazon Personalize. For more information, see [Evaluating an Amazon Personalize solution version with metrics](working-with-training-metrics.md). If training does not complete because of an error, you are not charged for the training. 

If your solution version has a status of CREATE\$1PENDING or CREATE\$1IN\$1PROGRESS, you can use the [StopSolutionVersionCreation](API_StopSolutionVersionCreation.md) operation to stop the solution version creation process. See [Stopping the creation of a solution version](stop-solution-version.md).

 When the solution version is ACTIVE, you are ready to use it to get recommendations. How you use an active solution version depends on how you get recommendations:
+  For real-time recommendations, you deploy an ACTIVE solution version with an Amazon Personalize campaign. You use the campaign to get recommendations for your users. See [Deploying an Amazon Personalize solution version with a campaignCreating a campaign](campaigns.md).
+ For batch recommendations, you specify an ACTIVE solution version when you create a batch inference job or batch segment job. See [Getting batch item recommendations](getting-batch-recommendations.md) or [Getting batch user segments](getting-user-segments.md).

# Stopping the creation of a solution version


If your solution version has a status of CREATE\$1PENDING or CREATE\$1IN\$1PROGRESS, you can use the Amazon Personalize console or the [StopSolutionVersionCreation](API_StopSolutionVersionCreation.md) operation to stop creating the solution version (stop training a model). You can't resume creating a solution version after it has stopped. You are billed for resources used up to the point when the creation of the solution version stopped. 

Stopping the creation of a solution version ends model training, but doesn't delete the solution version. You can still view the solution version details in the Amazon Personalize console and with the [DescribeSolutionVersion](API_DescribeSolutionVersion.md) operation. 

You can stop the solution version creation process with the Amazon Personalize console, the AWS Command Line Interface (AWS CLI), or the AWS SDKs.

**Topics**
+ [

## Stopping the creation of a solution version (console)
](#stop-solution-version-console)
+ [

## Stopping the creation of a solution version (AWS CLI)
](#stop-solution-version-cli)
+ [

## Stopping the creation of a solution version (AWS SDKs)
](#stop-solution-version-sdk)

## Stopping the creation of a solution version (console)


If your solution version has a status of CREATE\$1PENDING or CREATE\$1IN\$1PROGRESS, you can stop creating a solution version (stop training a model).

**To stop creating a solution version (console)**

1. Open the Amazon Personalize console at [https://console.aws.amazon.com/personalize/home](https://console.aws.amazon.com/personalize/home) and sign into your account.

1. On the **Dataset groups** page, choose the dataset group with the solution version that you want to stop.

1. In the navigation pane, choose **Solutions and recipes**. 

1. On the **Solution and recipes** page, choose the solution with the solution version that you want to stop.

1. In **Solution versions**, choose the solution version that you want to stop.

1. On the solution version details page, choose **Stop creation**. Depending on the original state of the solution version, the solution version state changes as follows:
   + CREATE\$1PENDING changes to CREATE\$1STOPPED.
   + CREATE\$1IN\$1PROGRESS changes to CREATE\$1STOPPING and then CREATE\$1STOPPED.

## Stopping the creation of a solution version (AWS CLI)


If your solution version has a status of CREATE\$1PENDING or CREATE\$1IN\$1PROGRESS, you can stop creating a solution version (stop training a model). Use the following `stop-solution-version-creation` command to stop creating the solution version with the AWS CLI. Replace `solution version arn` with the Amazon Resource Name (ARN) of the solution version that you want to stop. You are billed for resources used up to the point that creation of the solution version stopped. 

```
aws personalize stop-solution-version-creation \
    --solution-version-arn solution version arn
```

Check the training status of the solution version with the `describe-solution-version` command.

```
aws personalize describe-solution-version \
    --solution-version-arn solution version arn
```

Depending on the original state of the solution version, the solution version state changes as follows:
+ CREATE\$1PENDING changes to CREATE\$1STOPPED.

  
+ CREATE\$1IN\$1PROGRESS changes to CREATE\$1STOPPING and then CREATE\$1STOPPED

## Stopping the creation of a solution version (AWS SDKs)


If your solution version has a status of CREATE\$1PENDING or CREATE\$1IN\$1PROGRESS, you can stop creating a solution version (stop training a model). The following code shows how to stop creating a solution version with the AWS SDK for Python (Boto3) or AWS SDK for Java 2.x. You are billed for resources used up to the point when creation of the solution version stopped.

------
#### [ SDK for Python (Boto3) ]

Use the following `stop_solution_version_creation`method to stop creation of a solution version. Replace `solution_version_arn` with the Amazon Resource Name (ARN) of the solution version that you want to stop. The method uses the [DescribeSolutionVersion](API_DescribeSolutionVersion.md) operation to retrieve the solution version's status.

```
import boto3

personalize = boto3.client('personalize')

response = personalize.stop_solution_version_creation(
    solutionVersionArn = solution_version_arn
)

# Use the solution version ARN to get the solution version status.
solution_version_description = personalize.describe_solution_version(
    solutionVersionArn = solution_version_arn)['solutionVersion']
print('Solution version status: ' + solution_version_description['status'])
```

------
#### [ SDK for Java 2.x ]

Use the following `stopSolutionVersionCreation` method to stop creating a solution version. Pass as parameters an Amazon Personalize service client and the Amazon Resource Name (ARN) of the solution version that you want to stop creating. The following code uses the [DescribeSolutionVersion](API_DescribeSolutionVersion.md) operation to retrieve the solution version's status.

```
public static void stopSolutionVersionCreation(PersonalizeClient personalizeClient, String solutionVersionArn) {
    String solutionVersionStatus = "";
    
    StopSolutionVersionCreationRequest stopSolutionVersionCreationRequest = StopSolutionVersionCreationRequest.builder()
        .solutionVersionArn(solutionVersionArn)
        .build();
    
    personalizeClient.stopSolutionVersionCreation(stopSolutionVersionCreationRequest);
    
    // Use the solution version ARN to get the solution version status.
    DescribeSolutionVersionRequest describeSolutionVersionRequest = DescribeSolutionVersionRequest.builder() 
        .solutionVersionArn(solutionVersionArn)
        .build();
                    
    solutionVersionStatus = personalizeClient.describeSolutionVersion(describeSolutionVersionRequest)
        .solutionVersion()
        .status();
    System.out.println("Solution version status: " + solutionVersionStatus);
}
```

------

Depending on the original state of the solution version, the solution version state changes as follows:
+ CREATE\$1PENDING changes to CREATE\$1STOPPED.

  
+ CREATE\$1IN\$1PROGRESS changes to CREATE\$1STOPPING and then CREATE\$1STOPPED.

# Evaluating an Amazon Personalize solution version with metrics
Evaluating a solution version

 You can evaluate the performance of your solution version through offline and online metrics. *Online metrics* are the empirical results you observe in your users' interactions with real-time recommendations. For example, you might record your users' click-through rate as they browse your catalog. You are responsible for generating and recording any online metrics. 

 *Offline metrics* are the metrics Amazon Personalize generates when you train a solution version. With offline metrics, you can evaluate the performance of the model. You can view the effects of modifying a solution's hyperparameters, and you can compare results from models trained with different recipes on the *same data* in the same dataset group.

Avoid comparing metrics of different solution versions trained with different data. The difference in metrics might be from the difference in data rather than model performance. For example, you might have a dataset group with sparse `purchase` event data for each user, and another with robust `view` event data. Based on metrics like `precision at K`, the solution version trained on the view event data might incorrectly appear to perform better due to the higher number of interactions. 

 To get performance metrics, Amazon Personalize splits the input interactions data into a training set, a testing set, and for PERSONALIZED\$1ACTIONS, a validation set. The split depends on the type of recipe you choose:
+  For USER\$1SEGMENTATION recipes, the training set consists of 80% of each user's interactions data and the testing set consists of 20% of each user's interactions data. 
+  For all other recipe types, the training set consists of 90% of your users and their interactions data. The testing set consists of the remaining 10% of users and their interactions data. 

 Amazon Personalize then creates the solution version using the training set. After training completes, Amazon Personalize gives the new solution version the oldest 90% of each user’s data from the testing set as input. Amazon Personalize then calculates metrics by comparing the recommendations the solution version generates to the actual interactions in the newest 10% of each user’s data from the testing set. 

To generate a baseline for comparison purposes, we recommend using the [Popularity-Count](native-recipe-popularity.md) recipe, which recommends the top K most popular items.

**Topics**
+ [

## Retrieving solution version metrics
](#working-with-training-metrics-metrics)
+ [

## Metric definitions
](#metric-definitions)
+ [

## Example
](#working-with-training-metrics-example)
+ [

## Additional resources
](#additional-metrics-resources)

## Retrieving solution version metrics


After you create a solution version, you can use metrics to evaluate its performance. You can retrieve metrics for a solution version with the Amazon Personalize console, AWS Command Line Interface (AWS CLI), and AWS SDKs. 

**Topics**
+ [

### Retrieving solution version metrics (console)
](#retrieving-solution-version-metrics-console)
+ [

### Retrieving solution version metrics (AWS CLI)
](#retrieve-metrics-cli)
+ [

### Retrieving solution version metrics (AWS SDKs)
](#retrieve-metrics-sdks)

### Retrieving solution version metrics (console)


To view recommender metrics in the console, you navigate to the details page for your solution version.

1. Open the Amazon Personalize console at [https://console.aws.amazon.com/personalize/home](https://console.aws.amazon.com/personalize/home) and sign in to your account.

1. On the **Dataset groups** page, choose your Custom dataset group. 

1. From the navigation pane, choose **Custom resources** and then choose **Solutions and recipes**.

1. Choose your solution.

1. In **Solution versions**, choose your solution version to view its details page. The metrics are listed on the **Solution version metrics** tab in the bottom pane. For definitions of metrics, see [Metric definitions](#metric-definitions).

   Now that you have evaluated your solution version, you can create a campaign by deploying the solution version with the best metrics for your use case. For more information about deploying a solution, see [Deploying an Amazon Personalize solution version with a campaignCreating a campaign](campaigns.md).

### Retrieving solution version metrics (AWS CLI)


You retrieve the metrics for a specific solution version by calling the [GetSolutionMetrics](API_GetSolutionMetrics.md) operation. The following code shows how to retrieve metrics with the AWS CLI. 

```
personalize get-solution-metrics --solution-version-arn solution version ARN
```

The following is an example the output from a solution version created using the [User-Personalization](native-recipe-new-item-USER_PERSONALIZATION.md) recipe with an additional optimization objective.

```
{
    "solutionVersionArn": "arn:aws:personalize:us-west-2:acct-id:solution/SolutionName/<version-id>",
    "metrics": {
        "coverage": 0.27,
        "mean_reciprocal_rank_at_25": 0.0379,
        "normalized_discounted_cumulative_gain_at_5": 0.0405,
        "normalized_discounted_cumulative_gain_at_10": 0.0513,
        "normalized_discounted_cumulative_gain_at_25": 0.0828,
        "precision_at_5": 0.0136,
        "precision_at_10": 0.0102,
        "precision_at_25": 0.0091,
        "average_rewards_at_k": 0.653
    }
}
```

For explanations of each metric, see [Metric definitions](#metric-definitions). Now that you have evaluated your solution version, you can create a campaign by deploying the solution version with the best metrics for your use case. For more information about deploying a solution, see [Deploying an Amazon Personalize solution version with a campaignCreating a campaign](campaigns.md).

### Retrieving solution version metrics (AWS SDKs)


You retrieve the metrics for a specific solution version by calling the [GetSolutionMetrics](API_GetSolutionMetrics.md) operation. Use the following code to retrieve metrics. 

------
#### [ SDK for Python (Boto3) ]

```
import boto3

personalize = boto3.client('personalize')

response = personalize.get_solution_metrics(
    solutionVersionArn = 'solution version arn')

print(response['metrics'])
```

------
#### [ SDK for Java 2.x ]

```
public static void getSolutionVersionMetrics(PersonalizeClient personalizeClient, String solutionVersionArn) {

    try {
        GetSolutionMetricsRequest request = GetSolutionMetricsRequest.builder()
                .solutionVersionArn(solutionVersionArn)
                .build();
        Map<String, Double> metrics = personalizeClient.getSolutionMetrics(request).metrics();
        metrics.forEach((key, value) -> System.out.println(key + " " + value));
    } catch (PersonalizeException e ) {
        System.err.println(e.awsErrorDetails().errorMessage());
        System.exit(1);
    }
}
```

------

The following is an example the output from a solution version created using the [User-Personalization](native-recipe-new-item-USER_PERSONALIZATION.md) recipe with an additional optimization objective.

```
{
    "solutionVersionArn": "arn:aws:personalize:us-west-2:acct-id:solution/MovieSolution/<version-id>",
    "metrics": {
        "coverage": 0.27,
        "mean_reciprocal_rank_at_25": 0.0379,
        "normalized_discounted_cumulative_gain_at_5": 0.0405,
        "normalized_discounted_cumulative_gain_at_10": 0.0513,
        "normalized_discounted_cumulative_gain_at_25": 0.0828,
        "precision_at_5": 0.0136,
        "precision_at_10": 0.0102,
        "precision_at_25": 0.0091,
        "average_rewards_at_k": 0.653
    }
}
```

For explanations of each metric, see [Metric definitions](#metric-definitions). Now that you have evaluated your solution version, you can create a campaign by deploying the solution version with the best metrics for your use case. For more information about deploying a solution, see [Deploying an Amazon Personalize solution version with a campaignCreating a campaign](campaigns.md).

## Metric definitions


The metrics Amazon Personalize generates for solution versions are described below using the following terms:
+ *Relevant recommendation* is a recommendation for an item that the user actually interacted with. These items are from the newest 10% of each user’s interactions data from the testing set. 
+ *Rank* refers to the position of a recommended item in the list of recommendations. Position 1 (the top of the list) is presumed to be the most relevant to the user.

For each metric, higher numbers (closer to 1) are better. To dive deeper, see the resources listed in [Additional resources](#additional-metrics-resources). 

**coverage**  
The value for *coverage* tells you the proportion of unique items (for item recommendations), actions (for action recommendations), or users (for user segment recommendations), that Amazon Personalize might recommend out of the total number of unique records in your datasets.  
A higher coverage score means Amazon Personalize recommends more of your catalog, rather than the records same repeatedly. Recipes that feature item exploration, such as User-Personalization, have higher coverage than those that don’t, such as Similar-Items. 

**mean reciprocal rank at 25**  
This metric tells you about a model's ability to generate a relevant item recommendations at the top ranked position.   
 You might choose a model with a high *mean reciprocal rank at 25* if you are generating item search results for a user, and don't expect the user to choose an item lower on the list. For example, users frequently choose the first cooking recipe in search results. Amazon Personalize doesn't generate this metric for PERSONALIZED\$1ACTIONS or USER\$1SEGMENTATION recipes.  
 Amazon Personalize calculates this metric using the average reciprocal rank score for requests for recommendations. Each reciprocal rank score is calculated as follows: `1 / the rank of the highest item interacted with by the user`, where the total possible rankings is 25. Other lower ranked items the user interacts with are ignored. If the user chose the first item, the score is 1. If they don't choose any items, the score is 0.   
 For example, you might show three different users 25 recommendations each:   
+ If User 1 clicks the item at rank *4* and the item at rank *10*, their reciprocal rank score is *1/4*.
+ If User 2 clicks an item at rank *2*, an item at rank *4*, and an item at rank *12*, their reciprocal rank score is 1/2.
+ If User 3 clicks on a single item at rank *6*, their reciprocal rank score is 1/6.
 The mean reciprocal rank over all requests for recommendations (in this case 3) is calculated as `(1/4 + 1/2 + 1/6) / 3 = .3056`.   


**normalized discounted cumulative gain (NDCG) at K (5/10/25)**  
This metric tells you about how well your model ranks item or action recommendations, where K is a sample size of 5, 10, or 25 recommendations. This metric is useful if you are most interested in the ranking of recommendations beyond just the highest ranked item or action (for this, see `mean reciprocal rank at 25`). For example, the score for `NDCG at 10` would be useful if you have an application that shows up to 10 movies in a carousel at a time.   
Amazon Personalize calculates the NDCG by assigning weight to recommendations based on their ranking position for each user in the testing set. Each recommendation is discounted (given a lower weight) by a factor dependent on its position. The final metric is the average `NDCG at K` for all users in the testing set. The `NDCG at K` assumes that recommendations that are lower on a list are less relevant than recommendations higher on the list.  
Amazon Personalize uses a weighting factor of `1/log(1 + position)`, where the top of the list is position `1`.

**precision at K**  
This metric tells you how relevant your model’s recommendations are based on a sample size of K (5, 10, or 25) recommendations.   
 Amazon Personalize calculates this metric based on the number of relevant recommendations out of the top K recommendations for each user in the testing set, divided by K, where K is 5, 10, or 25. The final metric is the average across all users in the testing set.  
For example, if you recommend 10 items to a user, and the user interacts with 3 of them, the precision at K is 3 correctly predicted items divided by the total 10 recommended items: `3 / 10 = .30`.   
This metric rewards precise recommendation of relevant items. The closer the score is to one, the more precise the model. 

**precision**  
If you train a solution version with the Next-Best-Action recipe, Amazon Personalize generates a `precision` metric instead of `precision at K`. This metric tells you how good your model is at predicting actions users will actually take.  
 To calculate `precision`, for each action in your dataset, Amazon Personalize divides the number of users that were correctly predicted to take the action by the total number of times the action was recommended. Amazon Personalize then calculates the average for all actions in your dataset.   
For example, if an action was recommended to 100 users, and 60 users took the action and 40 users who didn't, the `precision` for the action is: `60 / 100 = .60`. Amazon Personalize then applies this calculation for all actions and returns the average.  
This metric rewards precise recommendation of relevant actions. The closer the score is to one, the more precise the model. 

**average\$1rewards\$1at\$1k**  
When you create a solution version (train a model) for a solution with an optimization objective, Amazon Personalize generates an `average_rewards_at_k` metric. The score for `average_rewards_at_k` tells you how well the solution version performs in achieving your objective. To calculate this metric, Amazon Personalize calculates the rewards for each user as follows:  
`rewards_per_user = total rewards from the user's interactions with their top 25 reward generating recommendations / total rewards from the user's interactions with recommendations`  
The final `average_rewards_at_k` is the average of all `rewards_per_user` normalized to be a decimal value less than or equal to 1 and greater than 0. The closer the value is to 1, the more gains on average per user you can expect from recommendations.  
For example, if your objective is to maximize revenue from clicks, Amazon Personalize calculates each user score by dividing total revenue generated by the items the user clicked from their top 25 most expensive recommendations by the revenue from all of the recommended items the user clicked. Amazon Personalize then returns a normalized average of all user scores. The closer the `average_rewards_at_k` is to 1, the more revenue on average you can expect to gain per user from recommendations.  
 For more information, see [Optimizing a solution for an additional objective](optimizing-solution-for-objective.md). 

**normalized\$1discounted\$1cumulative\$1gain\$1with\$1event\$1weights\$1at\$1k**  
 When you create a solution version (train a model) for a solution with an events configuration, Amazon Personalize generates an `normalized_discounted_cumulative_gain_with_event_weights_at_k` metric. The score for `normalized_discounted_cumulative_gain_with_event_weights_at_k` tells you how well the solution version performs considering the events weight you set for each event types.   
 It is similar to normalized discounted cumulative gain (NDCG) at K but the reward for each correct prediction will be weighted. In contrast, in the original NDCG at K, each correct prediction will all carry a weight of 1. For example, with “purchase” of weight 0.3 and “click” of weight 0.1, correctly predicting “purchase” item will get a reward of 1.5 while predicting “click” item will get a reward of 0.5.   
 For more information, see [Optimizing a solution with events configuration](optimizing-solution-events-config.md). 

**trend prediction accuracy**  
If you trained the solution version with the [Trending-Now](native-recipe-trending-now.md) recipe, the rate of increase in popularity of items recommended by the model. The higher the trend prediction accuracy (the closer to 1), the better the model is at correctly identifying trending items.   
 To calculate popularity acceleration, Amazon Personalize divides the rate of increase in popularity across all recommended items by the total popularity increase of the top 25 trending items. These items come from the actual interactions in the testing set.   
 Depending on your data distribution and what you choose for Trend discovery frequency, the value for trend prediction accuracy can be 0.0. 

**hit (hit at K)**  
If you trained the solution version with a USER\$1SEGMENTATION recipe, the average number of users in the predicted top relevant K results that match the actual users. Actual users are the users who actually interacted with the items in the test set. K is the top 1% of the most relevant users. The higher the value the more accurate the predictions. 

**recall (recall at K)**  
If you trained the solution version with a USER\$1SEGMENTATION recipe, the average percentage of predicted users in the predicted top relevant K results that match the actual users. Actual users are the users who actually interacted with the items in the test set. K is the top 1% of the most relevant users. The higher the value, the more accurate the predictions.

**recall**  
If you train a solution version with the Next-Best-Action recipe, this metric tells you how good your solution version is at discovering actions that users will interact with.   
 To calculate `recall`, for each action in your dataset, Amazon Personalize divides the number of users that were correctly predicted to take the action by the total number of users that actually take the action in the testing set. Amazon Personalize then calculates the average for all actions in your dataset.   
For example, if 100 users take an action in the testing set, and Amazon Personalize predicted 50 of these users would take the action, the `recall` for the action is: `50 / 100 = .50`. Amazon Personalize then applies this calculation for all actions and returns the average.

**Area under the curve (AUC)**  
If you trained the solution version with a PERSONALIZED\$1ACTIONS recipe, the area under the Receiver Operating Characteristic curve for your solution version. This metric tells you how well the solution version performs at correctly identifying actions that users will take.   
The Receiver Operating Characteristic curve plots the performance of the solution version. It plots the true positive (actions correctly predicted as relevant) and false positive (actions incorrectly predicted as relevant) rates at different threshold values. The Area under the curve (AUC) is a score that summarizes the performance of the solution version based on its curve.   
 The AUC of a solution version can between 0 and 1. The closer to 1, the better the model is at predicting relevant actions for your users. 

**Item Popularity**  
If you trained the solution version with the `aws-semantic-similarity` recipe, this metric measures how much engagement an item has received (likes, views, shares, etc.) relative to other items in your catalog. The higher the item popularity score (the closer to 1), the more user interactions the item has accumulated compared to other items.  
To calculate item popularity, Amazon Personalize counts the total number of unique users who have interacted with each item (through events like views, clicks, purchases, etc.). The raw engagement count for each item is then normalized across all items in your dataset, resulting in scores between 0 and 1. A score closer to 0 indicates low engagement while a score closer to 1 indicates high engagement on an average with items in the catalogue.

**Item Freshness**  
If you trained the solution version with the `aws-semantic-similarity` recipe, this metric measures how recently an item was added to your catalog relative to other items. The higher the item freshness score (the closer to 1), the more recently the item was created.  
To calculate item freshness, Amazon Personalize determines each item's age using the CREATION\$1TIMESTAMP from your Items dataset. The age is calculated as the difference between the training time and the item's creation timestamp. These ages are then normalized across all items, with newer items receiving scores closer to 1. A score closer to 0 indicates more old items while a score closer to 1 indicates more newer items on an average in the catalogue.

**Item Similarity**  
If you trained the solution version with the `aws-semantic-similarity` recipe, this metric measures how semantically related recommended items will be to your input item(s) based on their content, attributes, and metadata. The higher the item similarity score (the closer to 1), the more closely the recommended items match the characteristics of your reference item(s).  
To calculate item similarity, Amazon Personalize computes similarity scores between each recommended item and the input item(s) using semantic embeddings derived from item metadata and attributes. A score closer to 0 indicates low semantic similarity between the items in the catalogue on an average while a score closer to 1 indicates high semantic similarity between the items in the catalogue on an average. This metric helps you understand how well the model is capturing semantic relationships in your recommendations.

## Example


The following is a simple example for a solution version that produces a list of recommendations for a specific user. The second and fifth recommendations match records in the testing data for this user. These are the relevant recommendations. If `K` is set at `5`, the following metrics are generated for the user.

**reciprocal\$1rank**  
Calculation: 1/2  
Result: 0.5000

**normalized\$1discounted\$1cumulative\$1gain\$1at\$15**  
Calculation: (1/log(1 \$1 2) \$1 1/log(1 \$1 5)) / (1/log(1 \$1 1) \$1 1/log(1 \$1 2))  
Result: 0.6241

**precision\$1at\$15**  
Calculation: 2/5  
Result: 0.4000

## Additional resources


For information on evaluating a solution version with A/B testing, see [ Using A/B testing to measure the efficacy of recommendations generated by Amazon Personalize](https://aws.amazon.com/blogs/machine-learning/using-a-b-testing-to-measure-the-efficacy-of-recommendations-generated-by-amazon-personalize/). To dive deeper in different types of metrics for recommender systems, see the following external resources:
+ [MRR vs MAP vs NDCG: Rank-Aware Evaluation Metrics And When To Use Them](https://medium.com/swlh/rank-aware-recsys-evaluation-metrics-5191bba16832/)
+  [Discounted Cumulative Gain: the ranking metrics you should know about](https://medium.com/@maeliza.seymour/discounted-cumulative-gain-the-ranking-metrics-you-should-know-about-e1d1623f8cd9) 
+  [Recall and Precision at k for Recommender Systems](https://medium.com/@bond.kirill.alexandrovich/precision-and-recall-in-recommender-systems-and-some-metrics-stuff-ca2ad385c5f8) 
+  [Ranking Evaluation Metrics for Recommender Systems](https://towardsdatascience.com/ranking-evaluation-metrics-for-recommender-systems-263d0a66ef54) 
+  [Receiver operating characteristic](https://en.wikipedia.org/wiki/Receiver_operating_characteristic) 

# Deploying an Amazon Personalize solution version with a campaign
Creating a campaign

For real-time recommendations with custom resources, after you complete [Manually creating a solution version](creating-a-solution-version.md), you are ready to deploy your solution version with a campaign.

 A *campaign* deploys a solution version (trained model) with a provisioned transaction capacity for generating real-time recommendations. After you create a campaign, you use the [GetRecommendations](API_RS_GetRecommendations.md) or [GetPersonalizedRanking](API_RS_GetPersonalizedRanking.md) API operations to get recommendations. If you are getting batch item recommendations or user segments, you don't need to create a campaign. For more information, see [Getting batch item recommendations](getting-batch-recommendations.md) or [Getting batch user segments](getting-user-segments.md). 

When you create a campaign, you can configure the following:
+ You can configure the campaign to automatically update to use your solution's latest solution version. For more information see [Automatic campaign updates](#create-campaign-automatic-latest-sv-update). 
+ You can enable item metadata in recommendations. For more information, see [Item metadata in recommendations](#create-campaign-return-metadata). 
+ You can specify the minimum provisioned transactions per second for the campaign. This is the baseline transaction throughput for the campaign provisioned by Amazon Personalize. It sets the minimum billing charge for the campaign while it is active. For more information, see [Minimum provisioned transactions per second and auto-scaling](#min-tps-auto-scaling).

You can create a campaign with the Amazon Personalize console, AWS Command Line Interface (AWS CLI), or AWS SDKs. If you want to change an existing campaign's settings, such as enabling metadata in recommendations, you must update your campaign. For more information, see [Updating an Amazon Personalize campaign's configuration](update-campaigns.md). 

 You incur campaign costs while the campaign is active. To avoid unnecessary costs, make sure to delete the campaign when you are finished. For information about campaign costs, see [Amazon Personalize pricing](https://aws.amazon.com/personalize/pricing/). 

**Topics**
+ [

## Automatic campaign updates
](#create-campaign-automatic-latest-sv-update)
+ [

## Minimum provisioned transactions per second and auto-scaling
](#min-tps-auto-scaling)
+ [

## Item metadata in recommendations
](#create-campaign-return-metadata)
+ [

## Creating a campaign (console)
](#create-campaign-console)
+ [

## Creating a campaign (AWS CLI)
](#create-campaign-cli)
+ [

## Creating a campaign (AWS SDKs)
](#create-campaign-sdk)

## Automatic campaign updates


When you create a campaign, you can enable automatic campaign updates. With automatic updates, the campaign automatically updates to deploy the latest automatically or manually trained solution version of your solution. This makes it easier for you to keep your campaign current.

For example, if your solution uses [automatic training](solution-config-auto-training.md) to create a new solution version every seven days, your campaign would automatically update to use the latest solution version for every weekly training. If you don't use automatic campaign updates, you must manually update the campaign to deploy the latest trained model.
+ To enable automatic campaign updates when you create a campaign with the Amazon Personalize console, choose **Automatically update to use your solution's latest solution version** in the **Campaign details**. You can find the timestamp for the latest update on the campaign details page.

  For more information, see [Creating a campaign (console)](#create-campaign-console). 
+ To enable automatic campaign updates when you use the [CreateCampaign](API_CreateCampaign.md) API operation, for the `SolutionVersionArn` parameter, specify the Amazon Resource Name (ARN) of your solution in `SolutionArn/$LATEST` format. In the `campaignConfig`, set `enableMetadataWithRecommendations` to `true`. 

  To get the timestamp of the latest campaign update, you can use the [DescribeCampaign](API_DescribeCampaign.md) API operation and check `latestCampaignUpdate` details in the response. 

  For code samples that show you how to enable automatic updates, see [Creating a campaign (AWS CLI)](#create-campaign-cli) or [Creating a campaign (AWS SDKs)](#create-campaign-sdk).

## Minimum provisioned transactions per second and auto-scaling
Minimum provisioned TPS

**Important**  
 A high `minProvisionedTPS` will increase your cost. We recommend starting with 1 for `minProvisionedTPS` (the default). Track your usage using Amazon CloudWatch metrics, and increase the `minProvisionedTPS` as necessary.

 When you create an Amazon Personalize campaign, you can specify the minimum provisioned transactions per second (`minProvisionedTPS`) for the campaign. This is the baseline transaction throughput for the campaign provisioned by Amazon Personalize. It sets the minimum billing charge for the campaign while it is active. A transaction is a single `GetRecommendations` or `GetPersonalizedRanking` request. The default `minProvisionedTPS` is 1.

 If your TPS increases beyond the `minProvisionedTPS`, Amazon Personalize auto-scales the provisioned capacity up and down, but never below `minProvisionedTPS`. There's a short time delay while the capacity is increased that might cause loss of transactions. When your traffic reduces, capacity returns to the `minProvisionedTPS`. 

You are charged for the minimum provisioned TPS or, if your requests exceed the `minProvisionedTPS`, the actual TPS. The actual TPS is the total number of recommendation requests you make. We recommend starting with a low `minProvisionedTPS`, track your usage using Amazon CloudWatch metrics, and then increase the `minProvisionedTPS` as necessary.

For more information about campaign costs, see [Amazon Personalize pricing](https://aws.amazon.com/personalize/pricing/).

## Item metadata in recommendations


**Important**  
If you use the User-Personalization-v2 or Personalized-Ranking-v2 recipe, you don't incur additional costs for metadata. For all other recipes and all domain use cases, you incur additional costs. For more information, see [Amazon Personalize pricing](https://aws.amazon.com/personalize/pricing/).

When you get recommendations, you can have Amazon Personalize include item metadata in recommendation results. In your request, you can choose the columns from your Items dataset to include. Amazon Personalize returns this data for each item in the recommendation response. 

You might use metadata to enrich recommendations in your user interface, such as adding the genres for movies to carousels. Or you might use it to visually assess recommendation quality. If you use generative AI in your app, you can plug the metadata into AI prompts to generate more relevant content. For more information about using Amazon Personalize with generative AI, see [Amazon Personalize and generative AI](personalize-with-gen-ai.md).

### Enabling metadata


To add metadata to recommendations, you must have an Items dataset with a column of metadata. You don't have to use the metadata in training. For information about creating a dataset, see [Creating a schema and a dataset](data-prep-creating-datasets.md). For information updating data, see [Updating data in datasets after training](updating-datasets.md).

 If you use the User-Personalization-v2 or Personalized-Ranking-v2 recipe, new campaigns automatically have the option to include item metadata with recommendation results. You don't have manually enable metadata for your campaign. For all other recipes and domain use cases, you must enable the metadata option: 
+ To enable metadata with the Amazon Personalize console, when you create the campaign, choose **Return items metadata in recommendation results** in the **Campaign details**. For more information, see [Creating a campaign (console)](#create-campaign-console). 
+ To enable metadata with the AWS SDKs or AWS CLI, use the [CreateCampaign](API_CreateCampaign.md) API operation and in the `campaignConfig` set `enableMetadataWithRecommendations` to `true`. For more information, see [Creating a campaign (AWS CLI)](#create-campaign-cli) or [Creating a campaign (AWS SDKs)](#create-campaign-sdk).

## Creating a campaign (console)


**Important**  
 You incur campaign costs while the campaign is active. To avoid unnecessary costs, make sure to delete the campaign when you are finished. For information about campaign costs, see [Amazon Personalize pricing](https://aws.amazon.com/personalize/pricing/). 

After your solution version status is Active, you are ready to deploy it with an Amazon Personalize campaign.

**To create a campaign (console)**

1. Open the Amazon Personalize console at [https://console.aws.amazon.com/personalize/home](https://console.aws.amazon.com/personalize/home) and sign into your account.

1. Choose the dataset group with the solution version that you want to deploy. 

1. In the navigation pane, under **Custom resources**, choose **Campaigns**.

1. On the **Campaigns** page, choose **Create campaign**.

1. On the **Create new campaign** page, for **Campaign details**, provide the following information: 
   + **Campaign name** – Enter the name of the campaign. The text you enter here appears on the Campaign dashboard and details page.
   + **Solution** – Choose the solution that you just created.
   + **Automatically update to use your solution's latest solution version** – Choose this option to have the campaign automatically use the latest active solution version. If you don't choose this, you must manually update the campaign each time you want to deploy a new solution version. For more information, see [Automatic campaign updates](#create-campaign-automatic-latest-sv-update). 
   + **Solution version ID** – If you don't use automatic campaign updates to use the latest solution version, choose the ID of the solution version that you want to deploy.
   + **Minimum provisioned transactions per second (called minProvisionedTPS in APIs)** – Set the minimum provisioned transactions per second that Amazon Personalize supports. A high value will increase your charges. We recommend that you start with 1 (the default). Track your usage by using Amazon CloudWatch metrics, and increase the `minProvisionedTPS` as necessary. For more information, see [Minimum provisioned transactions per second and auto-scaling](#min-tps-auto-scaling).
   + **Return items metadata in recommendation results** – Choose this option if you want the option to include metadata with recommendation results. If enabled, you can specify the columns from your Items dataset when you get recommendations. For more information, see [Item metadata in recommendations](#create-campaign-return-metadata).

1. If you used the User-Personalization recipe, in **Campaign configuration**, you can optionally enter values for the **Exploration weight** and **Exploration item age cut off**. For more information, see [User-Personalization](native-recipe-new-item-USER_PERSONALIZATION.md).

1. For **Tags**, optionally add any tags. For more information about tagging Amazon Personalize resources, see [Tagging Amazon Personalize resources](tagging-resources.md).

1. Choose **Create campaign**.

1. On the campaign details page, when the campaign status is **Active**, you can use the campaign to get recommendations and record impressions. For more information, see [Getting recommendations from Amazon Personalize](getting-recommendations.md). 

   The campaign is ready when its status is ACTIVE. If you retrain your solution version, or if you want to change your campaign settings, you must update your campaign. For more information, see [Updating an Amazon Personalize campaign's configuration](update-campaigns.md). 

## Creating a campaign (AWS CLI)


**Important**  
 You incur campaign costs while the campaign is active. To avoid unnecessary costs, make sure to delete the campaign when you are finished. For information about campaign costs, see [Amazon Personalize pricing](https://aws.amazon.com/personalize/pricing/). 

After your solution version is Active, you are ready to deploy it with an Amazon Personalize campaign. To create a campaign with the AWS CLI, you use the `create-campaign` command.

The following code sample shows you how to create a campaign. It deploys the latest solution version of a solution that uses the User-Personalization recipe. The campaign it creates automatically updates to use future solution versions. The code uses the following configuration: 
+ It configures the campaign to automatically update to use the latest solution version for your solution: The `solution-version-arn` is in `solution ARN/$LATEST` format, and `syncWithLatestSolutionVersion` is `True`. To use the code, replace `solution ARN` with the Amazon Resource Name (ARN) of your solution.

  To disable automatic `syncWithLatestSolutionVersion`, specify only the solution version ARN (without `/$LATEST`), and set `syncWithLatestSolutionVersion` to `False`. 
+ It sets the `enableMetadataWithRecommendations` option to `True`. This enables a recommendation request option to include item metadata from an Items dataset with recommendation results. To disable this option, set it to `False`. For more information, see [Item metadata in recommendations](#create-campaign-return-metadata).
+ It sets `min-provisioned-tps` to 1 (the default). We recommend starting with 1 for `minProvisionedTPS` (the default). Track your usage by using Amazon CloudWatch metrics, and increase the `minProvisionedTPS` as necessary. For more information, see [Minimum provisioned transactions per second and auto-scaling](#min-tps-auto-scaling).

For a complete list of all parameters, see [CreateCampaign](API_CreateCampaign.md).

```
aws personalize create-campaign \
--name campaign-name \
--solution-version-arn solution-arn/\$LATEST \
--min-provisioned-tps 1 \
--campaign-config "{"\"syncWithLatestSolutionVersion"\": "true", "\"enableMetadataWithRecommendations"\": "true"}"
```

The campaign is ready when its status is ACTIVE. To get the current status, call [DescribeCampaign](API_DescribeCampaign.md) and check that the `status` field is `ACTIVE`.

If you retrain your solution version and your campaign doesn't automatically update to use the latest solution version, or if your want to change your campaign settings, you must update your campaign. For more information, see [Updating an Amazon Personalize campaign's configuration](update-campaigns.md). 

Amazon Personalize provides you with operations for managing campaigns such as [ListCampaigns](API_ListCampaigns.md) to list the campaigns that you have created. You can delete a campaign by calling [DeleteCampaign](API_DeleteCampaign.md). If you delete a campaign, the solution versions that are part of the campaign are not deleted.

After you have created your campaign, you can use it to make recommendations. For more information, see [Getting recommendations from Amazon Personalize](getting-recommendations.md).

## Creating a campaign (AWS SDKs)


**Important**  
 You incur campaign costs while the campaign is active. To avoid unnecessary costs, make sure to delete the campaign when you are finished. For information about campaign costs, see [Amazon Personalize pricing](https://aws.amazon.com/personalize/pricing/). 

After your solution version is Active, you are ready to deploy it with an Amazon Personalize campaign. To create a campaign with AWS SDKs, you use the [CreateCampaign](API_CreateCampaign.md) API operation.

The following code sample shows you how to create a campaign. The code deploys the latest solution version of a solution that uses the User-Personalization recipe. The campaign it creates automatically updates to use future solution versions. The code uses the following configuration: 
+ It configures the campaign to automatically update to use the latest solution version for your solution: The `solutionVersionArn` is in `solution ARN/$LATEST` format, and `syncWithLatestSolutionVersion` is `True`. To use the code, replace `solution ARN` with the Amazon Resource Name (ARN) of your solution version.

  To disable automatic `syncWithLatestSolutionVersion`, specify only the solution version ARN (without `/$LATEST`), and set `syncWithLatestSolutionVersion` to `False`. 
+ It sets the `enableMetadataWithRecommendations` option to `True`. This enables a recommendation request option to include item metadata from an Items dataset with recommendation results. To disable this option, set it to `False`. For more information, see [Item metadata in recommendations](#create-campaign-return-metadata).
+ It sets `minProvisionedTPS` to 1 (the default). We recommend that you start with 1 for `minProvisionedTPS` (the default). Track your usage by using Amazon CloudWatch metrics, and increase the `minProvisionedTPS` as necessary. For more information, see [Minimum provisioned transactions per second and auto-scaling](#min-tps-auto-scaling).

For a complete list of all parameters, see [CreateCampaign](API_CreateCampaign.md).

------
#### [ SDK for Python (Boto3) ]

```
import boto3

personalize = boto3.client('personalize')

response = personalize.create_campaign(
    name = 'campaign name',
    solutionVersionArn = 'solution ARN/$LATEST',
    minProvisionedTPS = 1,
    campaignConfig = {"syncWithLatestSolutionVersion": True, "enableMetadataWithRecommendations": True}
)

arn = response['campaignArn']

description = personalize.describe_campaign(campaignArn = arn)['campaign']
print('Name: ' + description['name'])
print('ARN: ' + description['campaignArn'])
print('Status: ' + description['status'])
```

------
#### [ SDK for JavaScript v3 ]

```
// Get service clients module and commands using ES6 syntax.
import { CreateCampaignCommand, PersonalizeClient } from
  "@aws-sdk/client-personalize";

// create personalizeClient
const personalizeClient = new PersonalizeClient({ region: "REGION" });

// set the campaign parameters
export const createCampaignParam = {
  solutionVersionArn: "SOLUTION_ARN/$LATEST" /* required */,
  name: "NAME" /* required */,
  minProvisionedTPS: 1 /* optional */,
  campaignConfig: {   /* optional */
    syncWithLatestSolutionVersion: true,
    enableMetadataWithRecommendations: true,
  },
};

export const run = async () => {
  try {
    const response = await personalizeClient.send(
      new CreateCampaignCommand(createCampaignParam)
    );
    console.log("Success", response);
    return response; // For unit tests.
  } catch (err) {
    console.log("Error", err);
  }
};
run();
```

------

The campaign is ready when its status is ACTIVE. To get the current status, call [DescribeCampaign](API_DescribeCampaign.md), and check that the `status` field is `ACTIVE`.

If you manually retrain your solution version, or if you want to change your campaign settings, you must update your campaign. For more information, see [Updating an Amazon Personalize campaign's configuration](update-campaigns.md). 

Amazon Personalize provides you with operations for managing campaigns such as [ListCampaigns](API_ListCampaigns.md) to list the campaigns that you have created. You can delete a campaign by calling [DeleteCampaign](API_DeleteCampaign.md). If you delete a campaign, the solution versions that are part of the campaign are not deleted.

After you have created your campaign, use it to make recommendations. For more information, see [Getting recommendations from Amazon Personalize](getting-recommendations.md).

# Updating an Amazon Personalize campaign's configuration
Updating a campaign

To change your campaign's [Minimum provisioned TPS](campaigns.md#min-tps-auto-scaling), manually deploy a new solution version, or modify a campaign's configuration, such as turning on the option to include metadata in recommendations, you must manually update the campaign. 

 The following doesn't require a manual campaign update: 
+ If your campaign uses automatic campaign updates, you don't have to update it to deploy the latest automatically or manually trained solution version of your solution. For more information, see [Automatic campaign updates](campaigns.md#create-campaign-automatic-latest-sv-update). 
+  With User-Personalization-v2, User-Personalization, or Next-Best-Action, Amazon Personalize automatically updates your latest solution version every two hours to include new items or actions in recommendations. Your campaign automatically uses the updated solution version. 

You manually update a campaign with the Amazon Personalize console, AWS Command Line Interface (AWS CLI), or AWS SDKs.

**Note**  
To update a campaign to turn on the option to include metadata in recommendations, you must have an Items dataset with a column of metadata. You don't have to use the metadata in training.  
If your campaign previously deployed a solution version that used User-Personalization-v2 or Personalized-Ranking-v2, and you are switching to an older version of the recipes, the option to include metadata is off by default. You can enable it when you update the campaign. For more information, see [Item metadata in recommendations](campaigns.md#create-campaign-return-metadata).

**Topics**
+ [

## Updating a campaign (console)
](#update-campaign-console)
+ [

## Updating a campaign (AWS CLI)
](#update-campaign-cli)
+ [

## Updating a campaign (AWS SDKs)
](#update-campaign-sdk)

## Updating a campaign (console)


To deploy a manually retrained solution version or make changes to your campaign configuration, you must update your campaign.

**To update a campaign (console)**

1. Open the Amazon Personalize console at [https://console.aws.amazon.com/personalize/home](https://console.aws.amazon.com/personalize/home) and sign into your account.

1.  Choose the dataset group with the campaign you want to update. 

1. In the navigation pane, choose **Campaigns**.

1. On the **Campaigns** page, choose the campaign you want to update.

1. On the campaign details page, choose **Update**.

1. On the **Update campaign** page, make your changes. For example, if you are deploying a retrained solution version, for **Solution version ID**, choose the identification number for the new solution version.

1. Choose **Update**. Amazon Personalize updates the campaign to use the new solution version and any changed configurations.

## Updating a campaign (AWS CLI)


To deploy a new solution version, change your campaign's [Minimum provisioned TPS](campaigns.md#min-tps-auto-scaling), or change your campaign's configuration, you must update your campaign. Use the following `update-campaign` command to update a campaign to use a new solution version with the AWS CLI. 

Replace `campaign arn` with the Amazon Resource Name (ARN) of the campaign you want to update. Replace `new solution version arn` with the solution version you want to deploy. 

```
aws personalize update-campaign \
--campaign-arn campaign arn \
--solution-version-arn new solution version arn \
--min-provisioned-tps 1
```

## Updating a campaign (AWS SDKs)


To deploy a new solution version, change your campaign's [Minimum provisioned TPS](campaigns.md#min-tps-auto-scaling) or change your campaign's configuration, you must update your campaign. Use the following code to update a campaign with the SDK for Python (Boto3) or SDK for Java 2.x. For a complete list of parameters, see [UpdateCampaign](API_UpdateCampaign.md). 

------
#### [ SDK for Python (Boto3) ]

Use the following `update_campaign` method to deploy a new solution version. Replace `campaign arn` with the Amazon Resource Name (ARN) of the campaign you want to update, replace the `new solution version arn` with the new solution version ARN and optionally change the `minProvisionedTPS`.

```
import boto3

personalize = boto3.client('personalize')

response = personalize.update_campaign(
    campaignArn = 'campaign arn',
    solutionVersionArn = 'new solution version arn',
    minProvisionedTPS = 1,
)

arn = response['campaignArn']

description = personalize.describe_campaign(campaignArn = arn)['campaign']
print('Name: ' + description['name'])
print('ARN: ' + description['campaignArn'])
print('Status: ' + description['status'])
```

------
#### [ SDK for Java 2.x ]

Use the following `updateCampaign` method to update a campaign to use a new solution version. Pass as parameters an Amazon Personalize service client, the new solution version's Amazon Resource Name (ARN), and the [Minimum provisioned TPS](campaigns.md#min-tps-auto-scaling). 

```
public static void updateCampaign(PersonalizeClient personalizeClient, 
                                String campaignArn,
                                String solutionVersionArn, 
                                Integer minProvisionedTPS) {

    try {    
        // build the updateCampaignRequest
        UpdateCampaignRequest updateCampaignRequest = UpdateCampaignRequest.builder()
            .campaignArn(campaignArn)
            .solutionVersionArn(solutionVersionArn)
            .minProvisionedTPS(minProvisionedTPS)
            .build();
        
        // update the campaign
        personalizeClient.updateCampaign(updateCampaignRequest);
        
        DescribeCampaignRequest campaignRequest = DescribeCampaignRequest.builder()
              .campaignArn(campaignArn)
              .build();
    
        DescribeCampaignResponse campaignResponse = personalizeClient.describeCampaign(campaignRequest);
        Campaign updatedCampaign = campaignResponse.campaign();
        
        System.out.println("The Campaign status is " + updatedCampaign.status());
    
    } catch (PersonalizeException e) {
        System.err.println(e.awsErrorDetails().errorMessage());
        System.exit(1);
    }
}
```

------