recommenders

Creates, updates, deletes, gets or lists a recommenders resource.

Overview

Name	recommenders
Type	Resource
Id	aws.personalize.recommenders

Fields

The following fields are returned by SELECT queries:

describe_recommender

Name	Datatype	Description
name	string	The name of the recommender. (pattern: <code>^[a-zA-Z0-9][a-zA-Z0-9-_]*</code>)
creation_date_time	string (date-time)	The date and time (in Unix format) that the recommender was created.
dataset_group_arn	string	The Amazon Resource Name (ARN) of the Domain dataset group that contains the recommender. (pattern: <code>arn:([a-z\d-]+):personalize:.:.:.+</code>)
failure_reason	string	If a recommender fails, the reason behind the failure.
last_updated_date_time	string (date-time)	The date and time (in Unix format) that the recommender was last updated.
latest_recommender_update	object	Provides a summary of the latest updates to the recommender.
model_metrics	object	Provides evaluation metrics that help you determine the performance of a recommender. For more information, see Evaluating a recommender.
recipe_arn	string	The Amazon Resource Name (ARN) of the recipe (Domain dataset group use case) that the recommender was created for. (pattern: <code>arn:([a-z\d-]+):personalize:.:.:.+</code>)
recommender_arn	string	The Amazon Resource Name (ARN) of the recommender. (pattern: <code>arn:([a-z\d-]+):personalize:.:.:.+</code>)
recommender_config	object	The configuration details of the recommender.
status	string	The status of the recommender. A recommender can be in one of the following states: CREATE PENDING > CREATE IN_PROGRESS > ACTIVE -or- CREATE FAILED STOP PENDING > STOP IN_PROGRESS > INACTIVE > START PENDING > START IN_PROGRESS > ACTIVE DELETE PENDING > DELETE IN_PROGRESS

list_recommenders

Name	Datatype	Description
name	string	The name of the recommender. (pattern: <code>^[a-zA-Z0-9][a-zA-Z0-9-_]*</code>)
creation_date_time	string (date-time)	The date and time (in Unix format) that the recommender was created.
dataset_group_arn	string	The Amazon Resource Name (ARN) of the Domain dataset group that contains the recommender. (pattern: <code>arn:([a-z\d-]+):personalize:.:.:.+</code>)
last_updated_date_time	string (date-time)	The date and time (in Unix format) that the recommender was last updated.
recipe_arn	string	The Amazon Resource Name (ARN) of the recipe (Domain dataset group use case) that the recommender was created for. (pattern: <code>arn:([a-z\d-]+):personalize:.:.:.+</code>)
recommender_arn	string	The Amazon Resource Name (ARN) of the recommender. (pattern: <code>arn:([a-z\d-]+):personalize:.:.:.+</code>)
recommender_config	object	The configuration details of the recommender.
status	string	The status of the recommender. A recommender can be in one of the following states: CREATE PENDING > CREATE IN_PROGRESS > ACTIVE -or- CREATE FAILED STOP PENDING > STOP IN_PROGRESS > INACTIVE > START PENDING > START IN_PROGRESS > ACTIVE DELETE PENDING > DELETE IN_PROGRESS

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
describe_recommender	select	region		Describes the given recommender, including its status. A recommender can be in one of the following states: CREATE PENDING > CREATE IN_PROGRESS > ACTIVE -or- CREATE FAILED STOP PENDING > STOP IN_PROGRESS > INACTIVE > START PENDING > START IN_PROGRESS > ACTIVE DELETE PENDING > DELETE IN_PROGRESS When the status is CREATE FAILED, the response includes the failureReason key, which describes why. The modelMetrics key is null when the recommender is being created or deleted. For more information on recommenders, see CreateRecommender.
list_recommenders	select	region		Returns a list of recommenders in a given Domain dataset group. When a Domain dataset group is not specified, all the recommenders associated with the account are listed. The response provides the properties for each recommender, including the Amazon Resource Name (ARN). For more information on recommenders, see CreateRecommender.
create_recommender	insert	region, name, datasetGroupArn, recipeArn		Creates a recommender with the recipe (a Domain dataset group use case) you specify. You create recommenders for a Domain dataset group and specify the recommender's Amazon Resource Name (ARN) when you make a GetRecommendations request. Minimum recommendation requests per second A high minRecommendationRequestsPerSecond will increase your bill. We recommend starting with 1 for minRecommendationRequestsPerSecond (the default). Track your usage using Amazon CloudWatch metrics, and increase the minRecommendationRequestsPerSecond as necessary. When you create a recommender, you can configure the recommender's minimum recommendation requests per second. The minimum recommendation requests per second (minRecommendationRequestsPerSecond) specifies the baseline recommendation request throughput provisioned by Amazon Personalize. The default minRecommendationRequestsPerSecond is 1. A recommendation request is a single GetRecommendations operation. Request throughput is measured in requests per second and Amazon Personalize uses your requests per second to derive your requests per hour and the price of your recommender usage. If your requests per second increases beyond minRecommendationRequestsPerSecond, Amazon Personalize auto-scales the provisioned capacity up and down, but never below minRecommendationRequestsPerSecond. There's a short time delay while the capacity is increased that might cause loss of requests. Your bill is the greater of either the minimum requests per hour (based on minRecommendationRequestsPerSecond) or the actual number of requests. The actual request throughput used is calculated as the average requests/second within a one-hour window. We recommend starting with the default minRecommendationRequestsPerSecond, track your usage using Amazon CloudWatch metrics, and then increase the minRecommendationRequestsPerSecond as necessary. Status A recommender can be in one of the following states: CREATE PENDING > CREATE IN_PROGRESS > ACTIVE -or- CREATE FAILED STOP PENDING > STOP IN_PROGRESS > INACTIVE > START PENDING > START IN_PROGRESS > ACTIVE DELETE PENDING > DELETE IN_PROGRESS To get the recommender status, call DescribeRecommender. Wait until the status of the recommender is ACTIVE before asking the recommender for recommendations. Related APIs ListRecommenders DescribeRecommender UpdateRecommender DeleteRecommender
update_recommender	update	region, recommenderArn, recommenderConfig		Updates the recommender to modify the recommender configuration. If you update the recommender to modify the columns used in training, Amazon Personalize automatically starts a full retraining of the models backing your recommender. While the update completes, you can still get recommendations from the recommender. The recommender uses the previous configuration until the update completes. To track the status of this update, use the latestRecommenderUpdate returned in the DescribeRecommender operation.
delete_recommender	delete	region		Deactivates and removes a recommender. A deleted recommender can no longer be specified in a GetRecommendations request.
start_recommender	exec	region, recommenderArn		Starts a recommender that is INACTIVE. Starting a recommender does not create any new models, but resumes billing and automatic retraining for the recommender.
stop_recommender	exec	region, recommenderArn		Stops a recommender that is ACTIVE. Stopping a recommender halts billing and automatic retraining for the recommender.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
region	string	AWS region (default: us-east-1)

SELECT examples

describe_recommender

Describes the given recommender, including its status. A recommender can be in one of the following states: CREATE PENDING > CREATE IN_PROGRESS > ACTIVE -or- CREATE FAILED STOP PENDING > STOP IN_PROGRESS > INACTIVE > START PENDING > START IN_PROGRESS > ACTIVE DELETE PENDING > DELETE IN_PROGRESS When the status is CREATE FAILED, the response includes the failureReason key, which describes why. The modelMetrics key is null when the recommender is being created or deleted. For more information on recommenders, see CreateRecommender.

SELECT
name,
creation_date_time,
dataset_group_arn,
failure_reason,
last_updated_date_time,
latest_recommender_update,
model_metrics,
recipe_arn,
recommender_arn,
recommender_config,
status
FROM aws.personalize.recommenders
WHERE region = '{{ region }}' -- required
;

list_recommenders

Returns a list of recommenders in a given Domain dataset group. When a Domain dataset group is not specified, all the recommenders associated with the account are listed. The response provides the properties for each recommender, including the Amazon Resource Name (ARN). For more information on recommenders, see CreateRecommender.

SELECT
name,
creation_date_time,
dataset_group_arn,
last_updated_date_time,
recipe_arn,
recommender_arn,
recommender_config,
status
FROM aws.personalize.recommenders
WHERE region = '{{ region }}' -- required
;

INSERT examples

create_recommender

Creates a recommender with the recipe (a Domain dataset group use case) you specify. You create recommenders for a Domain dataset group and specify the recommender's Amazon Resource Name (ARN) when you make a GetRecommendations request. Minimum recommendation requests per second A high minRecommendationRequestsPerSecond will increase your bill. We recommend starting with 1 for minRecommendationRequestsPerSecond (the default). Track your usage using Amazon CloudWatch metrics, and increase the minRecommendationRequestsPerSecond as necessary. When you create a recommender, you can configure the recommender's minimum recommendation requests per second. The minimum recommendation requests per second (minRecommendationRequestsPerSecond) specifies the baseline recommendation request throughput provisioned by Amazon Personalize. The default minRecommendationRequestsPerSecond is 1. A recommendation request is a single GetRecommendations operation. Request throughput is measured in requests per second and Amazon Personalize uses your requests per second to derive your requests per hour and the price of your recommender usage. If your requests per second increases beyond minRecommendationRequestsPerSecond, Amazon Personalize auto-scales the provisioned capacity up and down, but never below minRecommendationRequestsPerSecond. There's a short time delay while the capacity is increased that might cause loss of requests. Your bill is the greater of either the minimum requests per hour (based on minRecommendationRequestsPerSecond) or the actual number of requests. The actual request throughput used is calculated as the average requests/second within a one-hour window. We recommend starting with the default minRecommendationRequestsPerSecond, track your usage using Amazon CloudWatch metrics, and then increase the minRecommendationRequestsPerSecond as necessary. Status A recommender can be in one of the following states: CREATE PENDING > CREATE IN_PROGRESS > ACTIVE -or- CREATE FAILED STOP PENDING > STOP IN_PROGRESS > INACTIVE > START PENDING > START IN_PROGRESS > ACTIVE DELETE PENDING > DELETE IN_PROGRESS To get the recommender status, call DescribeRecommender. Wait until the status of the recommender is ACTIVE before asking the recommender for recommendations. Related APIs ListRecommenders DescribeRecommender UpdateRecommender DeleteRecommender

INSERT INTO aws.personalize.recommenders (
name,
datasetGroupArn,
recipeArn,
recommenderConfig,
tags,
region
)
SELECT 
'{{ name }}' /* required */,
'{{ datasetGroupArn }}' /* required */,
'{{ recipeArn }}' /* required */,
'{{ recommenderConfig }}',
'{{ tags }}',
'{{ region }}'
RETURNING
recommender_arn
;

Manifest

# Description fields are for documentation purposes
- name: recommenders
props:
  - name: region
    value: "{{ region }}"
    description: Required parameter for the recommenders resource.
  - name: name
    value: "{{ name }}"
    description: |
      The name of the recommender.
  - name: datasetGroupArn
    value: "{{ datasetGroupArn }}"
    description: |
      The Amazon Resource Name (ARN) of the destination domain dataset group for the recommender.
  - name: recipeArn
    value: "{{ recipeArn }}"
    description: |
      The Amazon Resource Name (ARN) of the recipe that the recommender will use. For a recommender, a recipe is a Domain dataset group use case. Only Domain dataset group use cases can be used to create a recommender. For information about use cases see Choosing recommender use cases.
  - name: recommenderConfig
    description: |
      The configuration details of the recommender.
    value:
      itemExplorationConfig: "{{ itemExplorationConfig }}"
      minRecommendationRequestsPerSecond: {{ minRecommendationRequestsPerSecond }}
      trainingDataConfig:
        excludedDatasetColumns: "{{ excludedDatasetColumns }}"
        includedDatasetColumns: "{{ includedDatasetColumns }}"
      enableMetadataWithRecommendations: {{ enableMetadataWithRecommendations }}
  - name: tags
    description: |
      A list of tags to apply to the recommender.
    value:
      - tagKey: "{{ tagKey }}"
        tagValue: "{{ tagValue }}"

UPDATE examples

update_recommender

Updates the recommender to modify the recommender configuration. If you update the recommender to modify the columns used in training, Amazon Personalize automatically starts a full retraining of the models backing your recommender. While the update completes, you can still get recommendations from the recommender. The recommender uses the previous configuration until the update completes. To track the status of this update, use the latestRecommenderUpdate returned in the DescribeRecommender operation.

UPDATE aws.personalize.recommenders
SET 
recommenderArn = '{{ recommenderArn }}',
recommenderConfig = '{{ recommenderConfig }}'
WHERE 
region = '{{ region }}' --required
AND recommenderArn = '{{ recommenderArn }}' --required
AND recommenderConfig = '{{ recommenderConfig }}' --required
RETURNING
recommender_arn;

DELETE examples

delete_recommender

Deactivates and removes a recommender. A deleted recommender can no longer be specified in a GetRecommendations request.

DELETE FROM aws.personalize.recommenders
WHERE region = '{{ region }}' --required
;

Lifecycle Methods

start_recommender

Starts a recommender that is INACTIVE. Starting a recommender does not create any new models, but resumes billing and automatic retraining for the recommender.

EXEC aws.personalize.recommenders.start_recommender 
@region='{{ region }}' --required 
@@json=
'{
"recommenderArn": "{{ recommenderArn }}"
}'
;

stop_recommender

Stops a recommender that is ACTIVE. Stopping a recommender halts billing and automatic retraining for the recommender.

EXEC aws.personalize.recommenders.stop_recommender 
@region='{{ region }}' --required 
@@json=
'{
"recommenderArn": "{{ recommenderArn }}"
}'
;