Call the QueryCollectionData API to query vector and full-text data - AnalyticDB

Retrieve vector data.

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:QueryCollectionData

create

*Collection

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

None

Request parameters

Parameter	Type	Required	Description	Example
DBInstanceId	string	No	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 instance IDs.	gp-xxxxxxxxx
Collection	string	Yes	The name of the collection. Note You can call the ListCollections operation to query a list of collections.	document
Namespace	string	No	The namespace. Note You can call the ListNamespaces operation to query a list of namespaces.	mynamespace
NamespacePassword	string	Yes	The password for the namespace.	testpassword
Content	string	No	The content for full-text search. If you specify this parameter, a hybrid search is performed. If this parameter is empty, only a vector search is performed. Note You cannot leave both this parameter and the `Vector` parameter empty.	hello_world
Filter	string	No	The filter condition for the query, specified in the format of a SQL WHERE clause. The expression must return a boolean value (`true` or `false`) and can include comparison operators (`=`, `!=`, `>`, `<`, `>=`, `<=`), logical operators (`AND`, `OR`, `NOT`), and keywords such as `IN`, `BETWEEN`, and `LIKE`. Note For more information about the syntax, see PostgreSQL WHERE.	pipeline_id='1yhpmo0rbn' AND (spu='10025667796135' AND dept_id='226')
TopK	integer	Yes	The number of top results to return.	10
Vector	array	No	The dense vector for the query. The number of dimensions must match the dimension specified when you call the CreateCollection API. Note If the `SparseVector` parameter is not provided, only dense vector search results are returned. If you do not provide `Vector` or `SparseVector`, only full-text search results are returned (assuming `Content` is provided).
	number	No	An element in the vector array.	1.234
SparseVector	object	No	The sparse vector for the query.
Indices	array	No	The array of indices for the non-zero elements in the sparse vector. Note The number of elements in the array cannot exceed 4,000.
	integer	No	An index.	1
Values	array	No	The array of values that corresponds to the indices.
	number	No	A value.	1.2345
RegionId	string	Yes	The region ID of the instance.	cn-hangzhou
Metrics	string	No	The similarity metric for the search. Valid values: l2: Euclidean distance. ip: Inner product. cosine: Cosine similarity. Note If you do not specify this parameter, the system uses the metric specified during index creation.	cosine
IncludeValues	boolean	No	Specifies whether to return vector data in the query results. Valid values: true: Returns vector data. false: Does not return vector data. This is the recommended setting for full-text search-only scenarios.	true
HybridSearch	string	No	The hybrid search algorithm. If you do not specify this parameter, the system directly compares and sorts the scores from the vector search and full-text search. Valid values: RRF: Reciprocal Rank Fusion. This algorithm uses a parameter `k` to control the fusion effect. For more information, see the `HybridSearchArgs` parameter. Weight: Weighted Ranking. This algorithm uses a parameter `alpha` to control the weight of vector search and full-text search scores before sorting. For more information, see the `HybridSearchArgs` parameter. Cascaded: Performs a full-text search, then performs a vector search on the results.	RRF
HybridSearchArgs	object	No	The parameters for the specified hybrid search algorithm. The following algorithms are supported: RRF: Specifies the constant `k` in the scoring formula `1/(k+rank_i)`. The value must be an integer greater than 1. The following is an example: `{ "RRF": { "k": 60 } }` Weight: The scoring formula is `alpha * vector_score + (1-alpha) * text_score`. The `alpha` parameter specifies the weight of the vector search score relative to the full-text search score. The value must be a number from 0 to 1. A value of 0 indicates that only the full-text search is used, and a value of 1 indicates that only the vector search is used. The following is an example: `{ "Weight": { "alpha": 0.5 } }`
	object	No
	any	No		{ "Weight": { "alpha": 0.5 } }
OrderBy	string	No	The field used for sorting. This parameter is not supported in hybrid search scenarios. By default, this parameter is empty. The field must be a metadata field or a default field in the table, such as `id`. The following formats are supported: 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`.	chunk_id
Offset	integer	No	The starting point for a paginated query. By default, this parameter is empty. This parameter is not supported in hybrid search scenarios. The value must be greater than or equal to 0. When you specify this parameter, the response includes a `Total` field that indicates the total number of matches. This parameter is used with `TopK`. For example, to retrieve 45 chunks in pages of 20, you must send three requests: `Offset=0, TopK=20`: Returns the 1st to 20th chunks. `Offset=20, TopK=20`: Returns the 21st to 40th chunks. `Offset=40, TopK=20`: Returns the 41st to 45th chunks.	0
IncludeMetadataFields	string	No	The metadata fields to return. By default, this parameter is empty. To return multiple fields, separate them with commas.	title,content
WorkspaceId	string	No	The ID of the workspace, which consists of multiple database instances. You cannot leave both this parameter and the `DBInstanceId` parameter empty. If you specify both parameters, this parameter takes precedence.	gp-ws-*****
RelationalTableFilter	object	No	Filters Vector Search results by joining with a relational table. Note To return data from the relational table, specify the fields in the `IncludeMetadataFields` parameter. For example, `rds_table_name.id` returns the `id` field of the relational table.
CollectionMetadataField	string	No	The metadata field in the vector collection that joins with a field in the relational table.	doc_id
TableField	string	No	The field in the relational table that joins with the metadata field in the vector collection.	id
TableName	string	No	The name of the relational table.	my_rds_table
Condition	string	No	The filter condition for the relational table.	tags @> ARRAY['art']
IncludeSparseValues	boolean	No	Specifies whether to return sparse vector data in the query results. Valid values: true: Returns sparse vector data. false: Does not return sparse vector data.

Response elements

Element

Type

Description

Example

object

The query response object.

Matches

object

The matched results.

match

array<object>

A list of matches.

array<object>

A single Record.

string

The unique ID of the vector data.

doca-1234

Metadata

object

The Metadata associated with the Record.

string

The metadata content.

{"title":"test title", "content": "test content"}

Values

object

The Vector Data.

value

array

An array of numbers that represents the vector.

number

A single value from the vector.

1.234

Score

number

The Similarity Score for this record. The score is calculated based on the metric (l2, ip, or cosine) specified during index creation.

0.12345

SparseValues

object

The sparse vector data.

Indices

object

The indices of the sparse vector.

Indice

array

An array of indices for the sparse vector.

integer

A single index from the sparse vector.

Values

object

The values of the sparse vector.

Value

array

An array of values for the sparse vector.

number

A single value from the sparse vector.

MetadataV2

object

The metadata. This field has the same values as the Metadata field, but uses a different data type for its elements to support any data type in the Software Development Kit (SDK).

any

This field can contain various data types. The SDK deserializes the data based on the following rules.

Note

Deserialization Rules

ADBPG data type	Java SDK type	Python SDK type
Integer (integer, bigint)	Long	int
Floating-point (real, double precision)	Double	float
Boolean (boolean)	Boolean	bool
String (text, character varying)	String	str
Array (e.g., int[], text[])	ArrayList<T> (where T is mapped according to these rules)	list
json	String	String

{'array_field': [15.5, 25.5, 35.5], 'float_field': 128.45, 'long_field': 123456789017, 'bool_field': False, 'json_field': '{"key1":"value1","num":999.0}', 'char_array_field': '[c, h, a, r, s, 5]', 'int_field': 128, 'source': 0, 'double_field': 12350.6789, 'string_field': 'test_string_5'}

RequestId

string

The Request ID.

ABB39CC3-4488-4857-905D-2E4A051D0521

Status

string

The status of the request. Valid values:

success: The request was successful.
fail: The request failed.

success

Message

string

Details about the request. This field is returned only if the request fails.

0.1234

Total

integer

The total number of hits that match the search criteria. This field is returned only if the Offset parameter is not 0.

100

Examples

Success response

JSON format

{
  "Matches": {
    "match": [
      {
        "Id": "doca-1234",
        "Metadata": {
          "key": "{\"title\":\"test title\", \"content\":  \"test content\"}"
        },
        "Values": {
          "value": [
            1.234
          ]
        },
        "Score": 0.12345,
        "SparseValues": {
          "Indices": {
            "Indice": [
              0
            ]
          },
          "Values": {
            "Value": [
              0
            ]
          }
        },
        "MetadataV2": {
          "key": "{'array_field': [15.5, 25.5, 35.5], 'float_field': 128.45, 'long_field': 123456789017, 'bool_field': False, 'json_field': '{\"key1\":\"value1\",\"num\":999.0}', 'char_array_field': '[c, h, a, r, s, 5]', 'int_field': 128, 'source': 0, 'double_field': 12350.6789, 'string_field': 'test_string_5'}"
        }
      }
    ]
  },
  "RequestId": "ABB39CC3-4488-4857-905D-2E4A051D0521",
  "Status": "success",
  "Message": "0.1234",
  "Total": 100
}

Error codes

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.