DocsICP FilingConsole
官方文档
首页

QueryCollectionData

更新时间：
复制 MD 格式
我的收藏

Retrieving 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 None

Request parameters

Parameter

Type

Required

Description

Example
DBInstanceId

string

No

The ID of the instance.

Note

You can call the DescribeDBInstances operation to query details for all AnalyticDB for PostgreSQL instances in a region, including their instance IDs.

gp-xxxxxxxxx
Collection

string

Yes

The name of the collection.

Note

You can call the ListCollections operation to list available collections.

document
Namespace

string

No

The name of the namespace.

Note

You can call the ListNamespaces operation to list available namespaces.

mynamespace
NamespacePassword

string

Yes

The password for the namespace.

testpassword
Content

string

No

The content for full-text search. If this parameter is omitted, only vector search is performed. If this parameter is specified, the system performs a hybrid search of vector search and full-text search.

Note

You must specify one of the Content and Vector parameters.

hello_world
Filter

string

No

The filter conditions for data retrieval. It is in the format of a WHERE clause in SQL. This expression returns a boolean value, which can be a simple comparison operator, such as =, <>, !=, >, <, >=, and <=, or a more complex expression combined with logical operators, such as AND, OR, and NOT, and keywords such as IN, BETWEEN, and LIKE.

Note

pipeline_id='1yhpmo0rbn' AND (spu='10025667796135' AND dept_id='226')
TopK

integer

Yes

Specifies the number of top results to return.

10
Vector

array

No

The vector data. The length of the vector data must be the same as that specified in the CreateCollection operation.

Note

  • If SparseVector is empty, only the dense vector search results are returned.

  • If both Vector and SparseVector are empty, only the full-text search results are returned.

number

No

The vector data.

1.234
SparseVector

object

No

The sparse vector data.

Indices

array

No

The array of indexes.

Note

The number of elements in the array cannot exceed 4,000.

integer

No

The index value.

1
Values

array

No

The array of sparse vectors.

number

No

The sparse vector data.

1.2345
RegionId

string

Yes

The region ID of the instance.

cn-hangzhou
Metrics

string

No

The similarity algorithm for search. Valid values:

  • l2: the Euclidean distance.

  • ip: the dot product distance.

  • cosine: the cosine similarity.

Note

If this parameter is not specified, the algorithm specified when the index is created is used.

cosine
IncludeValues

boolean

No

Specifies whether to return dense vector data. Valid values:

  • true: returns dense vector data.

  • false: does not return dense vector data.

true
HybridSearch

string

No

The hybrid search algorithm. If this parameter is empty, the system ranks results by directly comparing the scores from the vector search and the full-text search.

Valid values:

  • RRF: Reciprocal Rank Fusion. This algorithm has a parameter k to control the fusion effect. For more information, see the description of the HybridSearchArgs parameter.

  • Weight: weighted sort. This algorithm uses a parameter alpha to control the score ratio of vector search and full-text search, and then sorts the results. For more information about the parameter, see the HybridSearchArgs parameter.

  • Cascaded: performs a full-text search, and then performs a vector search on the search results.

RRF
HybridSearchArgs

object

No

The parameters for the hybrid search algorithm. The following algorithms are supported: RRF and Weight.

  • For RRF, specify the constant k in the scoring algorithm 1/(k+rank_i). The value must be a positive integer greater than 1. The format is as follows:

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

  • For Weight, in the formula alpha * vector_score + (1-alpha) * text_score, the alpha parameter indicates the score ratio of the vector search to the full-text search. The value ranges from 0 to 1. 0 indicates that only the full-text search is used, and 1 indicates that only the vector search is used.

{ 
   "Weight": {
    "alpha": 0.5
   }
}

object

No

The recall algorithm.

any

No

The configurations of the recall algorithm.

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

OrderBy

string

No

This parameter is left empty by default. It specifies the field based on which to sort the results. This parameter is not supported in hybrid search.

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

This parameter is left empty by default. It specifies the start position of a paged query. This parameter is not supported in hybrid search.

The value must be greater than or equal to 0. When this parameter is not empty, Total in the response indicates the total number of hits. This parameter is used with TopK. For example, if you want to retrieve chunks 0 to 44 with a page size of 20, you must send three requests:

  • Offset=0, TopK=20 returns chunks 0 to 19.

  • Offset=20, TopK=20 returns chunks 20 to 39.

  • Offset=40, TopK=20 returns chunks 40 to 44.

0
IncludeMetadataFields

string

No

This parameter is left empty by default. It specifies the metadata fields to be returned. You can specify multiple fields and separate them with commas (,).

title,content
WorkspaceId

string

No

The ID of the workspace that consists of multiple database instances. You must specify this parameter or the DBInstanceId parameter. If both this parameter and DBInstanceId are specified, this parameter is used.

gp-ws-*****
RelationalTableFilter

object

No

Uses another relational table to filter vector data, which is similar to the JOIN operation.

Note

The data of the relational table can be returned by setting the IncludeMetadataFields parameter. For example, rds_table_name.id indicates that the id field of the relational table is returned.

CollectionMetadataField

string

No

The metadata field of the vector collection, which is used to associate with the fields of the vector table.

doc_id
TableField

string

No

The field of the relational table, which is used to associate with the metadata field of the vector collection.

id
TableName

string

No

The name of the relational table.

my_rds_table
Condition

string

No

The filter conditions for the relational table.

tags @> ARRAY['art']
IncludeSparseValues

boolean

No

Specifies whether to return sparse vector data. Valid values:

  • true: returns sparse vector data.

  • false: does not return sparse vector data.

false

Response elements

Element

Type

Description

Example

object

The recall results.

Matches

object

match

array<object>

An array of matched items.

array<object>

A single matched record.

Id

string

The unique ID of the vector data.

doca-1234
Metadata

object

The associated metadata.

string

The value of a metadata key.

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

object

value

array

An array of floating-point numbers representing the dense vector.

number

A value within the dense vector.

1.234
Score

number

The similarity score of the data record. The score is based on the algorithm (l2/ip/cosine) specified during index creation.

0.12345
SparseValues

object

The sparse vector data.

Indices

object

Indice

array

An array of indices for the sparse vector.

integer

A single index value.

20
Values

object

Value

array

An array of values corresponding to the indices in the sparse vector.

number

A single value from the sparse vector.

0.222
MetadataV2

object

The metadata. This field has the same values as Metadata, but uses a different element type to allow the SDK to deserialize values into their native data types.

any

The SDK deserializes this field's value according to the following rules.

Note

Deserialization rules

ADBPG typeJava SDK typePython SDK type
Integer (integer, bigint)Longint
Floating-point number (real, double precision)Doublefloat
Boolean (boolean)Booleanbool
String (text, character varying)Stringstr
Array (for example, int[], text[])ArrayList<T>, where T is mapped according to the rules in this table.list
jsonStringstr

{'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 error, returned if the request fails.

0.1234
Total

integer

The total number of hits for the search. This parameter is returned only when the Offset parameter in the request 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": [
              20
            ]
          },
          "Values": {
            "Value": [
              0.222
            ]
          }
        },
        "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.