PutVectorIndexFusion-阿里云帮助中心

Usage notes

A Fusion-mode index uses a schema to define the type and retrieval capabilities of each field, and supports multiple retrieval capabilities such as vector search, scalar filtering, and full-text search. Standard-mode and Fusion-mode indexes can coexist in the same vector bucket.
If the request contains a parameter that the server does not support, an error is returned.
The creation operation either fully succeeds or fully fails.

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
PutVectorIndexFusion	`oss:PutVectorIndexFusion`	Creates a Fusion-mode vector index.

Request syntax

POST /?putVectorIndexFusion 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",
   "mode": "fusion",
   "schemaConfiguration": {
      "fields": [
         {
            "name": "string",
            "type": "string"
         }
      ]
   }
}

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. You can customize it. Must be globally unique within the vector bucket and 1 to 63 characters in length. Can contain only letters and digits, and must start with a letter.	vectorindex1
mode	String	Yes	The index mode. Set the value to fusion to create a Fusion-mode index.	fusion
schemaConfiguration	Object	Yes	A container for the schema configuration. Any configuration that the server does not support returns an error.	-
fields	Array of objects	Yes	The schema field configuration. The following limits apply: The total number of fields cannot exceed 100. The number of vector fields cannot exceed 3. The number of fields with tokenization enabled cannot exceed 8. Other scalar fields consume the remaining quota. At least one field with type=vector must exist. Parent node: schemaConfiguration	-
fields.name	String	Yes	The field name. Must be unique within a single index and 1 to 63 characters in length. Can contain uppercase and lowercase letters, digits, and underscores (_), and must start with a letter. Parent node: fields	vector_1
fields.type	String	Yes	The field type. Valid values: vector: a vector. double: a floating-point number. long: an integer. bool: a Boolean value. string: a string. You can enable tokenization to support full-text search. ip: an IP address. geoPoint: geographic point coordinates, in the format "latitude,longitude", with latitude first and longitude second. The latitude range is [-90,+90] and the longitude range is [-180,+180]. For example, 35.8,-45.91. Parent node: fields	vector

Parameters supported by each field type

Field type	Parameter	Type	Default	Description	Required
vector	dataType	String	-	The data type of the vector. This value is fixed and cannot be selected: float32 (floating-point).	Yes
	dimension	Integer	-	The vector dimension. Only 1 to 4096 dimensions are supported.	Yes
	distanceMetric	String	-	The distance metric. Valid values: euclidean: Euclidean distance. cosine: cosine distance. ip: inner product distance.	Yes
double	isArray	Boolean	false	Whether the field is an array. An array supports a maximum of 128 elements. Values such as NaN and positive or negative Infinity are not supported.	No
long	isArray	Boolean	false	Whether the field is an array. An array supports a maximum of 128 elements.	No
ip	isArray	Boolean	false	Whether the field is an array. An array supports a maximum of 128 elements.	No
string	isArray	Boolean	false	Whether the field is an array. The following limits apply: An array supports a maximum of 512 elements. A single string element is at most 4 KB, and all elements of the array combined are at most 64 KB. Arrays are not supported when tokenization (text) is enabled for the field. Arrays are not supported when the field is used as a partition key (isPartitionKey).	No
	isPartitionKey	Boolean	false	Whether the field is used as a partition key. By default, hash(vector key) is used to locate the target partition for writes. After configuration, hash(partitionKey) is used to locate the target partition for writes. Only one string field can be set as the partition key.	No
	exactMatch	Boolean	true	Whether to support exact-match (non-tokenized) queries. For example, if a field field_a is written with "abcd123", the query supports filtering on field_a="abcd123". When exactMatch is enabled, a single string is at most 4 KB. The default values and limits are as follows: By default, a string field has exactMatch=true and text.enabled=false. When isPartitionKey=true, exactMatch must be true, and text tokenization cannot be enabled. When text.enabled=true, exactMatch must be explicitly set to true or false. At least one of text and exactMatch must be enabled. When neither isArray nor isPartitionKey is used, both can be enabled at the same time.	No
	text.enabled	Boolean	false	Whether to enable tokenization. After tokenization is enabled, full-text search operators are supported. The following limits apply to tokenization: After tokenization is enabled, a single string is at most 64 KB. When exactMatch is also enabled, a single string is at most 4 KB. A string field with tokenization enabled does not support arrays. text is the parent node of the tokenization field, under which parameters such as analyzer and analyzerParameters can be configured.	No
	text.analyzer	String	standard	The analyzer type. Valid values: standard (default, can be omitted): the standard analyzer, which splits English text by word and Chinese text by character. split: delimiter-based tokenization, which lets you customize the tokenization result.	No

Analyzer parameters (text.analyzerParameters)

The parameters supported by each analyzer are as follows:

standard analyzer:
- caseSensitive: whether matching is case-sensitive. The default value is false, in which case all English letters are converted to lowercase. To keep case sensitivity, set it to true.
- delimitWord: for words in which letters and digits are joined together, whether to split the letters and digits. The default value is false, which means digits and letters are not split. When set to true, for example, "iphone6" is split into "iphone" and "6".
split analyzer:
- caseSensitive: same as the standard analyzer.
- delimiter: a custom delimiter. This parameter is required and has no default value. Valid values: space character (" "), vertical bar ("|"), hyphen ("-"), underscore ("_"), and comma (",").

Response headers

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

Examples

Note

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

Comprehensive example (all field types)

Example request

POST /?putVectorIndexFusion 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",
   "mode": "fusion",
   "schemaConfiguration": {
      "fields": [
         {
            "name": "vector_1",
            "type": "vector",
            "dataType": "float32",
            "dimension": 1024,
            "distanceMetric": "euclidean"
         },
         {
            "name": "vector_2",
            "type": "vector",
            "dataType": "float32",
            "dimension": 512,
            "distanceMetric": "cosine"
         },
         {
            "name": "timestamps",
            "type": "long",
            "isArray": true
         },
         {
            "name": "price",
            "type": "double"
         },
         {
            "name": "ip",
            "type": "ip"
         },
         {
            "name": "location",
            "type": "geoPoint"
         },
         {
            "name": "tag",
            "type": "string"
         },
         {
            "name": "user_id",
            "type": "string",
            "isPartitionKey": true
         },
         {
            "name": "tags",
            "type": "string",
            "isArray": true
         },
         {
            "name": "title_1",
            "type": "string",
            "exactMatch": true,
            "text": {
               "enabled": true,
               "analyzer": "standard",
               "analyzerParameters": {
                  "caseSensitive": true,
                  "delimitWord": false
               }
            }
         },
         {
            "name": "title_2",
            "type": "string",
            "exactMatch": false,
            "text": {
               "enabled": true,
               "analyzer": "split",
               "analyzerParameters": {
                  "caseSensitive": true,
                  "delimiter": " "
               }
            }
         }
      ]
   }
}

Example response

HTTP/1.1 200 OK
x-oss-request-id: 534B371674E88A4D8906****
Date: Thu, 17 Apr 2025 01:33:47 GMT
Connection: keep-alive
Server: AliyunOSS

Minimal schema: single vector field

Example request

POST /?putVectorIndexFusion 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",
  "mode": "fusion",
  "schemaConfiguration": {
    "fields": [
      {
        "name": "content_vector",
        "type": "vector",
        "dataType": "float32",
        "dimension": 1024,
        "distanceMetric": "cosine"
      }
    ]
  }
}

Multiple vectors: text, image, and video (multimodal)

Example request

POST /?putVectorIndexFusion 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": "multimodalindex",
  "mode": "fusion",
  "schemaConfiguration": {
    "fields": [
      {
        "name": "text_vector",
        "type": "vector",
        "dataType": "float32",
        "dimension": 1024,
        "distanceMetric": "cosine"
      },
      {
        "name": "image_vector",
        "type": "vector",
        "dataType": "float32",
        "dimension": 512,
        "distanceMetric": "euclidean"
      },
      {
        "name": "video_vector",
        "type": "vector",
        "dataType": "float32",
        "dimension": 256,
        "distanceMetric": "ip"
      },
      {
        "name": "title",
        "type": "string",
        "exactMatch": true,
        "text": {
          "enabled": true,
          "analyzer": "standard"
        }
      },
      {
        "name": "duration",
        "type": "long"
      }
    ]
  }
}

Full-text search: standard analyzer

Example request

POST /?putVectorIndexFusion 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",
  "mode": "fusion",
  "schemaConfiguration": {
    "fields": [
      {
        "name": "chunk_vector",
        "type": "vector",
        "dataType": "float32",
        "dimension": 1024,
        "distanceMetric": "cosine"
      },
      {
        "name": "title",
        "type": "string",
        "exactMatch": true,
        "text": {
          "enabled": true,
          "analyzer": "standard",
          "analyzerParameters": {
            "caseSensitive": false,
            "delimitWord": true
          }
        }
      },
      {
        "name": "body",
        "type": "string",
        "exactMatch": false,
        "text": {
          "enabled": true,
          "analyzer": "standard"
        }
      },
      {
        "name": "doc_id",
        "type": "string"
      },
      {
        "name": "year",
        "type": "long"
      },
      {
        "name": "status",
        "type": "string"
      },
      {
        "name": "updated_at",
        "type": "long"
      }
    ]
  }
}

Partition key: multi-tenant RAG knowledge base

Example request

POST /?putVectorIndexFusion 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": "tenantkbindex",
  "mode": "fusion",
  "schemaConfiguration": {
    "fields": [
      {
        "name": "chunk_vector",
        "type": "vector",
        "dataType": "float32",
        "dimension": 1024,
        "distanceMetric": "cosine"
      },
      {
        "name": "tenant_id",
        "type": "string",
        "isPartitionKey": true
      },
      {
        "name": "doc_id",
        "type": "string"
      },
      {
        "name": "content",
        "type": "string",
        "exactMatch": false,
        "text": {
          "enabled": true,
          "analyzer": "standard"
        }
      },
      {
        "name": "updated_at",
        "type": "long"
      }
    ]
  }
}

Error codes

Error code	HTTP status code	Description
VectorIndexParameterInvalid	400	The vector index parameter provided in the request is invalid.
MalformedJson	400	The request body is not in valid JSON format.
VectorBucketIndexExceedLimit	400	The number of created indexes has reached the upper limit. A single vector bucket can contain up to 100 vector indexes.
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.
VectorBucketIndexAlreadyExist	409	The specified index name already exists and cannot be created again.