All Products
Search
Document Center

AnalyticDB:QueryKnowledgeBasesContent

Last Updated:Nov 07, 2025

Retrieves vectors and metadata from multiple specified document collections using natural language queries, then merge and return the results from all retrieval paths.

Debugging

You can run this interface directly in OpenAPI Explorer, saving you the trouble of calculating signatures. After running successfully, OpenAPI Explorer can automatically generate SDK code samples.

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 Resources is 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.
OperationAccess levelResource typeCondition keyAssociated operation
gpdb:QueryKnowledgeBasesContentcreate
*Document
acs:gpdb:{#regionId}:{#accountId}:document/{#DBInstanceId}
    none
none

Request parameters

ParameterTypeRequiredDescriptionExample
DBInstanceIdstringYes

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
RegionIdstringYes

The region ID.

cn-beijing
ContentstringYes

The text content for retrieval.

MergeMethodstringNo

The method used to merge multiple knowledge bases. Default value: RRF. Valid values:

  • RRF
  • Weight
RRF
MergeMethodArgsobjectNo

The parameters of the merge method for each SourceCollection.

RrfobjectNo

The parameter that can be configured when the MergeMethod parameter is set to RRF.

KlongNo

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
WeightobjectNo

The parameter that you can configure when you set the MergeMethod parameter to Weight.

WeightsarrayNo

An array of weights for each SourceCollection.

doubleNo

The weight of each SourceCollection.

0.5
RerankFactordoubleNo

The rerank factor. If you specify this parameter, the vector retrieval results are reranked once more. Valid values: 1<RerankFactor<=5.

Note
  • If the document is segmented into sparse parts, reranking is inefficient.

  • We recommend that the number of reranked results (the ceiling of TopK × RerankFactor) not exceed 50.

2
SourceCollectionarray<object>Yes

The information about collections to retrieve from.

objectYes

Knowledge base.

CollectionstringYes

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
NamespacestringNo

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
NamespacePasswordstringYes

The password of the namespace.

Note The value of this parameter is specified when you call the CreateNamespace operation.
ns_password
QueryParamsobjectNo

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.

FilterstringNo

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
  • For the syntax, see https://www.postgresqltutorial.com/postgresql-tutorial/postgresql-where/.
id = 'llm-52tvykqt6u67iw73_j6ovptwjk7_file_6ce3da1f7e69495d9f491f2180c86973_11967297'
GraphEnhancebooleanNo

Whether to enable knowledge graph enhancement. Default value: false.

true
GraphSearchArgsobjectNo

Returns the top number of entities and relationship edges. Default value: 60.

GraphTopKlongNo

Returns the top number of entities and relationship edges. Default value: 60.

60
HybridSearchstringNo

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:

  • RRF: The reciprocal rank fusion (RRF) algorithm uses a constant k to control the fusion effect. For more information, see the description of the HybridSearchArgs parameter.
  • Weight: This algorithm uses the alpha parameter to specify the proportion of the vector search score and the full-text search score and then sorts by weight. For more information, see the description of the HybridSearchArgs parameter.
  • Cascaded: This algorithm performs first full-text retrieval and then vector retrieval.
Cascaded
HybridSearchArgsobjectNo

The parameters of the dual-path retrieval algorithm. RRF and Weight are supported at this time:

  • RRF: Specifies 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. The format:
{ 
   "RRF": {
    "k": 60
   }
}
  • Weight: The score is computed as alpha * vector_score + (1 - alpha) * text_score. The parameter alpha controls the weighting between vector search and full-text search scores, with a valid range of [0, 1]. 0 specifies only full-text search score. 1 specifies only vector search score.
{ 
   "Weight": {
    "alpha": 0.5
   }
}
anyNo

The parameter value.

{ "RRF": { "k": 60 } }
MetricsstringNo

The method that is used to create vector indexes. Valid values:

  • l2: Euclidean distance.
  • ip: Inner product distance.
  • cosine: Cosine similarity.
cosine
RecallWindowarrayNo

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
  • We recommend that you specify this parameter if the source document is segmented into large numbers of pieces, which may result in loss of contextual information during retrieval.

  • Perform re-ranking before windowing.

longNo

Retrieval window size.

[0,0]
RerankFactordoubleNo

The rerank factor. If you specify this parameter, the vector retrieval results are reranked once more. Valid values: 1<RerankFactor<=5.

Note
  • If the document is segmented into sparse parts, reranking is inefficient.

  • We recommend that the number of reranked results (the ceiling of TopK × RerankFactor) not exceed 50.

2.0
TopKlongNo

The number of top results.

776
UseFullTextRetrievalbooleanNo

Specifies whether to use full-text retrieval (dual-path retrieval). The default value is false, which means only vector retrieval is used.

false
OrderBystringNo

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
OffsetintegerNo

Offset for pagination.

20
TopKlongNo

Set the number of top results to be returned after merging results from multiple path retrieval.

10

Response parameters

ParameterTypeDescriptionExample
object
RequestIdstring

The unique ID of the request.

ABB39CC3-4488-4857-905D-2E4A051D0521
Messagestring

The returned information.

success
Statusstring

The status of the operation. Valid values:

  • success.
  • fail.
success
Matchesarray<object>

A single data record.

MatchListobject

A single data record.

Idstring

The unique ID of the vector data.

doca-1234
Contentstring

The content of the text.

Metadataobject

The metadata map.

string

Metadata Map value.

{\"pic_id\":\"text\",\"pic_name\":\"text\",\"pic_url\":\"text\"}
FileNamestring

The name of the file.

my_doc.txt
Scoredouble

The similarity score of the data. It is related to the algorithm (l2, ip, or cosine) that is specified when you create an index.

0.12345
RetrievalSourceinteger

The source of the retrieval results. 1 indicates vector retrieval, 2 indicates full-text retrieval, and 3 indicates dual-path retrieval.

1
LoaderMetadatastring

Document loader metadata.

{"page_pos": 1}
FileURLstring

The public network URL of the image result. By default, the URL is valid for 2 hours.

You can use the UrlExpiration parameter to specify a validity period.

https://xxx-cn-beijing.aliyuncs.com/image/test.png
RerankScoredouble

The rerank score.

6.2345
EmbeddingTokensstring

The number of tokens that are used during vectorization.

Note A token is the minimum unit for segmenting text. A token can be a word, phrase, punctuation, or character.
100
Usageobject

The total number of tokens that are consumed by this query.

EmbeddingTokensstring

The number of tokens that are used for vectorization.

Note A token is the minimum unit for splitting text. A token can be a word, phrase, punctuation, or character.
475
EmbeddingEntriesstring

The number of entries that are used during vectorization.

Note An entry refers to a single unit of vectorization processing. Processing one text input counts as 1 entry, while processing one image counts as 2 entries.
10
Entitiesarray<object>

The details of the entity.

entitiesobject

The details of the entity.

Idstring

The entity ID.

1
Entitystring

The name of the entity.

Dr. Wang
Typestring

The entity type.

Descriptionstring

The entity description.

A former advisor at DeepMind.
FileNamestring

The name of the file.

my_doc.txt
Relationsarray<object>

The details of the relationship edge.

relationsobject

The details of the relationship edge.

Idstring

The ID of the link.

1
SourceEntitystring

The source entity.

TargetEntitystring

The destination entity.

Dr. Wang
Descriptionstring

The description of the relationship edge.

Dr. Wang previously served as an advisor at DeepMind.
FileNamestring

The name of the file.

my_doc.txt

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 timeSummary of changesOperation
2025-10-30Add OperationView Change Details