2021/05/27 - AWSKendraFrontendService - 9 new api methods
Changes Amazon Kendra now suggests popular queries in order to help guide query typing and help overall accuracy.
Updates the settings of query suggestions for an index.
Amazon Kendra supports partial updates, so you only need to provide the fields you want to update.
If an update is currently processing (i.e. 'happening'), you need to wait for the update to finish before making another update.
Updates to query suggestions settings might not take effect right away. The time for your updated settings to take effect depends on the updates made and the number of search queries in your index.
You can still enable/disable query suggestions at any time.
See also: AWS API Documentation
Request Syntax
client.update_query_suggestions_config(
IndexId='string',
Mode='ENABLED'|'LEARN_ONLY',
QueryLogLookBackWindowInDays=123,
IncludeQueriesWithoutUserInformation=True|False,
MinimumNumberOfQueryingUsers=123,
MinimumQueryCount=123
)
string
[REQUIRED]
The identifier of the index you want to update query suggestions settings for.
string
Set the mode to ENABLED or LEARN_ONLY.
By default, Amazon Kendra enables query suggestions. LEARN_ONLY mode allows you to turn off query suggestions. You can to update this at any time.
In LEARN_ONLY mode, Amazon Kendra continues to learn from new queries to keep suggestions up to date for when you are ready to switch to ENABLED mode again.
integer
How recent your queries are in your query log time window.
The time window is the number of days from current day to past days.
By default, Amazon Kendra sets this to 180.
boolean
TRUE to include queries without user information (i.e. all queries, irrespective of the user), otherwise FALSE to only include queries with user information.
If you pass user information to Amazon Kendra along with the queries, you can set this flag to FALSE and instruct Amazon Kendra to only consider queries with user information.
If you set to FALSE, Amazon Kendra only considers queries searched at least MinimumQueryCount times across MinimumNumberOfQueryingUsers unique users for suggestions.
If you set to TRUE, Amazon Kendra ignores all user information and learns from all queries.
integer
The minimum number of unique users who must search a query in order for the query to be eligible to suggest to your users.
Increasing this number might decrease the number of suggestions. However, this ensures a query is searched by many users and is truly popular to suggest to users.
How you tune this setting depends on your specific needs.
integer
The the minimum number of times a query must be searched in order to be eligible to suggest to your users.
Decreasing this number increases the number of suggestions. However, this affects the quality of suggestions as it sets a low bar for a query to be considered popular to suggest to users.
How you tune this setting depends on your specific needs.
None
Deletes a block list used for query suggestions for an index.
A deleted block list might not take effect right away. Amazon Kendra needs to refresh the entire suggestions list to add back the queries that were previously blocked.
See also: AWS API Documentation
Request Syntax
client.delete_query_suggestions_block_list(
IndexId='string',
Id='string'
)
string
[REQUIRED]
The identifier of the you want to delete a block list from.
string
[REQUIRED]
The unique identifier of the block list that needs to be deleted.
None
Describes the settings of query suggestions for an index.
This is used to check the current settings applied to query suggestions.
See also: AWS API Documentation
Request Syntax
client.describe_query_suggestions_config(
IndexId='string'
)
string
[REQUIRED]
The identifier of the index you want to describe query suggestions settings for.
dict
Response Syntax
{
'Mode': 'ENABLED'|'LEARN_ONLY',
'Status': 'ACTIVE'|'UPDATING',
'QueryLogLookBackWindowInDays': 123,
'IncludeQueriesWithoutUserInformation': True|False,
'MinimumNumberOfQueryingUsers': 123,
'MinimumQueryCount': 123,
'LastSuggestionsBuildTime': datetime(2015, 1, 1),
'LastClearTime': datetime(2015, 1, 1),
'TotalSuggestionsCount': 123
}
Response Structure
(dict) --
Mode (string) --
Shows whether query suggestions are currently in ENABLED mode or LEARN_ONLY mode.
By default, Amazon Kendra enables query suggestions. LEARN_ONLY turns off query suggestions for your users. You can change the mode using the UpdateQuerySuggestionsConfig operation.
Status (string) --
Shows whether the status of query suggestions settings is currently Active or Updating.
Active means the current settings apply and Updating means your changed settings are in the process of applying.
QueryLogLookBackWindowInDays (integer) --
Shows how recent your queries are in your query log time window (in days).
IncludeQueriesWithoutUserInformation (boolean) --
Shows whether Amazon Kendra uses all queries or only uses queries that include user information to generate query suggestions.
MinimumNumberOfQueryingUsers (integer) --
Shows the minimum number of unique users who must search a query in order for the query to be eligible to suggest to your users.
MinimumQueryCount (integer) --
Shows the minimum number of times a query must be searched in order for the query to be eligible to suggest to your users.
LastSuggestionsBuildTime (datetime) --
Shows the date-time query suggestions for an index was last updated.
LastClearTime (datetime) --
Shows the date-time query suggestions for an index was last cleared.
After you clear suggestions, Amazon Kendra learns new suggestions based on new queries added to the query log from the time you cleared suggestions. Amazon Kendra only considers re-occurences of a query from the time you cleared suggestions.
TotalSuggestionsCount (integer) --
Shows the current total count of query suggestions for an index.
This count can change when you update your query suggestions settings, if you filter out certain queries from suggestions using a block list, and as the query log accumulates more queries for Amazon Kendra to learn from.
Clears existing query suggestions from an index.
This deletes existing suggestions only, not the queries in the query log. After you clear suggestions, Amazon Kendra learns new suggestions based on new queries added to the query log from the time you cleared suggestions. If you do not see any new suggestions, then please allow Amazon Kendra to collect enough queries to learn new suggestions.
See also: AWS API Documentation
Request Syntax
client.clear_query_suggestions(
IndexId='string'
)
string
[REQUIRED]
The identifier of the index you want to clear query suggestions from.
None
Updates a block list used for query suggestions for an index.
Updates to a block list might not take effect right away. Amazon Kendra needs to refresh the entire suggestions list to apply any updates to the block list. Other changes not related to the block list apply immediately.
If a block list is updating, then you need to wait for the first update to finish before submitting another update.
Amazon Kendra supports partial updates, so you only need to provide the fields you want to update.
See also: AWS API Documentation
Request Syntax
client.update_query_suggestions_block_list(
IndexId='string',
Id='string',
Name='string',
Description='string',
SourceS3Path={
'Bucket': 'string',
'Key': 'string'
},
RoleArn='string'
)
string
[REQUIRED]
The identifier of the index for a block list.
string
[REQUIRED]
The unique identifier of a block list.
string
The name of a block list.
string
The description for a block list.
dict
The S3 path where your block list text file sits in S3.
If you update your block list and provide the same path to the block list text file in S3, then Amazon Kendra reloads the file to refresh the block list. Amazon Kendra does not automatically refresh your block list. You need to call the UpdateQuerySuggestionsBlockList API to refresh you block list.
If you update your block list, then Amazon Kendra asynchronously refreshes all query suggestions with the latest content in the S3 file. This means changes might not take effect immediately.
Bucket (string) -- [REQUIRED]
The name of the S3 bucket that contains the file.
Key (string) -- [REQUIRED]
The name of the file.
string
The IAM (Identity and Access Management) role used to access the block list text file in S3.
None
Describes a block list used for query suggestions for an index.
This is used to check the current settings that are applied to a block list.
See also: AWS API Documentation
Request Syntax
client.describe_query_suggestions_block_list(
IndexId='string',
Id='string'
)
string
[REQUIRED]
The identifier of the index for the block list.
string
[REQUIRED]
The unique identifier of the block list.
dict
Response Syntax
{
'IndexId': 'string',
'Id': 'string',
'Name': 'string',
'Description': 'string',
'Status': 'ACTIVE'|'CREATING'|'DELETING'|'UPDATING'|'ACTIVE_BUT_UPDATE_FAILED'|'FAILED',
'ErrorMessage': 'string',
'CreatedAt': datetime(2015, 1, 1),
'UpdatedAt': datetime(2015, 1, 1),
'SourceS3Path': {
'Bucket': 'string',
'Key': 'string'
},
'ItemCount': 123,
'FileSizeBytes': 123,
'RoleArn': 'string'
}
Response Structure
(dict) --
IndexId (string) --
Shows the identifier of the index for the block list.
Id (string) --
Shows the unique identifier of the block list.
Name (string) --
Shows the name of the block list.
Description (string) --
Shows the description for the block list.
Status (string) --
Shows whether the current status of the block list is ACTIVE or INACTIVE.
ErrorMessage (string) --
Shows the error message with details when there are issues in processing the block list.
CreatedAt (datetime) --
Shows the date-time a block list for query suggestions was last created.
UpdatedAt (datetime) --
Shows the date-time a block list for query suggestions was last updated.
SourceS3Path (dict) --
Shows the current S3 path to your block list text file in your S3 bucket.
Each block word or phrase should be on a separate line in a text file.
For information on the current quota limits for block lists, see Quotas for Amazon Kendra.
Bucket (string) --
The name of the S3 bucket that contains the file.
Key (string) --
The name of the file.
ItemCount (integer) --
Shows the current number of valid, non-empty words or phrases in the block list text file.
FileSizeBytes (integer) --
Shows the current size of the block list text file in S3.
RoleArn (string) --
Shows the current IAM (Identity and Access Management) role used by Amazon Kendra to access the block list text file in S3.
The role needs S3 read permissions to your file in S3 and needs to give STS (Security Token Service) assume role permissions to Amazon Kendra.
Lists the block lists used for query suggestions for an index.
For information on the current quota limits for block lists, see Quotas for Amazon Kendra.
See also: AWS API Documentation
Request Syntax
client.list_query_suggestions_block_lists(
IndexId='string',
NextToken='string',
MaxResults=123
)
string
[REQUIRED]
The identifier of the index for a list of all block lists that exist for that index.
For information on the current quota limits for block lists, see Quotas for Amazon Kendra.
string
If the previous response was incomplete (because there is more data to retrieve), Amazon Kendra returns a pagination token in the response. You can use this pagination token to retrieve the next set of block lists ( BlockListSummaryItems).
integer
The maximum number of block lists to return.
dict
Response Syntax
{
'BlockListSummaryItems': [
{
'Id': 'string',
'Name': 'string',
'Status': 'ACTIVE'|'CREATING'|'DELETING'|'UPDATING'|'ACTIVE_BUT_UPDATE_FAILED'|'FAILED',
'CreatedAt': datetime(2015, 1, 1),
'UpdatedAt': datetime(2015, 1, 1),
'ItemCount': 123
},
],
'NextToken': 'string'
}
Response Structure
(dict) --
BlockListSummaryItems (list) --
Summary items for a block list.
This includes summary items on the block list ID, block list name, when the block list was created, when the block list was last updated, and the count of block words/phrases in the block list.
For information on the current quota limits for block lists, see Quotas for Amazon Kendra.
(dict) --
Summary information on a query suggestions block list.
This includes information on the block list ID, block list name, when the block list was created, when the block list was last updated, and the count of block words/phrases in the block list.
For information on the current quota limits for block lists, see Quotas for Amazon Kendra.
Id (string) --
The identifier of a block list.
Name (string) --
The name of the block list.
Status (string) --
The status of the block list.
CreatedAt (datetime) --
The date-time summary information for a query suggestions block list was last created.
UpdatedAt (datetime) --
The date-time the block list was last updated.
ItemCount (integer) --
The number of items in the block list file.
NextToken (string) --
If the response is truncated, Amazon Kendra returns this token that you can use in the subsequent request to retrieve the next set of block lists.
Fetches the queries that are suggested to your users.
See also: AWS API Documentation
Request Syntax
client.get_query_suggestions(
IndexId='string',
QueryText='string',
MaxSuggestionsCount=123
)
string
[REQUIRED]
The identifier of the index you want to get query suggestions from.
string
[REQUIRED]
The text of a user's query to generate query suggestions.
A query is suggested if the query prefix matches what a user starts to type as their query.
Amazon Kendra does not show any suggestions if a user types fewer than two characters or more than 60 characters. A query must also have at least one search result and contain at least one word of more than four characters.
integer
The maximum number of query suggestions you want to show to your users.
dict
Response Syntax
{
'QuerySuggestionsId': 'string',
'Suggestions': [
{
'Id': 'string',
'Value': {
'Text': {
'Text': 'string',
'Highlights': [
{
'BeginOffset': 123,
'EndOffset': 123
},
]
}
}
},
]
}
Response Structure
(dict) --
QuerySuggestionsId (string) --
The unique identifier for a list of query suggestions for an index.
Suggestions (list) --
A list of query suggestions for an index.
(dict) --
A single query suggestion.
Id (string) --
The unique UUID (universally unique identifier) of a single query suggestion.
Value (dict) --
The value for the unique UUID (universally unique identifier) of a single query suggestion.
The value is the text string of a suggestion.
Text (dict) --
The SuggestionTextWithHighlights structure that contains the query suggestion text and highlights.
Text (string) --
The query suggestion text to display to the user.
Highlights (list) --
The beginning and end of the query suggestion text that should be highlighted.
(dict) --
The text highlights for a single query suggestion.
BeginOffset (integer) --
The zero-based location in the response string where the highlight starts.
EndOffset (integer) --
The zero-based location in the response string where the highlight ends.
Creates a block list to exlcude certain queries from suggestions.
Any query that contains words or phrases specified in the block list is blocked or filtered out from being shown as a suggestion.
You need to provide the file location of your block list text file in your S3 bucket. In your text file, enter each block word or phrase on a separate line.
For information on the current quota limits for block lists, see Quotas for Amazon Kendra.
See also: AWS API Documentation
Request Syntax
client.create_query_suggestions_block_list(
IndexId='string',
Name='string',
Description='string',
SourceS3Path={
'Bucket': 'string',
'Key': 'string'
},
ClientToken='string',
RoleArn='string',
Tags=[
{
'Key': 'string',
'Value': 'string'
},
]
)
string
[REQUIRED]
The identifier of the index you want to create a query suggestions block list for.
string
[REQUIRED]
A user friendly name for the block list.
For example, the block list named 'offensive-words' includes all offensive words that could appear in user queries and need to be blocked from suggestions.
string
A user-friendly description for the block list.
For example, the description "List of all offensive words that can appear in user queries and need to be blocked from suggestions."
dict
[REQUIRED]
The S3 path to your block list text file in your S3 bucket.
Each block word or phrase should be on a separate line in a text file.
For information on the current quota limits for block lists, see Quotas for Amazon Kendra.
Bucket (string) -- [REQUIRED]
The name of the S3 bucket that contains the file.
Key (string) -- [REQUIRED]
The name of the file.
string
A token that you provide to identify the request to create a query suggestions block list.
This field is autopopulated if not provided.
string
[REQUIRED]
The IAM (Identity and Access Management) role used by Amazon Kendra to access the block list text file in your S3 bucket.
You need permissions to the role ARN (Amazon Resource Name). The role needs S3 read permissions to your file in S3 and needs to give STS (Security Token Service) assume role permissions to Amazon Kendra.
list
A tag that you can assign to a block list that categorizes the block list.
(dict) --
A list of key/value pairs that identify an index, FAQ, or data source. Tag keys and values can consist of Unicode letters, digits, white space, and any of the following symbols: _ . : / = + - @.
Key (string) -- [REQUIRED]
The key for the tag. Keys are not case sensitive and must be unique for the index, FAQ, or data source.
Value (string) -- [REQUIRED]
The value associated with the tag. The value may be an empty string but it can't be null.
dict
Response Syntax
{
'Id': 'string'
}
Response Structure
(dict) --
Id (string) --
The unique identifier of the created block list.