AWS bedrock documentation change
Summary
Added detailed documentation for the GenerateQuery API, including usage instructions, key considerations, and IAM policy examples for granting permissions
Security assessment
The change adds IAM policy examples for granting permissions to use GenerateQuery and related APIs. While this is security-related documentation about access control, there is no evidence it addresses a specific security vulnerability. The policy example includes a wildcard resource (*) for some actions, which could introduce risks if misconfigured, but this is a standard documentation example rather than a vulnerability fix.
Diff
diff --git a/bedrock/latest/userguide/knowledge-base-generate-query.md b/bedrock/latest/userguide/knowledge-base-generate-query.md index 8bdf5fec6..be438966b 100644 --- a//bedrock/latest/userguide/knowledge-base-generate-query.md +++ b//bedrock/latest/userguide/knowledge-base-generate-query.md @@ -4,0 +5,2 @@ +Using the GenerateQuery APIKey considerationsGrant a role permissions to access generated queries + @@ -18 +20,24 @@ When you connect a structured data store to your knowledge base, your knowledge -###### Important +## Using the `GenerateQuery` API + +You can use the response from the `GenerateQuery` API operation with a subsequent `Retrieve` or `RetrieveAndGenerate` action, or insert it into other workflows. `GenerateQuery` allows you to efficiently transform queries into SQL queries by taking into consideration the structure of your knowledge base's data source. + +To turn a natural language query into a SQL query, submit a [GenerateQuery](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_GenerateQuery.html) request with an [Agents for Amazon Bedrock runtime endpoint](https://docs.aws.amazon.com/general/latest/gr/bedrock.html#bra-rt). The `GenerateQuery` request contains the following fields: + + * queryGenerationInput – Specify `TEXT` as the `type` and include the query in the `text` field. + +###### Note + +Queries must be written in English. + + * transformationConfiguration – Specify `TEXT_TO_SQL` as the `mode`. In the `textToSqlConfiguration` field, specify `KNOWLEDGE_BASE` as the `type`. Then, specify the ARN of the knowledge base. + + + + +The response returns an array containing a [GeneratedQuery](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_GeneratedQuery.html) object in the `queries` field. The object contains an SQL query for the query in the `sql` field. + +## Key considerations + +The following are some key considerations when generating a query using structured data. + + * ###### Cross-region inference and structured data retrieval @@ -26,3 +51 @@ For more information, see [Increase throughput with cross-Region inference](./cr -You can use the response from the `GenerateQuery` API operation with a subsequent `Retrieve` or `RetrieveAndGenerate` action, or insert it into other workflows. `GenerateQuery` allows you to efficiently transform queries into SQL queries by taking into consideration the structure of your knowledge base's data source. - -###### Important + * ###### Accuracy of generated SQL queries @@ -32 +55 @@ The accuracy of a generated SQL query can vary depending on context, table schem -To turn a natural language query into a SQL query, submit a [GenerateQuery](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_GenerateQuery.html) request with an [Agents for Amazon Bedrock runtime endpoint](https://docs.aws.amazon.com/general/latest/gr/bedrock.html#bra-rt). The `GenerateQuery` request contains the following fields: + * ###### Number of retrieved results @@ -34 +57 @@ To turn a natural language query into a SQL query, submit a [GenerateQuery](http - * queryGenerationInput – Specify `TEXT` as the `type` and include the query in the `text` field. +The following limitations apply when generating the response. @@ -36 +59 @@ To turn a natural language query into a SQL query, submit a [GenerateQuery](http -###### Note + * When using the `InvokeAgent`, `RetrieveAndGenerate`, and `RetrieveAndGenerateStream` API operations, only 10 retrieved results are used when generating the response. @@ -38 +61 @@ To turn a natural language query into a SQL query, submit a [GenerateQuery](http -Queries must be written in English. + * When using the `InvokeAgent` API, if there are more than 10 rows of retrieved results, the total number of retrieved rows is not passed to the agent for generating the response. If you use the `RetrieveAndGenerate` API instead, the total number of rows is included in the prompt for generating the final response. @@ -40 +63 @@ Queries must be written in English. - * transformationConfiguration – Specify `TEXT_TO_SQL` as the `mode`. In the `textToSqlConfiguration` field, specify `KNOWLEDGE_BASE` as the `type`. Then, specify the ARN of the knowledge base. + * ###### `GenerateQuery` API quota @@ -41,0 +65 @@ Queries must be written in English. +The `GenerateQuery` API has a quota of 2 requests per second. @@ -45 +68,0 @@ Queries must be written in English. -###### Note @@ -47 +70,59 @@ Queries must be written in English. -The `GenerateQuery` API has a quota of 2 requests per second. +## Grant a role permissions to access generated queries + +For your knowledge base that's conencted to a structured data source, if you want to to perform some additional operations on the generated squeries, then you must grant permissions to perform the `GenerateQuery` API action. To allow your IAM role to query a knowledge base connected to a structured data store, attach the following policy to the role: + + + { + "Version": "2012-10-17", + "Statement": [ + { + "Sid": "GetKB", + "Effect": "Allow", + "Action": [ + "bedrock:GetKnowledgeBase" + ], + "Resource": [ + "arn:${Partition}:bedrock:${Region}:${Account}:knowledge-base/${KnowledgeBaseId}" + ] + }, + { + "Sid": "GenerateQueryAccess", + "Effect": "Allow", + "Action": [ + "bedrock:GenerateQuery", + "sqlworkbench:GetSqlRecommendations" + ], + "Resource": "*" + }, + { + "Sid": "Retrieve", + "Effect": "Allow", + "Action": [ + "bedrock:Retrieve", + ] + "Resource": [ + "arn:${Partition}:bedrock:${Region}:${Account}:knowledge-base/${KnowledgeBaseId}" + ] + }, + { + "Sid": "RetrieveAndGenerate", + "Effect": "Allow", + "Action": [ + "bedrock:RetrieveAndGenerate", + ] + "Resource": [ + "*" + ] + } + ] + } + +You can remove statements that you don't need, depending on your use case: + + * The `GetKB` and `GenerateQuery` statements are required to call [GenerateQuery](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_GenerateQuery.html) to generate SQL queries that take into account user queries and your connected data source. + + * The `Retrieve` statement is required to call [Retrieve](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_Retrieve.html) to retrieve data from your structured data store. + + * The `RetrieveAndGenerate` statement is required to call [RetrieveAndGenerate](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_RetrieveAndGenerate.html) to retrieve data from your structured data store and generate responses based off the data. + + @@ -49 +129,0 @@ The `GenerateQuery` API has a quota of 2 requests per second. -The response returns an array containing a [GeneratedQuery](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent-runtime_GeneratedQuery.html) object in the `queries` field. The object contains an SQL query for the query in the `sql` field.