QueryVectorsFusion - Object Storage Service - Alibaba Cloud Documentation Center

Usage notes

QueryVectorsFusion is used to query Fusion-mode indexes. To perform a vector similarity search on a Standard-mode index, use the QueryVectors operation.
Unlike QueryVectors, which returns results by distance, QueryVectorsFusion returns results by relevance score. A higher score indicates higher relevance.
knn, query, and retriever correspond to vector search, scalar and full-text filtering, and multi-way recall fusion, respectively. You can combine them as needed. When retriever is used, the request can include only the indexName, limit, partitionKeys, returnMetadata, and returnMetadataFields parameters.
nextToken supports pagination only in a query-only search scenario (without knn or retriever).

Permissions

By default, an Alibaba Cloud account has full permissions, whereas a RAM user or RAM role has none. The Alibaba Cloud account owner or an administrator must grant permissions by using a RAM policy or a bucket policy.

API	Action	Description
QueryVectorsFusion	`oss:QueryVectorsFusion`	Queries a Fusion-mode vector index.

Request syntax

POST /?queryVectorsFusion HTTP/1.1
Host: examplebucket-123***456.cn-hangzhou-internal.oss-vectors.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue
Content-type: application/json

{
   "indexName": "string",
   "knn": [
      {
         "field": "string",
         "queryVector": [0.1],
         "topK": 10
      }
   ],
   "returnMetadata": true
}

Request headers

This operation uses only common request headers. For more information, see Common HTTP headers.

Request parameters

Parameter	Type	Required	Description	Example
indexName	String	Yes	The name of the index to query.	vectorindex1
knn	Array of objects	No	The vector search configuration. It supports approximate nearest neighbor (ANN) search on one or more vector fields, with a maximum of 3. For the sub-parameters, see "knn parameters" below.	-
query	Object	No	The scalar filtering and full-text search conditions, expressed by using filter operators. For the operators, see "Filter operators" below.	-
retriever	Object	No	The multi-way recall fusion configuration, which merges and re-ranks the results of multiple retrieval ways by using a fusion algorithm. For the sub-parameters, see "retriever parameters" below. When retriever is used, the request can include only indexName, limit, partitionKeys, returnMetadata, and returnMetadataFields.	-
returnMetadata	Boolean	No	Specifies whether to return the metadata of vectors. The default value is false.	true
returnMetadataFields	Array of strings	No	The names of the metadata fields to return. If this parameter is not specified, all metadata fields are returned. Vector fields cannot be specified.	["price","tag"]
partitionKeys	Array of strings	No	The partition key values. This parameter limits the search scope to the specified partitions, which improves search efficiency. It is available only when a partition key is defined in the index schema. A maximum of 512 elements are supported, with a total size of at most 4 KB.	["user_1"]
limit	Integer	No	The maximum number of results to return. The default value is 10.	10
nextToken	String	No	The pagination token. Pagination is supported only in a query-only search scenario (without knn or retriever). Pass in the nextToken returned by the previous request to obtain the next page.	CAESABgB****
sort	Array of objects	No	The sort fields. A maximum of 3 can be specified. Sorting is supported for long, double, bool, string (with exactMatch enabled), and ip fields, and their arrays. Sorting by relevance score _score is supported, but _score supports only descending order (desc).	[{"field":"price","order":"asc"}]

knn parameters

knn is an array of objects. Each element represents an approximate nearest neighbor (ANN) search on a vector field, with a maximum of 3. The sub-parameters are as follows:

Parameter	Type	Required	Description	Example
field	String	Yes	The name of the vector field to query. It must be a field with type=vector in the schema.	vector_1
queryVector	Array of floats	Yes	The query vector. Its dimension must be consistent with the dimension of the vector field specified by field.	[0.1, 0.2, 0.3]
topK	Integer	No	The number of nearest neighbors to return. The default value is 10.	10
filter	Object	No	The pre-filter conditions for the vector search. Scalar conditions are applied to filter first, and then the vector search is performed. For the filter operators, see "Filter operators" below.	-
numCandidates	Integer	No	The size of the candidate set for the vector search. The value must be no less than topK. The default value equals topK. Increasing this value appropriately can improve recall quality but increases search overhead. If you have no experience in tuning this parameter, we recommend that you use the server-side default value.	100
boost	Float	No	The weight coefficient for the score of this vector search way. The default value is 1.0.	1.0

retriever parameters

retriever is used for multi-way recall fusion. It consists of a compound retriever that nests simple retrievers. The total number of retrievers is at most 3 and at least 1. Nesting a compound retriever within a compound retriever is not supported in this release.

Compound retriever: fuses the results of multiple simple retrievers by using an algorithm. Valid values:
- rrf (Reciprocal Rank Fusion): fuses results by weighting the reciprocal of the rank of each way's results. Supported parameters:
  - k: the rank smoothing constant. Valid values: 1 to 65536. The default value is 50.
  - windowSize: the result window size of each way that participates in fusion. The default value is 100.
  - weight: the weight of this retriever. The value must be no less than 0. The default value is 1.0.
- weight (weighted fusion): normalizes the scores of each way and then computes a weighted sum. Supported parameters:
  - weight: the weight of this retriever. The default value is 1.0.
  - normalizer: the score normalization method. Valid values: none (no normalization), minMax (min-max normalization), and l2 (L2 normalization). The default value is none.
  - windowSize: the result window size of each way that participates in fusion.
Simple retriever: a single source for fusion. Valid values:
- knn: a single vector search way. The sub-parameters are the same as "knn parameters" above.
- query: a single scalar and full-text search way. The sub-parameters are the same as "Filter operators" below.

Filter operators

In query and filter, scalar filtering and full-text search conditions are expressed by using filter operators. The supported operators are as follows:

Operator	Description	Applicable type
`$and`	Logical AND. All sub-conditions (clauses) must be satisfied. Supports boost (weight) and minShouldMatch (the minimum number of matches).	Logical operator
`$or`	Logical OR. Any sub-condition can be satisfied. Supports boost and minShouldMatch.	Logical operator
`$nor`	Logical NOR. None of the sub-conditions (clauses) are satisfied. Does not support boost.	Logical operator
`$eq` / `$in` / `$exists`	Indicate equal to, in a set, and field exists, respectively. Support boost (you can use the object form to carry boost).	Scalar operator
`$ne` / `$nin`	Indicate not equal to and not in a set, respectively.	Scalar operator
`$gt` / `$gte` / `$lt` / `$lte`	Indicate greater than, greater than or equal to, less than, and less than or equal to, respectively. For two-sided range filtering, we recommend that you use the `$range` operator for better performance.	Scalar operator
`$range`	Range filtering. Express a range by combining gt/gte/lt/lte. Supports boost. gt and gte are mutually exclusive, and lt and lte are mutually exclusive.	Scalar operator
`$textMatch`	Tokenized match (full-text search). Supported parameters: operator (optional, and/or, default or), minShouldMatch, and boost. The search text is at most 512 bytes. Applicable only to string fields with tokenization (text) enabled.	Full-text operator
`$textMatchPhrase`	Phrase match (full-text search), which requires the matched terms to keep the same order and adjacency. Supported parameter: boost. The search text is at most 512 bytes. Applicable only to string fields with tokenization (text) enabled.	Full-text operator
`$geoDistance`	Search by distance range, matching documents within a given radius centered at a point. Supported parameters: centerPoint (the center coordinate, a string in the "latitude,longitude" format), distanceInMeter (the radius from the center, in meters, greater than 0), and boost. Applicable only to geoPoint fields.	Geo operator
`$geoBoundingBox`	Search by rectangular area, matching documents within the rectangle. Supported parameters: topLeft (the top-left corner coordinate) and bottomRight (the bottom-right corner coordinate), both strings in the "latitude,longitude" format; boost is also supported. Applicable only to geoPoint fields.	Geo operator
`$geoPolygon`	Search by polygon area, matching documents within the polygon. Supported parameters: points (an array of polygon vertex coordinates, each a string in the "latitude,longitude" format, up to 16 points) and boost. Applicable only to geoPoint fields.	Geo operator
`$matchAll`	Matches all documents.	Match-all operator

Operator syntax examples

The following examples show the syntax of each operator by category, including the default form and the form with custom parameters. Replace field_name in the examples with the actual field name.

Logical operators ($and / $or / $nor)

// $and: all sub-conditions must be satisfied; supports boost
{
  "$and": {
    "clauses": [
      { "title": { "$eq": "马拉松" } },
      { "year":  { "$gte": 2020 } }
    ],
    "boost": 2.0
  }
}

// $or: any sub-condition can be satisfied; supports boost and minShouldMatch
{
  "$or": {
    "clauses": [
      { "title": { "$eq": "马拉松" } },
      { "year":  { "$gte": 2020 } }
    ],
    "boost": 2.0,
    "minShouldMatch": "50%"
  }
}

// $nor: none of the sub-conditions is satisfied; does not support boost
{
  "$nor": {
    "clauses": [
      { "category": { "$eq": "drama" } },
      { "year":     { "$gte": 2020 } }
    ]
  }
}

Equality / set / existence operators ($eq / $ne / $in / $nin / $exists)

// $eq: equal to; supports the shorthand and object forms (the object form can carry boost)
{ "field_name": { "$eq": "documentary" } }
{ "field_name": { "$eq": { "value": "documentary", "boost": 2.0 } } }

// $ne: not equal to (negation semantics; does not support boost)
{ "field_name": { "$ne": "documentary" } }

// $in / $nin: in / not in a set (up to 1024 elements; $in can carry boost)
{ "field_name": { "$in": ["comedy", "documentary"] } }
{ "field_name": { "$in": { "value": ["comedy", "documentary"], "boost": 2.0 } } }
{ "field_name": { "$nin": ["comedy", "documentary"] } }

// $exists: whether the field exists
{ "field_name": { "$exists": true } }
{ "field_name": { "$exists": { "value": true, "boost": 2.0 } } }

Range operators ($gt / $gte / $lt / $lte / $range)

// $gt / $gte / $lt / $lte: single-sided comparison, shorthand form
{ "field_name": { "$gt": 6 } }
{ "field_name": { "$gte": 6 } }

// $range: two-sided range; supports boost (recommended for better performance)
// Constraints: gt and gte are mutually exclusive, lt and lte are mutually exclusive,
// and $range must not be mixed with $gt/$gte/$lt/$lte on the same field
{
  "field_name": {
    "$range": {
      "gte": 6,
      "lt": 10,
      "boost": 2.0
    }
  }
}

Full-text search operators ($textMatch / $textMatchPhrase)

// $textMatch: tokenized match, default form
{ "field_name": { "$textMatch": "a b c" } }
// $textMatch: with custom parameters
{
  "field_name": {
    "$textMatch": {
      "value": "a b c",
      "operator": "or",
      "minShouldMatch": "75%",
      "boost": 2.0
    }
  }
}

// $textMatchPhrase: phrase match, default form
{ "field_name": { "$textMatchPhrase": "a b c" } }
// $textMatchPhrase: with custom parameters (only boost is supported)
{
  "field_name": {
    "$textMatchPhrase": {
      "value": "a b c",
      "boost": 2.0
    }
  }
}

Geo operators ($geoDistance / $geoBoundingBox / $geoPolygon)

// $geoDistance: search by distance range
{
  "field_name": {
    "$geoDistance": {
      "centerPoint": "5,5",
      "distanceInMeter": 10000,
      "boost": 2.0
    }
  }
}

// $geoBoundingBox: search by rectangular area
{
  "field_name": {
    "$geoBoundingBox": {
      "topLeft": "10,0",
      "bottomRight": "0,10",
      "boost": 2.0
    }
  }
}

// $geoPolygon: search by polygon area (up to 16 vertices)
{
  "field_name": {
    "$geoPolygon": {
      "points": ["0,0", "5,5", "5,0"],
      "boost": 2.0
    }
  }
}

Match-all operator ($matchAll)

// $matchAll: match all documents
{ "$matchAll": {} }
// with boost
{ "$matchAll": { "boost": 2.0 } }

Note

Different field types support different filter operators. For example, numeric fields (long and double) support comparison and range operators; the exact-match capability (exactMatch) of a string field supports equality operators, and full-text operators are supported after tokenization is enabled; geoPoint fields support geo operators. Use the operators based on the capabilities configured for each field in the index schema.

Response headers

This operation uses only common response headers. For more information, see Common HTTP headers.

Response elements

Element	Type	Description	Example
vectors	Array of objects	The list of vector results hit by the search.	-
key	String	The unique identifier of the vector. Parent node: vectors	key1
score	Float	The relevance score. A higher score indicates higher relevance. Parent node: vectors	0.87
metadata	Object	The metadata of the vector. It is returned only when returnMetadata=true. You can use returnMetadataFields to specify the fields to return. Parent node: vectors	-
nextToken	String	The pagination token. It is returned only in a query-only search scenario and is used to obtain the next page of results.	CAESABgB****

Examples

Note

The queryVector and vector values in the following examples illustrate the structure only and are truncated. In actual calls, the vector length must exactly match the dimension declared when the index is created. Otherwise, an invalid parameter error is returned.

Single-path vector search

Example request

POST /?queryVectorsFusion HTTP/1.1
Host: examplebucket-123***456.cn-hangzhou-internal.oss-vectors.aliyuncs.com
Date: Thu, 17 Apr 2025 01:33:47 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218
Content-type: application/json

{
  "indexName": "docindex",
  "knn": {
    "field": "content_vector",
    "queryVector": [0.12, 0.53, 0.08, 0.91],
    "topK": 100
  },
  "limit": 10
}

Vector search with pre-filtering (hybrid search)

Example request

POST /?queryVectorsFusion HTTP/1.1
Host: examplebucket-123***456.cn-hangzhou-internal.oss-vectors.aliyuncs.com
Date: Thu, 17 Apr 2025 01:33:47 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218
Content-type: application/json

{
   "indexName": "vectorindex1",
   "knn": [
      {
         "field": "vector_1",
         "queryVector": [0.1, 0.2, 0.3],
         "topK": 10,
         "filter": {
            "price": { "$gte": 100, "$lte": 500 }
         }
      }
   ],
   "returnMetadata": true,
   "returnMetadataFields": ["price", "tag"],
   "limit": 10
}

Example response

HTTP/1.1 200 OK
x-oss-request-id: 534B371674E88A4D8906****
Date: Thu, 17 Apr 2025 01:33:47 GMT
Content-Type: application/json
Server: AliyunOSS

{
   "vectors": [
      {
         "key": "key1",
         "score": 0.87,
         "metadata": {
            "price": 199,
            "tag": "shoes"
         }
      },
      {
         "key": "key2",
         "score": 0.72,
         "metadata": {
            "price": 320,
            "tag": "shoes"
         }
      }
   ]
}

Scalar-only search (no vectors)

Example request

POST /?queryVectorsFusion HTTP/1.1
Host: examplebucket-123***456.cn-hangzhou-internal.oss-vectors.aliyuncs.com
Date: Thu, 17 Apr 2025 01:33:47 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218
Content-type: application/json

{
  "indexName": "productindex",
  "query": {
    "$and": {
      "clauses": [
        { "category": { "$in": { "value": ["phone", "tablet"] } } },
        { "price": { "$range": { "gte": 1000, "lte": 5000 } } },
        { "stock": { "$gt": 0 } }
      ]
    }
  },
  "sort": [{ "price": { "order": "asc" } }],
  "limit": 20,
  "returnMetadata": true,
  "returnMetadataFields": ["title", "brand", "price", "stock"]
}

Full-text search ($textMatch)

Example request

POST /?queryVectorsFusion HTTP/1.1
Host: examplebucket-123***456.cn-hangzhou-internal.oss-vectors.aliyuncs.com
Date: Thu, 17 Apr 2025 01:33:47 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218
Content-type: application/json

{
  "indexName": "kbindex",
  "query": {
    "body": {
      "$textMatch": {
        "value": "wireless noise-canceling headphones",
        "operator": "or",
        "minShouldMatch": "2",
        "boost": 1.0
      }
    }
  },
  "limit": 10,
  "returnMetadata": true,
  "returnMetadataFields": ["title", "doc_id"]
}

Geo search ($geoDistance)

Example request

POST /?queryVectorsFusion HTTP/1.1
Host: examplebucket-123***456.cn-hangzhou-internal.oss-vectors.aliyuncs.com
Date: Thu, 17 Apr 2025 01:33:47 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218
Content-type: application/json

{
  "indexName": "poiindex",
  "query": {
    "location": {
      "$geoDistance": {
        "centerPoint": "31.23,121.47",
        "distanceInMeter": 5000,
        "boost": 1.0
      }
    }
  },
  "sort": [{ "rating": { "order": "desc" } }],
  "limit": 20,
  "returnMetadata": true,
  "returnMetadataFields": ["name", "rating", "city"]
}

Hybrid search: RRF fusion

Example request

POST /?queryVectorsFusion HTTP/1.1
Host: examplebucket-123***456.cn-hangzhou-internal.oss-vectors.aliyuncs.com
Date: Thu, 17 Apr 2025 01:33:47 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218
Content-type: application/json

{
  "indexName": "productindex",
  "retriever": {
    "rrf": {
      "k": 50,
      "windowSize": 100,
      "retrievers": [
        {
          "retriever": {
            "knn": {
              "field": "text_vector",
              "queryVector": [0.12, 0.53, 0.08],
              "topK": 100
            }
          },
          "weight": 2.0
        },
        {
          "retriever": {
            "simple": {
              "query": {
                "title": { "$textMatch": { "value": "wireless headphones" } }
              }
            }
          },
          "weight": 0.5
        }
      ]
    }
  },
  "limit": 10,
  "returnMetadata": true,
  "returnMetadataFields": ["title", "brand"]
}

Example response

HTTP/1.1 200 OK
x-oss-request-id: 534B371674E88A4D8906****
Date: Thu, 17 Apr 2025 01:33:47 GMT
Content-Type: application/json
Server: AliyunOSS

{
   "vectors": [
      {
         "key": "product-001",
         "score": 0.04755,
         "metadata": {
            "title": "Wireless Noise-Canceling Headphones",
            "brand": "AliBrand"
         }
      },
      {
         "key": "product-007",
         "score": 0.03846,
         "metadata": {
            "title": "Over-Ear Headphones",
            "brand": "NovaBrand"
         }
      }
   ]
}

Hybrid search: weighted normalized fusion

Example request

POST /?queryVectorsFusion HTTP/1.1
Host: examplebucket-123***456.cn-hangzhou-internal.oss-vectors.aliyuncs.com
Date: Thu, 17 Apr 2025 01:33:47 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218
Content-type: application/json

{
  "indexName": "productindex",
  "retriever": {
    "weight": {
      "windowSize": 100,
      "retrievers": [
        {
          "retriever": {
            "knn": {
              "field": "text_vector",
              "queryVector": [0.12, 0.53, 0.08],
              "topK": 100
            }
          },
          "weight": 0.7,
          "normalizer": "minMax"
        },
        {
          "retriever": {
            "simple": {
              "query": {
                "title": { "$textMatch": { "value": "wireless headphones" } }
              }
            }
          },
          "weight": 0.3,
          "normalizer": "minMax"
        }
      ]
    }
  },
  "limit": 10,
  "returnMetadata": true,
  "returnMetadataFields": ["title", "brand"]
}

Example response

HTTP/1.1 200 OK
x-oss-request-id: 534B371674E88A4D8906****
Date: Thu, 17 Apr 2025 01:33:47 GMT
Content-Type: application/json
Server: AliyunOSS

{
   "vectors": [
      {
         "key": "product-001",
         "score": 0.23056,
         "metadata": {
            "title": "Wireless Noise-Canceling Headphones",
            "brand": "AliBrand"
         }
      }
   ]
}

Pagination (nextToken)

Example request

POST /?queryVectorsFusion HTTP/1.1
Host: examplebucket-123***456.cn-hangzhou-internal.oss-vectors.aliyuncs.com
Date: Thu, 17 Apr 2025 01:33:47 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218
Content-type: application/json

{
  "indexName": "kbindex",
  "query": {
    "$and": {
      "clauses": [
        { "title": { "$textMatch": { "value": "vector database" } } },
        { "year": { "$range": { "gte": 2024 } } }
      ]
    }
  },
  "nextToken": "CAESCG15aC1mESgEeKaGA",
  "limit": 50,
  "returnMetadata": true,
  "returnMetadataFields": ["title", "year"]
}

Error codes

Error code	HTTP status code	Description
MalformedJson	400	The request body is not in valid JSON format.
InvalidArgument	400	The search parameters provided in the request are invalid. For example, the query vector dimension does not match the index, or a filter operator that the field does not support is used.
NoSuchVectorIndex	404	The specified vector index does not exist.
AccessDenied	403	Access denied. Possible causes: The request does not include the required authentication information. You do not have the required permissions to perform the operation.