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

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

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 specific region, including the instance IDs.	gp-xxxxxxxxx
Namespace	string	No	The namespace. Default value: public. Note You can call the CreateNamespace operation to create a namespace and call the ListNamespaces operation to view the namespace list.	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 view the created 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 when you call the CreateNamespace operation.	testpassword
Content	string	No	The text content used for retrieval.	What is AnalyticDB for PostgreSQL?
Filter	string	No	The filter conditions for the data to query, formatted as an SQL WHERE clause. This is an expression that returns a Boolean value (true or false). The 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 (<=). They can also be more complex expressions combined with logical operators (AND, OR, NOT), or conditions using keywords such as IN, BETWEEN, and LIKE. 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, the context of the retrieval results is additionally returned. The format is an array of two elements: List<A, B>, where -10 <= A <= 0 and 0 <= B <= 10. Note Use this parameter when documents are split into excessively small chunks and retrieval may lose context information. Reranking takes precedence over windowing. That is, reranking is performed before windowing.
	integer	No	The size of the recall window.	[-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 vector retrieval results are reranked. Valid values: 1 < RerankFactor <= 5. Note When document chunks are sparse, reranking is slow. The 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-channel recall). Default value: false, which indicates that only vector retrieval is used.	true
Metrics	string	No	The similarity algorithm used during retrieval. If this value is empty, the algorithm specified when the knowledge base is created is used. You do not need to set this parameter unless you have special requirements. Note Valid values: l2: Euclidean distance. ip: Dot product (inner product) distance. cosine: Cosine similarity.	cosine
FileName	string	No	The source file name of the image to search in image-to-image search scenarios. Note The image file must have a file name extension. Supported image file name 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 name extension. Supported image file name extensions: bmp, jpg, jpeg, png, and tiff.	https://xx/myImage.jpg
IncludeVector	boolean	No	Specifies whether to return vectors. Default value: false. Note false: Vectors are not returned. true: Vectors are returned.	true
HybridSearch	string	No	The multi-channel recall algorithm. Default value: empty. If this parameter is empty, the scores of dense vectors and full text are directly compared, and sorting is performed. Valid values: RRF: Reciprocal Rank Fusion. A parameter k is used to control the fusion effect. For more information, see the HybridSearchArgs configuration. Weight: Weighted sorting. Parameters are used to control the score weights of vectors and full text before sorting. For more information, see the HybridSearchArgs configuration. Cascaded: Full-text retrieval is performed first, and then vector retrieval is performed based on the full-text retrieval results.	RRF
HybridSearchArgs	object	No	The algorithm parameters for multi-channel recall. RRF and Weight are supported. You can use HybridPathsSetting to specify the recall of dense vectors (dense), sparse vectors (sparse), and full-text retrieval (fulltext). If this value is empty, dense vectors (dense) and full-text retrieval (fulltext) are recalled 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-channel recall (HybridPathsSetting is not specified, and only alpha is specified): Formula: alpha * dense_score + (1-alpha) * fulltext_score. The alpha parameter indicates the score weights of dense vectors and full-text retrieval. Valid values: 0 to 1. A value of 0 indicates full-text retrieval only, and a value of 1 indicates dense vectors only: `{ "Weight": { "alpha": 0.5 } }` Three-channel recall pattern: Formula: normalized_dense * dense_score + normalized_sparse * sparse_score + normalized_fulltext * fulltext_score. The dense, sparse, and fulltext parameters represent the weights of dense vectors, sparse vectors, and full-text retrieval, respectively. Valid values: greater than or equal to 0. The system automatically performs normalization on the weights to 0 to 1 (that is, normalized_x = x / (dense + sparse + fulltext)). `{ "HybridPathsSetting": { "paths": "dense,sparse,fulltext" }, "Weight": { "dense": 0.5, "sparse": 0.3, "fulltext": 0.2 } }`
	object	No	The parameter names for multi-channel recall.
	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: The unit can be seconds (s) or days (d). 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, which is 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 reranking model parameters.
Instruct	string	No	This parameter can be set when RerankModel.Name is set to qwen3-rerank. You can add a custom sorting task description to guide the model to adopt different sorting strategies.	Given a web search query, retrieve relevant passages that answer the query
Name	string	No	The name of the reranking model. Valid values: qwen3-rerank and gte-rerank-v2.	qwen3-rerank
RerankMetadataFields	string	No	The metadata fields that participate in reranking. Separate multiple fields with commas (,). By default, only the document content (content) is used for reranking. The field names must be metadata defined in the collection.
OrderBy	string	No	The field based on which sorting is performed. Default value: empty. The field must belong to the metadata or be 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; and reverse order, such as block_id DESC, chunk_id DESC.	created_at
Offset	integer	No	The offset used for a paged query.	0

Response elements

Element	Type	Description	Example
	object
EmbeddingTokens	string	The number of tokens used for vectorization. Note A token is the smallest unit into which input text is divided. A token can be a word, a phrase, a punctuation mark, or a character.	100
Entities	object
entities	array<object>	The list of entities.
	object	The entity details.
Description	string	The entity description.	A former advisor at DeepMind.
Entity	string	The entity name.	Dr. Wang
FileName	string	The file name.	my_doc.txt
Id	string	The entity ID.	1
Type	string	The entity type.	person
Matches	object
MatchList	array<object>	The list of matches.
	array<object>	The match record.
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.
FileName	string	The file name.	my_doc.txt
FileURL	string	The public URL of the image in the query result. The default validity period is 2 hours. You can specify a custom validity period by using the UrlExpiration parameter.	https://xxx-cn-beijing.aliyuncs.com/image/test.png
Id	string	The unique ID of the vector data.	doca-1234
LoaderMetadata	string	The metadata generated during document loading.	{"page_pos": 1}
Metadata	object	The metadata map.
	string	The metadata.	{"title":"test"}
RerankScore	number	The reranking score.	6.2345
RetrievalSource	integer	The source of the retrieve result. A value of 1 indicates AISearch. A value of 2 indicates full-text index. A value of 3 indicates dual-channel recall.	1
Score	number	The similarity score of the record. The scoring algorithm is based on the algorithm specified during index creation, such as L2, IP, or cosine.	0.12345
Vector	object
VectorList	array	The list of vector data.
	number	The vector data.	[1.2123,-0.12314,...]
Message	string	The returned message.	success
Relations	object
relations	array<object>	The list of relation edges.
	object	The relation edge details.
Description	string	The relation edge description.	Dr. Wang previously served as an advisor at DeepMind.
FileName	string	The file name.	my_doc.txt
Id	string	The relation edge ID.	1
SourceEntity	string	The source entity.	DeepMind consultant
TargetEntity	string	The target entity.	Dr. Wang
RequestId	string	The request ID.	ABB39CC3-4488-4857-905D-2E4A051D0521
Status	string	The status. Valid values: success: Successful. fail: Failed.	success
Usage	object	The resource usage of the current query.
EmbeddingEntries	string	The number of entries used for vectorization. Note An entry refers to the number of items processed when text or images are vectorized. For example, processing text once counts as 1 entry, and processing an image once counts as 2 entries.	10
EmbeddingTokens	string	The number of tokens used for vectorization. Note A token is the smallest unit into which input text is divided. A token can be a word, a phrase, a punctuation mark, or a character.	100
WindowMatches	object
windowMatches	array<object>	The list of windowed matches.
	array<object>
WindowMatch	object
windowMatch	array<object>	The list of matches for a single top window.
	array<object>
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.
FileName	string	The file name.	my_doc.txt
Id	string	The unique ID of the vector data.	doca-2345
LoaderMetadata	string	The metadata generated during document loading.	{"page_pos": 2}
Metadata	object	The metadata map.
	string	The metadata.	{"title":"test"}

Examples

Success response

JSON format

{
  "EmbeddingTokens": "100",
  "Entities": {
    "entities": [
      {
        "Description": "A former advisor at DeepMind.",
        "Entity": "Dr. Wang",
        "FileName": "my_doc.txt",
        "Id": "1",
        "Type": "person"
      }
    ]
  },
  "Matches": {
    "MatchList": [
      {
        "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.",
        "FileName": "my_doc.txt",
        "FileURL": "https://xxx-cn-beijing.aliyuncs.com/image/test.png",
        "Id": "doca-1234",
        "LoaderMetadata": "{\"page_pos\": 1}",
        "Metadata": {
          "key": "{\"title\":\"test\"}"
        },
        "RerankScore": 6.2345,
        "RetrievalSource": 1,
        "Score": 0.12345,
        "Vector": {
          "VectorList": [
            0
          ]
        }
      }
    ]
  },
  "Message": "success",
  "Relations": {
    "relations": [
      {
        "Description": "Dr. Wang previously served as an advisor at DeepMind.",
        "FileName": "my_doc.txt\n",
        "Id": "1",
        "SourceEntity": "DeepMind consultant",
        "TargetEntity": "Dr. Wang"
      }
    ]
  },
  "RequestId": "ABB39CC3-4488-4857-905D-2E4A051D0521",
  "Status": "success",
  "Usage": {
    "EmbeddingEntries": "10",
    "EmbeddingTokens": "100"
  },
  "WindowMatches": {
    "windowMatches": [
      {
        "WindowMatch": {
          "windowMatch": [
            {
              "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.",
              "FileName": "my_doc.txt",
              "Id": "doca-2345",
              "LoaderMetadata": "{\"page_pos\": 2}",
              "Metadata": {
                "key": "{\"title\":\"test\"}"
              }
            }
          ]
        }
      }
    ]
  }
}

Error codes

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.