Retrieves vectors and metadata from multiple specified document collections using natural language queries, then merge and return the results from all retrieval paths.
Debugging
Authorization information
The following table shows the authorization information corresponding to the API. The authorization information can be used in the Action policy element to grant a RAM user or RAM role the permissions to call this API operation. Description:
- Operation: the value that you can use in the Action element to specify the operation on a resource.
- Access level: the access level of each operation. The levels are read, write, and list.
- Resource type: the type of the resource on which you can authorize the RAM user or the RAM role to perform the operation. Take note of the following items:
- For mandatory resource types, indicate with a prefix of * .
- If the permissions cannot be granted at the resource level,
All Resourcesis used in the Resource type column of the operation.
- Condition Key: the condition key that is defined by the cloud service.
- Associated operation: other operations that the RAM user or the RAM role must have permissions to perform to complete the operation. To complete the operation, the RAM user or the RAM role must have the permissions to perform the associated operations.
| Operation | Access level | Resource type | Condition key | Associated operation |
|---|---|---|---|---|
| gpdb:QueryKnowledgeBasesContent | create | *Document acs:gpdb:{#regionId}:{#accountId}:document/{#DBInstanceId} |
| none |
Request parameters
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| DBInstanceId | string | Yes | The cluster ID. Note
You can call the DescribeDBInstances operation to query the information about all AnalyticDB for PostgreSQL instances within a region, including instance IDs.
| gp-xxxxxxxxx |
| RegionId | string | Yes | The region ID. | cn-beijing |
| Content | string | Yes | The text content for retrieval. | |
| MergeMethod | string | No | The method used to merge multiple knowledge bases. Default value: RRF. Valid values:
| RRF |
| MergeMethodArgs | object | No | The parameters of the merge method for each SourceCollection. | |
| Rrf | object | No | The parameter that can be configured when the MergeMethod parameter is set to RRF. | |
| K | long | No | The smoothing constant k in the formula to calculate the score: 1/(k + rank_i). The k constant must be a positive integer greater than 1. | 60 |
| Weight | object | No | The parameter that you can configure when you set the MergeMethod parameter to Weight. | |
| Weights | array | No | An array of weights for each SourceCollection. | |
| double | No | The weight of each SourceCollection. | 0.5 | |
| RerankFactor | double | No | The rerank factor. If you specify this parameter, the vector retrieval results are reranked once more. Valid values: 1<RerankFactor<=5. Note
| 2 |
| SourceCollection | array<object> | Yes | The information about collections to retrieve from. | |
| object | Yes | Knowledge base. | ||
| Collection | string | Yes | The name of the document collection. Note
You can call the CreateDocumentCollection operation to create a document collection and call the ListDocumentCollections operation to query a list of document collections.
| knowledge22 |
| Namespace | string | No | The namespace. Note
You can call the CreateNamespace operation to create a namespace and call the ListNamespaces operation to query a list of namespaces.
| ns_cloud_index |
| NamespacePassword | string | Yes | The password of the namespace. Note
The value of this parameter is specified when you call the CreateNamespace operation.
| ns_password |
| QueryParams | object | No | The condition that is used to filter the data to be updated. Specify this parameter in a format that is the same as the WHERE clause. | |
| Filter | string | No | The filter condition that is used to query data. Specify this parameter in a format that is the same as the WHERE clause. The parameter is an expression that returns a Boolean value of TRUE or FALSE. The condition can be a simple comparison using operators such as equal (=), not equal (<> or !=), greater than (>), less than (<), greater than or equal (>=), or less than or equal (<=). It can also be a more complex expression combining multiple conditions with logical operators (AND, OR, NOT), or use keywords such as IN, BETWEEN, and LIKE. Note
| id = 'llm-52tvykqt6u67iw73_j6ovptwjk7_file_6ce3da1f7e69495d9f491f2180c86973_11967297' |
| GraphEnhance | boolean | No | Whether to enable knowledge graph enhancement. Default value: false. | true |
| GraphSearchArgs | object | No | Returns the top number of entities and relationship edges. Default value: 60. | |
| GraphTopK | long | No | Returns the top number of entities and relationship edges. Default value: 60. | 60 |
| HybridSearch | string | No | The dual-path retrieval algorithm. This parameter is empty by default, which specifies that scores of vector retrieval and full-text retrieval are directly compared and sorted together. Valid values:
| Cascaded |
| HybridSearchArgs | object | No | The parameters of the dual-path retrieval algorithm. RRF and Weight are supported at this time:
| |
| any | No | The parameter value. | { "RRF": { "k": 60 } } | |
| Metrics | string | No | The method that is used to create vector indexes. Valid values:
| cosine |
| RecallWindow | array | No | The retrieval window. If you specify this parameter, the context of the retrieved result is added in the output. Format: List<A, B>. Valid values: -10<=A<=0 and 0<=B<=10. Note
| |
| long | No | Retrieval window size. | [0,0] | |
| RerankFactor | double | No | The rerank factor. If you specify this parameter, the vector retrieval results are reranked once more. Valid values: 1<RerankFactor<=5. Note
| 2.0 |
| TopK | long | No | The number of top results. | 776 |
| UseFullTextRetrieval | boolean | No | Specifies whether to use full-text retrieval (dual-path retrieval). The default value is false, which means only vector retrieval is used. | false |
| OrderBy | string | No | The fields by which to sort the results. This parameter is empty by default. The field must be either a metadata field or a default field in the table (e.g., id). Supported formats include: Single field, such as chunk_id. Multiple fields that are separated by commas (,), such as block_id,chunk_id. Descending order is supported, such as block_id DESC,chunk_id DESC. | file_id,sort_num |
| Offset | integer | No | Offset for pagination. | 20 |
| TopK | long | No | Set the number of top results to be returned after merging results from multiple path retrieval. | 10 |
Response parameters
Examples
Sample success responses
JSONformat
{
"RequestId": "ABB39CC3-4488-4857-905D-2E4A051D0521",
"Message": "success",
"Status": "success",
"Matches": {
"MatchList": [
{
"Id": "doca-1234",
"Content": "",
"Metadata": {
"key": "{\\\"pic_id\\\":\\\"text\\\",\\\"pic_name\\\":\\\"text\\\",\\\"pic_url\\\":\\\"text\\\"}"
},
"FileName": "my_doc.txt",
"Score": 0.12345,
"RetrievalSource": 1,
"LoaderMetadata": {
"page_pos": 1
},
"FileURL": "https://xxx-cn-beijing.aliyuncs.com/image/test.png",
"RerankScore": 6.2345
}
]
},
"EmbeddingTokens": 100,
"Usage": {
"EmbeddingTokens": 475,
"EmbeddingEntries": 10
},
"Entities": {
"entities": [
{
"Id": 1,
"Entity": "Dr. Wang",
"Type": "",
"Description": "A former advisor at DeepMind.",
"FileName": "my_doc.txt"
}
]
},
"Relations": {
"relations": [
{
"Id": 1,
"SourceEntity": "",
"TargetEntity": "Dr. Wang",
"Description": "Dr. Wang previously served as an advisor at DeepMind.",
"FileName": "my_doc.txt\n"
}
]
}
}Error codes
For a list of error codes, visit the Service error codes.
Change history
| Change time | Summary of changes | Operation |
|---|---|---|
| 2025-10-30 | Add Operation | View Change Details |
