Amazon Kendra Intelligent Ranking 2022-10-19
- Client: Aws\KendraRanking\KendraRankingClient
- Service ID: kendra-ranking
- Version: 2022-10-19
This page describes the parameters and results for the operations of the Amazon Kendra Intelligent Ranking (2022-10-19), and shows how to use the Aws\KendraRanking\KendraRankingClient object to call the described operations. This documentation is specific to the 2022-10-19 API version of the service.
Operation Summary
Each of the following operations can be created from a client using
$client->getCommand('CommandName')
, where "CommandName" is the
name of one of the following operations. Note: a command is a value that
encapsulates an operation and the parameters used to create an HTTP request.
You can also create and send a command immediately using the magic methods
available on a client object: $client->commandName(/* parameters */)
.
You can send the command asynchronously (returning a promise) by appending the
word "Async" to the operation name: $client->commandNameAsync(/* parameters */)
.
- CreateRescoreExecutionPlan ( array $params = [] )
- Creates a rescore execution plan.
- DeleteRescoreExecutionPlan ( array $params = [] )
- Deletes a rescore execution plan.
- DescribeRescoreExecutionPlan ( array $params = [] )
- Gets information about a rescore execution plan.
- ListRescoreExecutionPlans ( array $params = [] )
- Lists your rescore execution plans.
- ListTagsForResource ( array $params = [] )
- Gets a list of tags associated with a specified resource.
- Rescore ( array $params = [] )
- Rescores or re-ranks search results from a search service such as OpenSearch (self managed).
- TagResource ( array $params = [] )
- Adds a specified tag to a specified rescore execution plan.
- UntagResource ( array $params = [] )
- Removes a tag from a rescore execution plan.
- UpdateRescoreExecutionPlan ( array $params = [] )
- Updates a rescore execution plan.
Paginators
Paginators handle automatically iterating over paginated API results. Paginators are associated with specific API operations, and they accept the parameters that the corresponding API operation accepts. You can get a paginator from a client class using getPaginator($paginatorName, $operationParameters). This client supports the following paginators:
Operations
CreateRescoreExecutionPlan
$result = $client->createRescoreExecutionPlan
([/* ... */]); $promise = $client->createRescoreExecutionPlanAsync
([/* ... */]);
Creates a rescore execution plan. A rescore execution plan is an Amazon Kendra Intelligent Ranking resource used for provisioning the Rescore
API. You set the number of capacity units that you require for Amazon Kendra Intelligent Ranking to rescore or re-rank a search service's results.
For an example of using the CreateRescoreExecutionPlan
API, including using the Python and Java SDKs, see Semantically ranking a search service's results.
Parameter Syntax
$result = $client->createRescoreExecutionPlan([ 'CapacityUnits' => [ 'RescoreCapacityUnits' => <integer>, // REQUIRED ], 'ClientToken' => '<string>', 'Description' => '<string>', 'Name' => '<string>', // REQUIRED 'Tags' => [ [ 'Key' => '<string>', // REQUIRED 'Value' => '<string>', // REQUIRED ], // ... ], ]);
Parameter Details
Members
- CapacityUnits
-
- Type: CapacityUnitsConfiguration structure
You can set additional capacity units to meet the needs of your rescore execution plan. You are given a single capacity unit by default. If you want to use the default capacity, you don't set additional capacity units. For more information on the default capacity and additional capacity units, see Adjusting capacity.
- ClientToken
-
- Type: string
A token that you provide to identify the request to create a rescore execution plan. Multiple calls to the
CreateRescoreExecutionPlanRequest
API with the same client token will create only one rescore execution plan. - Description
-
- Type: string
A description for the rescore execution plan.
- Name
-
- Required: Yes
- Type: string
A name for the rescore execution plan.
- Tags
-
- Type: Array of Tag structures
A list of key-value pairs that identify or categorize your rescore execution plan. You can also use tags to help control access to the rescore execution plan. Tag keys and values can consist of Unicode letters, digits, white space, and any of the following symbols: _ . : / = + - @.
Result Syntax
[ 'Arn' => '<string>', 'Id' => '<string>', ]
Result Details
Members
- Arn
-
- Required: Yes
- Type: string
The Amazon Resource Name (ARN) of the rescore execution plan.
- Id
-
- Required: Yes
- Type: string
The identifier of the rescore execution plan.
Errors
- AccessDeniedException:
You don’t have sufficient access to perform this action. Please ensure you have the required permission policies and user accounts and try again.
- ConflictException:
A conflict occurred with the request. Please fix any inconsistencies with your resources and try again.
- ServiceQuotaExceededException:
You have exceeded the set limits for your Amazon Kendra Intelligent Ranking service. Please see Quotas for more information, or contact Support to inquire about an increase of limits.
- ThrottlingException:
The request was denied due to request throttling. Please reduce the number of requests and try again.
- ValidationException:
The input fails to satisfy the constraints set by the Amazon Kendra Intelligent Ranking service. Please provide the correct input and try again.
- InternalServerException:
An issue occurred with the internal server used for your Amazon Kendra Intelligent Ranking service. Please wait a few minutes and try again, or contact Support for help.
DeleteRescoreExecutionPlan
$result = $client->deleteRescoreExecutionPlan
([/* ... */]); $promise = $client->deleteRescoreExecutionPlanAsync
([/* ... */]);
Deletes a rescore execution plan. A rescore execution plan is an Amazon Kendra Intelligent Ranking resource used for provisioning the Rescore
API.
Parameter Syntax
$result = $client->deleteRescoreExecutionPlan([ 'Id' => '<string>', // REQUIRED ]);
Parameter Details
Members
- Id
-
- Required: Yes
- Type: string
The identifier of the rescore execution plan that you want to delete.
Result Syntax
[]
Result Details
Errors
- AccessDeniedException:
You don’t have sufficient access to perform this action. Please ensure you have the required permission policies and user accounts and try again.
- ValidationException:
The input fails to satisfy the constraints set by the Amazon Kendra Intelligent Ranking service. Please provide the correct input and try again.
- ConflictException:
A conflict occurred with the request. Please fix any inconsistencies with your resources and try again.
- ResourceNotFoundException:
The resource you want to use doesn't exist. Please check you have provided the correct resource and try again.
- ThrottlingException:
The request was denied due to request throttling. Please reduce the number of requests and try again.
- InternalServerException:
An issue occurred with the internal server used for your Amazon Kendra Intelligent Ranking service. Please wait a few minutes and try again, or contact Support for help.
DescribeRescoreExecutionPlan
$result = $client->describeRescoreExecutionPlan
([/* ... */]); $promise = $client->describeRescoreExecutionPlanAsync
([/* ... */]);
Gets information about a rescore execution plan. A rescore execution plan is an Amazon Kendra Intelligent Ranking resource used for provisioning the Rescore
API.
Parameter Syntax
$result = $client->describeRescoreExecutionPlan([ 'Id' => '<string>', // REQUIRED ]);
Parameter Details
Members
- Id
-
- Required: Yes
- Type: string
The identifier of the rescore execution plan that you want to get information on.
Result Syntax
[ 'Arn' => '<string>', 'CapacityUnits' => [ 'RescoreCapacityUnits' => <integer>, ], 'CreatedAt' => <DateTime>, 'Description' => '<string>', 'ErrorMessage' => '<string>', 'Id' => '<string>', 'Name' => '<string>', 'Status' => 'CREATING|UPDATING|ACTIVE|DELETING|FAILED', 'UpdatedAt' => <DateTime>, ]
Result Details
Members
- Arn
-
- Type: string
The Amazon Resource Name (ARN) of the rescore execution plan.
- CapacityUnits
-
- Type: CapacityUnitsConfiguration structure
The capacity units set for the rescore execution plan. A capacity of zero indicates that the rescore execution plan is using the default capacity. For more information on the default capacity and additional capacity units, see Adjusting capacity.
- CreatedAt
-
- Type: timestamp (string|DateTime or anything parsable by strtotime)
The Unix timestamp of when the rescore execution plan was created.
- Description
-
- Type: string
The description for the rescore execution plan.
- ErrorMessage
-
- Type: string
When the
Status
field value isFAILED
, theErrorMessage
field contains a message that explains why. - Id
-
- Type: string
The identifier of the rescore execution plan.
- Name
-
- Type: string
The name for the rescore execution plan.
- Status
-
- Type: string
The current status of the rescore execution plan. When the value is
ACTIVE
, the rescore execution plan is ready for use. If theStatus
field value isFAILED
, theErrorMessage
field contains a message that explains why. - UpdatedAt
-
- Type: timestamp (string|DateTime or anything parsable by strtotime)
The Unix timestamp of when the rescore execution plan was last updated.
Errors
- ValidationException:
The input fails to satisfy the constraints set by the Amazon Kendra Intelligent Ranking service. Please provide the correct input and try again.
- ResourceNotFoundException:
The resource you want to use doesn't exist. Please check you have provided the correct resource and try again.
- ThrottlingException:
The request was denied due to request throttling. Please reduce the number of requests and try again.
- AccessDeniedException:
You don’t have sufficient access to perform this action. Please ensure you have the required permission policies and user accounts and try again.
- InternalServerException:
An issue occurred with the internal server used for your Amazon Kendra Intelligent Ranking service. Please wait a few minutes and try again, or contact Support for help.
ListRescoreExecutionPlans
$result = $client->listRescoreExecutionPlans
([/* ... */]); $promise = $client->listRescoreExecutionPlansAsync
([/* ... */]);
Lists your rescore execution plans. A rescore execution plan is an Amazon Kendra Intelligent Ranking resource used for provisioning the Rescore
API.
Parameter Syntax
$result = $client->listRescoreExecutionPlans([ 'MaxResults' => <integer>, 'NextToken' => '<string>', ]);
Parameter Details
Members
- MaxResults
-
- Type: int
The maximum number of rescore execution plans to return.
- NextToken
-
- Type: string
If the response is truncated, Amazon Kendra Intelligent Ranking returns a pagination token in the response. You can use this pagination token to retrieve the next set of rescore execution plans.
Result Syntax
[ 'NextToken' => '<string>', 'SummaryItems' => [ [ 'CreatedAt' => <DateTime>, 'Id' => '<string>', 'Name' => '<string>', 'Status' => 'CREATING|UPDATING|ACTIVE|DELETING|FAILED', 'UpdatedAt' => <DateTime>, ], // ... ], ]
Result Details
Members
- NextToken
-
- Type: string
If the response is truncated, Amazon Kendra Intelligent Ranking returns a pagination token in the response.
- SummaryItems
-
- Type: Array of RescoreExecutionPlanSummary structures
An array of summary information for one or more rescore execution plans.
Errors
- ValidationException:
The input fails to satisfy the constraints set by the Amazon Kendra Intelligent Ranking service. Please provide the correct input and try again.
- AccessDeniedException:
You don’t have sufficient access to perform this action. Please ensure you have the required permission policies and user accounts and try again.
- ThrottlingException:
The request was denied due to request throttling. Please reduce the number of requests and try again.
- InternalServerException:
An issue occurred with the internal server used for your Amazon Kendra Intelligent Ranking service. Please wait a few minutes and try again, or contact Support for help.
ListTagsForResource
$result = $client->listTagsForResource
([/* ... */]); $promise = $client->listTagsForResourceAsync
([/* ... */]);
Gets a list of tags associated with a specified resource. A rescore execution plan is an example of a resource that can have tags associated with it.
Parameter Syntax
$result = $client->listTagsForResource([ 'ResourceARN' => '<string>', // REQUIRED ]);
Parameter Details
Members
- ResourceARN
-
- Required: Yes
- Type: string
The Amazon Resource Name (ARN) of the rescore execution plan to get a list of tags for.
Result Syntax
[ 'Tags' => [ [ 'Key' => '<string>', 'Value' => '<string>', ], // ... ], ]
Result Details
Members
- Tags
-
- Type: Array of Tag structures
A list of tags associated with the rescore execution plan.
Errors
- ValidationException:
The input fails to satisfy the constraints set by the Amazon Kendra Intelligent Ranking service. Please provide the correct input and try again.
- ResourceUnavailableException:
The resource you want to use is unavailable. Please check you have provided the correct resource information and try again.
- ThrottlingException:
The request was denied due to request throttling. Please reduce the number of requests and try again.
- AccessDeniedException:
You don’t have sufficient access to perform this action. Please ensure you have the required permission policies and user accounts and try again.
- InternalServerException:
An issue occurred with the internal server used for your Amazon Kendra Intelligent Ranking service. Please wait a few minutes and try again, or contact Support for help.
Rescore
$result = $client->rescore
([/* ... */]); $promise = $client->rescoreAsync
([/* ... */]);
Rescores or re-ranks search results from a search service such as OpenSearch (self managed). You use the semantic search capabilities of Amazon Kendra Intelligent Ranking to improve the search service's results.
Parameter Syntax
$result = $client->rescore([ 'Documents' => [ // REQUIRED [ 'Body' => '<string>', 'GroupId' => '<string>', 'Id' => '<string>', // REQUIRED 'OriginalScore' => <float>, // REQUIRED 'Title' => '<string>', 'TokenizedBody' => ['<string>', ...], 'TokenizedTitle' => ['<string>', ...], ], // ... ], 'RescoreExecutionPlanId' => '<string>', // REQUIRED 'SearchQuery' => '<string>', // REQUIRED ]);
Parameter Details
Members
- Documents
-
- Required: Yes
- Type: Array of Document structures
The list of documents for Amazon Kendra Intelligent Ranking to rescore or rank on.
- RescoreExecutionPlanId
-
- Required: Yes
- Type: string
The identifier of the rescore execution plan. A rescore execution plan is an Amazon Kendra Intelligent Ranking resource used for provisioning the
Rescore
API. - SearchQuery
-
- Required: Yes
- Type: string
The input query from the search service.
Result Syntax
[ 'RescoreId' => '<string>', 'ResultItems' => [ [ 'DocumentId' => '<string>', 'Score' => <float>, ], // ... ], ]
Result Details
Members
- RescoreId
-
- Type: string
The identifier associated with the scores that Amazon Kendra Intelligent Ranking gives to the results. Amazon Kendra Intelligent Ranking rescores or re-ranks the results for the search service.
- ResultItems
-
- Type: Array of RescoreResultItem structures
A list of result items for documents with new relevancy scores. The results are in descending order.
Errors
- ValidationException:
The input fails to satisfy the constraints set by the Amazon Kendra Intelligent Ranking service. Please provide the correct input and try again.
- ConflictException:
A conflict occurred with the request. Please fix any inconsistencies with your resources and try again.
- AccessDeniedException:
You don’t have sufficient access to perform this action. Please ensure you have the required permission policies and user accounts and try again.
- ResourceNotFoundException:
The resource you want to use doesn't exist. Please check you have provided the correct resource and try again.
- ThrottlingException:
The request was denied due to request throttling. Please reduce the number of requests and try again.
- InternalServerException:
An issue occurred with the internal server used for your Amazon Kendra Intelligent Ranking service. Please wait a few minutes and try again, or contact Support for help.
TagResource
$result = $client->tagResource
([/* ... */]); $promise = $client->tagResourceAsync
([/* ... */]);
Adds a specified tag to a specified rescore execution plan. A rescore execution plan is an Amazon Kendra Intelligent Ranking resource used for provisioning the Rescore
API. If the tag already exists, the existing value is replaced with the new value.
Parameter Syntax
$result = $client->tagResource([ 'ResourceARN' => '<string>', // REQUIRED 'Tags' => [ // REQUIRED [ 'Key' => '<string>', // REQUIRED 'Value' => '<string>', // REQUIRED ], // ... ], ]);
Parameter Details
Members
- ResourceARN
-
- Required: Yes
- Type: string
The Amazon Resource Name (ARN) of the rescore execution plan to tag.
- Tags
-
- Required: Yes
- Type: Array of Tag structures
A list of tag keys to add to a rescore execution plan. If a tag already exists, the existing value is replaced with the new value.
Result Syntax
[]
Result Details
Errors
- ValidationException:
The input fails to satisfy the constraints set by the Amazon Kendra Intelligent Ranking service. Please provide the correct input and try again.
- ResourceUnavailableException:
The resource you want to use is unavailable. Please check you have provided the correct resource information and try again.
- ThrottlingException:
The request was denied due to request throttling. Please reduce the number of requests and try again.
- AccessDeniedException:
You don’t have sufficient access to perform this action. Please ensure you have the required permission policies and user accounts and try again.
- InternalServerException:
An issue occurred with the internal server used for your Amazon Kendra Intelligent Ranking service. Please wait a few minutes and try again, or contact Support for help.
UntagResource
$result = $client->untagResource
([/* ... */]); $promise = $client->untagResourceAsync
([/* ... */]);
Removes a tag from a rescore execution plan. A rescore execution plan is an Amazon Kendra Intelligent Ranking resource used for provisioning the Rescore
operation.
Parameter Syntax
$result = $client->untagResource([ 'ResourceARN' => '<string>', // REQUIRED 'TagKeys' => ['<string>', ...], // REQUIRED ]);
Parameter Details
Members
- ResourceARN
-
- Required: Yes
- Type: string
The Amazon Resource Name (ARN) of the rescore execution plan to remove the tag.
- TagKeys
-
- Required: Yes
- Type: Array of strings
A list of tag keys to remove from the rescore execution plan. If a tag key does not exist on the resource, it is ignored.
Result Syntax
[]
Result Details
Errors
- ValidationException:
The input fails to satisfy the constraints set by the Amazon Kendra Intelligent Ranking service. Please provide the correct input and try again.
- ResourceUnavailableException:
The resource you want to use is unavailable. Please check you have provided the correct resource information and try again.
- ThrottlingException:
The request was denied due to request throttling. Please reduce the number of requests and try again.
- AccessDeniedException:
You don’t have sufficient access to perform this action. Please ensure you have the required permission policies and user accounts and try again.
- InternalServerException:
An issue occurred with the internal server used for your Amazon Kendra Intelligent Ranking service. Please wait a few minutes and try again, or contact Support for help.
UpdateRescoreExecutionPlan
$result = $client->updateRescoreExecutionPlan
([/* ... */]); $promise = $client->updateRescoreExecutionPlanAsync
([/* ... */]);
Updates a rescore execution plan. A rescore execution plan is an Amazon Kendra Intelligent Ranking resource used for provisioning the Rescore
API. You can update the number of capacity units you require for Amazon Kendra Intelligent Ranking to rescore or re-rank a search service's results.
Parameter Syntax
$result = $client->updateRescoreExecutionPlan([ 'CapacityUnits' => [ 'RescoreCapacityUnits' => <integer>, // REQUIRED ], 'Description' => '<string>', 'Id' => '<string>', // REQUIRED 'Name' => '<string>', ]);
Parameter Details
Members
- CapacityUnits
-
- Type: CapacityUnitsConfiguration structure
You can set additional capacity units to meet the needs of your rescore execution plan. You are given a single capacity unit by default. If you want to use the default capacity, you don't set additional capacity units. For more information on the default capacity and additional capacity units, see Adjusting capacity.
- Description
-
- Type: string
A new description for the rescore execution plan.
- Id
-
- Required: Yes
- Type: string
The identifier of the rescore execution plan that you want to update.
- Name
-
- Type: string
A new name for the rescore execution plan.
Result Syntax
[]
Result Details
Errors
- ValidationException:
The input fails to satisfy the constraints set by the Amazon Kendra Intelligent Ranking service. Please provide the correct input and try again.
- ResourceNotFoundException:
The resource you want to use doesn't exist. Please check you have provided the correct resource and try again.
- ThrottlingException:
The request was denied due to request throttling. Please reduce the number of requests and try again.
- AccessDeniedException:
You don’t have sufficient access to perform this action. Please ensure you have the required permission policies and user accounts and try again.
- ServiceQuotaExceededException:
You have exceeded the set limits for your Amazon Kendra Intelligent Ranking service. Please see Quotas for more information, or contact Support to inquire about an increase of limits.
- ConflictException:
A conflict occurred with the request. Please fix any inconsistencies with your resources and try again.
- InternalServerException:
An issue occurred with the internal server used for your Amazon Kendra Intelligent Ranking service. Please wait a few minutes and try again, or contact Support for help.
Shapes
AccessDeniedException
Description
You don’t have sufficient access to perform this action. Please ensure you have the required permission policies and user accounts and try again.
Members
- Message
-
- Type: string
CapacityUnitsConfiguration
Description
Sets additional capacity units configured for your rescore execution plan. A rescore execution plan is an Amazon Kendra Intelligent Ranking resource used for provisioning the Rescore
API. You can add and remove capacity units to fit your usage requirements.
Members
- RescoreCapacityUnits
-
- Required: Yes
- Type: int
The amount of extra capacity for your rescore execution plan.
A single extra capacity unit for a rescore execution plan provides 0.01 rescore requests per second. You can add up to 1000 extra capacity units.
ConflictException
Description
A conflict occurred with the request. Please fix any inconsistencies with your resources and try again.
Members
- Message
-
- Type: string
Document
Description
Information about a document from a search service such as OpenSearch (self managed). Amazon Kendra Intelligent Ranking uses this information to rank and score on.
Members
- Body
-
- Type: string
The body text of the search service's document.
- GroupId
-
- Type: string
The optional group identifier of the document from the search service. Documents with the same group identifier are grouped together and processed as one document within the service.
- Id
-
- Required: Yes
- Type: string
The identifier of the document from the search service.
- OriginalScore
-
- Required: Yes
- Type: float
The original document score or rank from the search service. Amazon Kendra Intelligent Ranking gives the document a new score or rank based on its intelligent search algorithms.
- Title
-
- Type: string
The title of the search service's document.
- TokenizedBody
-
- Type: Array of strings
The body text of the search service's document represented as a list of tokens or words. You must choose to provide
Body
orTokenizedBody
. You cannot provide both. - TokenizedTitle
-
- Type: Array of strings
The title of the search service's document represented as a list of tokens or words. You must choose to provide
Title
orTokenizedTitle
. You cannot provide both.
InternalServerException
Description
An issue occurred with the internal server used for your Amazon Kendra Intelligent Ranking service. Please wait a few minutes and try again, or contact Support for help.
Members
- Message
-
- Type: string
RescoreExecutionPlanSummary
Description
Summary information for a rescore execution plan. A rescore execution plan is an Amazon Kendra Intelligent Ranking resource used for provisioning the Rescore
API.
Members
- CreatedAt
-
- Type: timestamp (string|DateTime or anything parsable by strtotime)
The Unix timestamp when the rescore execution plan was created.
- Id
-
- Type: string
The identifier of the rescore execution plan.
- Name
-
- Type: string
The name of the rescore execution plan.
- Status
-
- Type: string
The current status of the rescore execution plan. When the value is
ACTIVE
, the rescore execution plan is ready for use. - UpdatedAt
-
- Type: timestamp (string|DateTime or anything parsable by strtotime)
The Unix timestamp when the rescore execution plan was last updated.
RescoreResultItem
Description
A result item for a document with a new relevancy score.
Members
- DocumentId
-
- Type: string
The identifier of the document from the search service.
- Score
-
- Type: float
The relevancy score or rank that Amazon Kendra Intelligent Ranking gives to the result.
ResourceNotFoundException
Description
The resource you want to use doesn't exist. Please check you have provided the correct resource and try again.
Members
- Message
-
- Type: string
ResourceUnavailableException
Description
The resource you want to use is unavailable. Please check you have provided the correct resource information and try again.
Members
- Message
-
- Type: string
ServiceQuotaExceededException
Tag
Description
A key-value pair that identifies or categorizes a rescore execution plan. A rescore execution plan is an Amazon Kendra Intelligent Ranking resource used for provisioning the Rescore
API. You can also use a tag to help control access to a rescore execution plan. A tag key and value can consist of Unicode letters, digits, white space, and any of the following symbols: _ . : / = + - @.
Members
- Key
-
- Required: Yes
- Type: string
The key for the tag. Keys are not case sensitive and must be unique.
- Value
-
- Required: Yes
- Type: string
The value associated with the tag. The value can be an empty string but it can't be null.
ThrottlingException
Description
The request was denied due to request throttling. Please reduce the number of requests and try again.
Members
- Message
-
- Type: string
ValidationException
Description
The input fails to satisfy the constraints set by the Amazon Kendra Intelligent Ranking service. Please provide the correct input and try again.
Members
- Message
-
- Type: string