Query Vectors & Metadata with QueryContent API - AnalyticDB for PostgreSQL - Alibaba Cloud - AnalyticDB

Retrieves vectors and metadata from a specified document collection using natural language queries.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.
API: The API that you can call to perform the action.
Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.
Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.
- For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.
- For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.
Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.
Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

gpdb:QueryContent

create

*Document

acs:gpdb:{#regionId}:{#accountId}:document/{#DBInstanceId}

None

Request parameters

Parameter	Type	Required	Description	Example
DBInstanceId	string	Yes	The instance ID. Note You can call the DescribeDBInstances operation to query the details of all AnalyticDB for PostgreSQL instances in a region, including instance IDs.	gp-xxxxxxxxx
Namespace	string	No	The namespace. Default value: public. Note You can create a namespace by calling the CreateNamespace operation and query namespaces by calling the ListNamespaces operation.	mynamespace
Collection	string	Yes	The name of the document collection. Note The document collection is created by calling the CreateDocumentCollection operation. You can call the ListDocumentCollections operation to query existing document collections.	document
RegionId	string	Yes	The region ID of the instance.	cn-hangzhou
NamespacePassword	string	Yes	The password of the namespace. Note This value is specified by the CreateNamespace operation.	testpassword
Content	string	No	The text content used for retrieval.	What is AnalyticDB for PostgreSQL?
Filter	string	No	The filter condition for the data to query, in SQL WHERE clause format. The filter is an expression that returns a Boolean value (true or false). Conditions can be simple comparison operators such as equal to (=), not equal to (<> or !=), greater than (>), less than (<), greater than or equal to (>=), and less than or equal to (<=). Conditions can also be more complex expressions combined with logical operators (AND, OR, NOT), as well as conditions using the IN, BETWEEN, and LIKE keywords. Note For detailed syntax, refer to: https://www.postgresqltutorial.com/postgresql-tutorial/postgresql-where/.	title = 'test' AND name like 'test%'
RecallWindow	array	No	The recall window. When this value is not empty, additional context around the retrieval results is returned. The format is a two-element array: List<A, B>, where -10<=A<=0 and 0<=B<=10. Note Use this parameter when documents are split into overly small chunks and retrieval may lose contextual information. Reranking takes priority over windowing. Reranking is performed first, followed by windowing.
	integer	No	The recall window size.	[-5, 5]
TopK	integer	No	The number of top results to return.	10
RerankFactor	number	No	The reranking factor. When this value is not empty, the AISearch retrieve results are reranked. Valid values: 1 < RerankFactor <= 5. Note Reranking is slow when documents are sparsely chunked. The total number of reranked results (TopK × Factor, rounded up) should not exceed 50.	2
UseFullTextRetrieval	boolean	No	(Deprecated) Specifies whether to use full-text retrieval (dual-path recall). Default value: false, which indicates that only vector retrieval is used.	true
Metrics	string	No	The similarity algorithm used for retrieval. If this value is empty, the algorithm specified when the knowledge base was created is used. Leave this parameter empty unless you have specific requirements. Note Valid values: l2: Euclidean distance. ip: inner product distance. cosine: cosine similarity.	cosine
FileName	string	No	The name of the source image file to search in image-to-image search scenarios. Note The image file must have a file extension. Supported image extensions: bmp, jpg, jpeg, png, and tiff.	test.jpg
FileUrl	string	No	The publicly accessible URL of the image file in image-to-image search scenarios. Note The image file must have a file extension. Supported image extensions: bmp, jpg, jpeg, png, and tiff.	https://xx/myImage.jpg
IncludeVector	boolean	No	Specifies whether to return vectors. Default value: false. Note false: Does not return vectors. true: Returns vectors.	true
HybridSearch	string	No	The multi-channel recall algorithm. Default value: empty, which indicates that the dense vector and full-text index scores are directly compared and sorted. Valid values: RRF: Reciprocal Rank Fusion. A parameter k controls the fusion effect. For more information, see the HybridSearchArgs configuration. Weight: Weighted sorting. Parameters control the score weights of AISearch retrieve and full-text index results before sorting. For more information, see the HybridSearchArgs configuration. Cascaded: Full-text index retrieve is performed first, followed by AISearch retrieve based on the full-text index results.	RRF
HybridSearchArgs	object	No	The algorithm parameters for multi-channel recall. RRF and Weight are supported. HybridPathsSetting specifies the recall paths: dense vectors (dense), sparse vectors (sparse), and full-text index (fulltext). If this value is empty, dense vectors (dense) and full-text index (fulltext) are used by default. RRF: Specifies the constant k in the score calculation formula `1/(k+rank_i)`. The value must be a positive integer greater than 1. Format: `{ "HybridPathsSetting": { "paths": "dense,fulltext" }, "RRF": { "k": 60 } }` Weight: Dual-path recall (without specifying HybridPathsSetting, only specifying alpha): Formula: alpha * dense_score + (1-alpha) * fulltext_score. The alpha parameter specifies the score weight between dense vectors and full-text index retrieve. Valid values: 0 to 1, where 0 indicates full-text index only and 1 indicates dense vector only: `{ "Weight": { "alpha": 0.5 } }` Three-path recall pattern: Formula: normalized_dense * dense_score + normalized_sparse * sparse_score + normalized_fulltext * fulltext_score. The dense, sparse, and fulltext values represent the weights for dense vectors, sparse vectors, and full-text index retrieve respectively. Valid values: greater than or equal to 0. The system automatically performs normalization of the weights to 0 to 1 (normalized_x = x / (dense + sparse + fulltext)). `{ "HybridPathsSetting": { "paths": "dense,sparse,fulltext" }, "Weight": { "dense": 0.5, "sparse": 0.3, "fulltext": 0.2 } }`
	object	No	The multi-channel recall parameter name.
	any	No	The parameter value.	{ "HybridPathsSetting": { "paths": "dense,fulltext" }, "RRF": { "k": 60 } }
IncludeMetadataFields	string	No	The metadata fields to return. Default value: empty. Separate multiple fields with commas.	title,page
IncludeFileUrl	boolean	No	Specifies whether to synchronously return the URL of the document. By default, the URL is not returned.	false
UrlExpiration	string	No	The validity period of the returned image URL. Note Valid values: Supports seconds (s) and days (d) as units. For example, 300s indicates a validity period of 300 seconds, and 60d indicates a validity period of 60 days. Valid values: 60s to 365d. Default value: 7200s (2 hours).	7200s
GraphEnhance	boolean	No	Specifies whether to enable knowledge graph enhancement. Default value: false.	false
GraphSearchArgs	object	No	The knowledge graph retrieval parameters.
GraphTopK	integer	No	The number of top entities and relationship edges to return. Default value: 60.	60
RerankModel	object	No	The rerank model parameters.
Name	string	No	The name of the rerank model. Valid values: qwen3-rerank, gte-rerank-v2.	qwen3-rerank
Instruct	string	No	This parameter can be set when RerankModel.Name is qwen3-rerank. Adds a custom sorting task type description. This parameter guides the model to adopt different sorting strategies.	Given a web search query, retrieve relevant passages that answer the query
RerankMetadataFields	string	No
OrderBy	string	No	The field used for sorting. Default value: empty. The field must belong to metadata or a default field in the table, such as id. Supported formats: A single field, such as chunk_id. Multiple fields separated by commas, such as block_id, chunk_id. Descending order, such as block_id DESC, chunk_id DESC.	created_at
Offset	integer	No	The offset for paged query. Used for paging through results.	0

Response elements

Element	Type	Description	Example
	object
RequestId	string	The request ID.	ABB39CC3-4488-4857-905D-2E4A051D0521
Message	string	The returned message.	success
Status	string	The status. Valid values: success: Succeeded. fail: Failed.	success
Matches	object
MatchList	array<object>	The list of matched results.
	array<object>	A single record.
Id	string	The unique vector ID.	doca-1234
Content	string	The text content.	AnalyticDB for PostgreSQL is a massively parallel processing (MPP) data warehouse service compatible with ANSI SQL 2003, the PostgreSQL ecosystem, and the Oracle database ecosystem.
Metadata	object	The metadata.
	string	Custom metadata as key-value pairs.	{"title":"test"}
Vector	object
VectorList	array	The vector values.
	number	A floating-point number in the vector.	[1.2123,-0.12314,...]
FileName	string	The file name.	my_doc.txt
Score	number	The similarity score for the record. The scoring algorithm depends on the metric (for example, `l2`, `ip`, or `cosine`) specified when the index was created.	0.12345
RetrievalSource	integer	The retrieval source. A value of `1` indicates vector retrieval, `2` indicates full-text search, and `3` indicates dual-channel recall.	1
LoaderMetadata	string	The metadata captured when the document loader loads the document.	{"page_pos": 1}
FileURL	string	The public URL of the file in the query result. By default, the URL is valid for 2 hours. You can use the `UrlExpiration` parameter to specify a custom validity period.	https://xxx-cn-beijing.aliyuncs.com/image/test.png
RerankScore	number	The reranking score.	6.2345
WindowMatches	object
windowMatches	array<object>	The list of windowed matched results.
	array<object>
WindowMatch	object
windowMatch	array<object>	The matches within a single window.
	array<object>
Id	string	The unique vector ID.	doca-2345
Content	string	The text content.	AnalyticDB for PostgreSQL is a massively parallel processing (MPP) data warehouse service compatible with ANSI SQL 2003, the PostgreSQL ecosystem, and the Oracle database ecosystem.
Metadata	object	The metadata.
	string	Custom metadata as key-value pairs.	{"title":"test"}
FileName	string	The file name.	my_doc.txt
LoaderMetadata	string	The metadata captured when the document loader loads the document.	{"page_pos": 2}
EmbeddingTokens	string	The number of tokens used during vectorization. Note A token is the smallest unit into which the input text is split. A token can be a word, a phrase, a punctuation mark, or a character.	100
Usage	object	The resource usage of this query.
EmbeddingTokens	string	The number of tokens used during vectorization. Note A token is the smallest unit into which the input text is split. A token can be a word, a phrase, a punctuation mark, or a character.	100
EmbeddingEntries	string	The number of entries used during vectorization. Note An entry refers to the number of items processed during vectorization of text or images. For example, processing text once counts as 1 entry, and processing an image once counts as 2 entries.	10
Entities	object
entities	array<object>	The list of entities.
	object	The entity details.
Id	string	The entity ID.	1
Entity	string	The entity name.	Dr. Wang
Type	string	The entity type.	person
Description	string	The entity description.	A former advisor at DeepMind.
FileName	string	The file name.	my_doc.txt
Relations	object
relations	array<object>	The list of relationship edges.
	object	The relationship edge details.
Id	string	The relationship edge ID.	1
SourceEntity	string	The source entity.	DeepMind consultant
TargetEntity	string	The target entity.	Dr. Wang
Description	string	The relationship edge description.	Dr. Wang previously served as an advisor at DeepMind.
FileName	string	The file name.	my_doc.txt

Examples

Success response

JSON format

{
  "RequestId": "ABB39CC3-4488-4857-905D-2E4A051D0521",
  "Message": "success",
  "Status": "success",
  "Matches": {
    "MatchList": [
      {
        "Id": "doca-1234",
        "Content": "AnalyticDB for PostgreSQL is a massively parallel processing (MPP) data warehouse service compatible with ANSI SQL 2003, the PostgreSQL ecosystem, and the Oracle database ecosystem.",
        "Metadata": {
          "key": "{\"title\":\"test\"}"
        },
        "Vector": {
          "VectorList": [
            0
          ]
        },
        "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
      }
    ]
  },
  "WindowMatches": {
    "windowMatches": [
      {
        "WindowMatch": {
          "windowMatch": [
            {
              "Id": "doca-2345",
              "Content": "AnalyticDB for PostgreSQL is a massively parallel processing (MPP) data warehouse service compatible with ANSI SQL 2003, the PostgreSQL ecosystem, and the Oracle database ecosystem.",
              "Metadata": {
                "key": "{\"title\":\"test\"}"
              },
              "FileName": "my_doc.txt",
              "LoaderMetadata": "{\"page_pos\": 2}"
            }
          ]
        }
      }
    ]
  },
  "EmbeddingTokens": "100",
  "Usage": {
    "EmbeddingTokens": "100",
    "EmbeddingEntries": "10"
  },
  "Entities": {
    "entities": [
      {
        "Id": "1",
        "Entity": "Dr. Wang",
        "Type": "person",
        "Description": "A former advisor at DeepMind.",
        "FileName": "my_doc.txt"
      }
    ]
  },
  "Relations": {
    "relations": [
      {
        "Id": "1",
        "SourceEntity": "DeepMind consultant",
        "TargetEntity": "Dr. Wang",
        "Description": "Dr. Wang previously served as an advisor at DeepMind.",
        "FileName": "my_doc.txt\n"
      }
    ]
  }
}

Error codes

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.