AWS Tools for Windows PowerShell
Command Reference

AWS services or capabilities described in AWS Documentation may vary by region/location. Click Getting Started with Amazon AWS to see specific differences applicable to the China (Beijing) Region.

Synopsis

Calls the Amazon Kendra Query API operation.

Syntax

Invoke-KNDRQuery
-QueryText <String>
-AttributeFilter <AttributeFilter>
-UserContext_DataSourceGroup <DataSourceGroup[]>
-CollapseConfiguration_DocumentAttributeKey <String>
-SortingConfiguration_DocumentAttributeKey <String>
-DocumentRelevanceOverrideConfiguration <DocumentRelevanceConfiguration[]>
-CollapseConfiguration_Expand <Boolean>
-Facet <Facet[]>
-UserContext_Group <String[]>
-SpellCorrectionConfiguration_IncludeQuerySpellCheckSuggestion <Boolean>
-IndexId <String>
-ExpandConfiguration_MaxExpandedResultsPerItem <Int32>
-ExpandConfiguration_MaxResultItemsToExpand <Int32>
-CollapseConfiguration_MissingAttributeKeyStrategy <MissingAttributeKeyStrategy>
-PageNumber <Int32>
-QueryResultTypeFilter <QueryResultType>
-RequestedDocumentAttribute <String[]>
-CollapseConfiguration_SortingConfiguration <SortingConfiguration[]>
-SortingConfiguration <SortingConfiguration[]>
-SortingConfiguration_SortOrder <SortOrder>
-UserContext_Token <String>
-UserContext_UserId <String>
-VisitorId <String>
-PageSize <Int32>
-Select <String>
-PassThru <SwitchParameter>
-Force <SwitchParameter>
-ClientConfig <AmazonKendraConfig>

Description

Searches an index given an input query. If you are working with large language models (LLMs) or implementing retrieval augmented generation (RAG) systems, you can use Amazon Kendra's Retrieve API, which can return longer semantically relevant passages. We recommend using the Retrieve API instead of filing a service limit increase to increase the Query API document excerpt length. You can configure boosting or relevance tuning at the query level to override boosting at the index level, filter based on document fields/attributes and faceted search, and filter based on the user or their group access to documents. You can also include certain fields in the response that might provide useful additional information. A query response contains three types of results.
  • Relevant suggested answers. The answers can be either a text excerpt or table excerpt. The answer can be highlighted in the excerpt.
  • Matching FAQs or questions-answer from your FAQ file.
  • Relevant documents. This result type includes an excerpt of the document with the document title. The searched terms can be highlighted in the excerpt.
You can specify that the query return only one type of result using the QueryResultTypeFilter parameter. Each query returns the 100 most relevant results. If you filter result type to only question-answers, a maximum of four results are returned. If you filter result type to only answers, a maximum of three results are returned.

Parameters

-AttributeFilter <AttributeFilter>
Filters search results by document fields/attributes. You can only provide one attribute filter; however, the AndAllFilters, NotFilter, and OrAllFilters parameters contain a list of other filters.The AttributeFilter parameter means you can create a set of filtering rules that a document must satisfy to be included in the query results.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-ClientConfig <AmazonKendraConfig>
Amazon.PowerShell.Cmdlets.KNDR.AmazonKendraClientCmdlet.ClientConfig
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-CollapseConfiguration_DocumentAttributeKey <String>
The document attribute used to group search results. You can use any attribute that has the Sortable flag set to true. You can also sort by any of the following built-in attributes:"_category","_created_at", "_last_updated_at", "_version", "_view_count".
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-CollapseConfiguration_Expand <Boolean>
Specifies whether to expand the collapsed results.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-CollapseConfiguration_MissingAttributeKeyStrategy <MissingAttributeKeyStrategy>
Specifies the behavior for documents without a value for the collapse attribute.Amazon Kendra offers three customization options:
  • Choose to COLLAPSE all documents with null or missing values in one group. This is the default configuration.
  • Choose to IGNORE documents with null or missing values. Ignored documents will not appear in query results.
  • Choose to EXPAND each document with a null or missing value into a group of its own.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-CollapseConfiguration_SortingConfiguration <SortingConfiguration[]>
A prioritized list of document attributes/fields that determine the primary document among those in a collapsed group.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesCollapseConfiguration_SortingConfigurations
-DocumentRelevanceOverrideConfiguration <DocumentRelevanceConfiguration[]>
Overrides relevance tuning configurations of fields/attributes set at the index level.If you use this API to override the relevance tuning configured at the index level, but there is no relevance tuning configured at the index level, then Amazon Kendra does not apply any relevance tuning.If there is relevance tuning configured for fields at the index level, and you use this API to override only some of these fields, then for the fields you did not override, the importance is set to 1.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesDocumentRelevanceOverrideConfigurations
-ExpandConfiguration_MaxExpandedResultsPerItem <Int32>
The number of expanded results to show per collapsed primary document. For instance, if you set this value to 3, then at most 3 results per collapsed group will be displayed.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesCollapseConfiguration_ExpandConfiguration_MaxExpandedResultsPerItem
-ExpandConfiguration_MaxResultItemsToExpand <Int32>
The number of collapsed search result groups to expand. If you set this value to 10, for example, only the first 10 out of 100 result groups will have expand functionality.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesCollapseConfiguration_ExpandConfiguration_MaxResultItemsToExpand
-Facet <Facet[]>
An array of documents fields/attributes for faceted search. Amazon Kendra returns a count for each field key specified. This helps your users narrow their search.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesFacets
-Force <SwitchParameter>
This parameter overrides confirmation prompts to force the cmdlet to continue its operation. This parameter should always be used with caution.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-IndexId <String>
The identifier of the index for the search.
Required?True
Position?Named
Accept pipeline input?True (ByPropertyName)
-PageNumber <Int32>
Query results are returned in pages the size of the PageSize parameter. By default, Amazon Kendra returns the first page of results. Use this parameter to get result pages after the first one.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-PageSize <Int32>
Sets the number of results that are returned in each page of results. The default page size is 10. The maximum number of results returned is 100. If you ask for more than 100 results, only 100 are returned.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-PassThru <SwitchParameter>
Changes the cmdlet behavior to return the value passed to the QueryText parameter. The -PassThru parameter is deprecated, use -Select '^QueryText' instead. This parameter will be removed in a future version.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-QueryResultTypeFilter <QueryResultType>
Sets the type of query result or response. Only results for the specified type are returned.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-QueryText <String>
The input query text for the search. Amazon Kendra truncates queries at 30 token words, which excludes punctuation and stop words. Truncation still applies if you use Boolean or more advanced, complex queries.
Required?False
Position?1
Accept pipeline input?True (ByValue, ByPropertyName)
-RequestedDocumentAttribute <String[]>
An array of document fields/attributes to include in the response. You can limit the response to include certain document fields. By default, all document attributes are included in the response.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesRequestedDocumentAttributes
-Select <String>
Use the -Select parameter to control the cmdlet output. The default value is '*'. Specifying -Select '*' will result in the cmdlet returning the whole service response (Amazon.Kendra.Model.QueryResponse). Specifying the name of a property of type Amazon.Kendra.Model.QueryResponse will result in that property being returned. Specifying -Select '^ParameterName' will result in the cmdlet returning the selected cmdlet parameter value.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-SortingConfiguration <SortingConfiguration[]>
Provides configuration information to determine how the results of a query are sorted.You can set upto 3 fields that Amazon Kendra should sort the results on, and specify whether the results should be sorted in ascending or descending order. The sort field quota can be increased.If you don't provide a sorting configuration, the results are sorted by the relevance that Amazon Kendra determines for the result. In the case of ties in sorting the results, the results are sorted by relevance.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesSortingConfigurations
-SortingConfiguration_DocumentAttributeKey <String>
The name of the document attribute used to sort the response. You can use any field that has the Sortable flag set to true.You can also sort by any of the following built-in attributes:
  • _category
  • _created_at
  • _last_updated_at
  • _version
  • _view_count
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-SortingConfiguration_SortOrder <SortOrder>
The order that the results should be returned in. In case of ties, the relevance assigned to the result by Amazon Kendra is used as the tie-breaker.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-SpellCorrectionConfiguration_IncludeQuerySpellCheckSuggestion <Boolean>
TRUE to suggest spell corrections for queries.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesSpellCorrectionConfiguration_IncludeQuerySpellCheckSuggestions
-UserContext_DataSourceGroup <DataSourceGroup[]>
The list of data source groups you want to filter search results based on groups' access to documents in that data source.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesUserContext_DataSourceGroups
-UserContext_Group <String[]>
The list of groups you want to filter search results based on the groups' access to documents.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesUserContext_Groups
-UserContext_Token <String>
The user context token for filtering search results for a user. It must be a JWT or a JSON token.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-UserContext_UserId <String>
The identifier of the user you want to filter search results based on their access to documents.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-VisitorId <String>
Provides an identifier for a specific user. The VisitorId should be a unique identifier, such as a GUID. Don't use personally identifiable information, such as the user's email address, as the VisitorId.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)

Common Credential and Region Parameters

-AccessKey <String>
The AWS access key for the user account. This can be a temporary access key if the corresponding session token is supplied to the -SessionToken parameter.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesAK
-Credential <AWSCredentials>
An AWSCredentials object instance containing access and secret key information, and optionally a token for session-based credentials.
Required?False
Position?Named
Accept pipeline input?True (ByValue, ByPropertyName)
-EndpointUrl <String>
The endpoint to make the call against.Note: This parameter is primarily for internal AWS use and is not required/should not be specified for normal usage. The cmdlets normally determine which endpoint to call based on the region specified to the -Region parameter or set as default in the shell (via Set-DefaultAWSRegion). Only specify this parameter if you must direct the call to a specific custom endpoint.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
-NetworkCredential <PSCredential>
Used with SAML-based authentication when ProfileName references a SAML role profile. Contains the network credentials to be supplied during authentication with the configured identity provider's endpoint. This parameter is not required if the user's default network identity can or should be used during authentication.
Required?False
Position?Named
Accept pipeline input?True (ByValue, ByPropertyName)
-ProfileLocation <String>
Used to specify the name and location of the ini-format credential file (shared with the AWS CLI and other AWS SDKs)If this optional parameter is omitted this cmdlet will search the encrypted credential file used by the AWS SDK for .NET and AWS Toolkit for Visual Studio first. If the profile is not found then the cmdlet will search in the ini-format credential file at the default location: (user's home directory)\.aws\credentials.If this parameter is specified then this cmdlet will only search the ini-format credential file at the location given.As the current folder can vary in a shell or during script execution it is advised that you use specify a fully qualified path instead of a relative path.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesAWSProfilesLocation, ProfilesLocation
-ProfileName <String>
The user-defined name of an AWS credentials or SAML-based role profile containing credential information. The profile is expected to be found in the secure credential file shared with the AWS SDK for .NET and AWS Toolkit for Visual Studio. You can also specify the name of a profile stored in the .ini-format credential file used with the AWS CLI and other AWS SDKs.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesStoredCredentials, AWSProfileName
-Region <Object>
The system name of an AWS region or an AWSRegion instance. This governs the endpoint that will be used when calling service operations. Note that the AWS resources referenced in a call are usually region-specific.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesRegionToCall
-SecretKey <String>
The AWS secret key for the user account. This can be a temporary secret key if the corresponding session token is supplied to the -SessionToken parameter.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesSK, SecretAccessKey
-SessionToken <String>
The session token if the access and secret keys are temporary session-based credentials.
Required?False
Position?Named
Accept pipeline input?True (ByPropertyName)
AliasesST

Outputs

Amazon.Kendra.Model.QueryResponse
This cmdlet returns an Amazon.Kendra.Model.QueryResponse object containing multiple properties. The object can also be referenced from properties attached to the cmdlet entry in the $AWSHistory stack.
AWS Tools for PowerShell User Guide

Supported Version

AWS Tools for PowerShell: 2.x.y.z