Write vector data to an index using put-vectors - Object Storage Service - Alibaba Cloud - Object Storage Service

Usage notes

A single vector index can store up to 2 billion rows of vector data.
The PutVectors operation has a QPS limit of 1,000. A single request can write a batch of up to 500 vectors, and the total number of vectors across all concurrent requests is limited to 2,500.

Permissions

An Alibaba Cloud account has all permissions by default. However, a Resource Access Management (RAM) user or RAM role does not have any permissions by default. The Alibaba Cloud account owner or an administrator must grant permissions using a RAM Policy or a bucket policy.

API	Action	Description
PutVectors	`oss:PutVectors`	Writes vector data.

Command format

ossutil vectors-api put-vectors --bucket value --index-name value --vectors value [flags]

Parameters

Parameter	Type	Description
--bucket	string	The name of the vector bucket.
--index-name	string	The name of the index.
--vectors	string	The vector data. You can specify a JSON string or a file path prefixed with file://.

Note

The put-vectors command corresponds to the PutVectors API operation.
For information about the supported global command-line options, see Global command-line options.

Vector data format

The vector data must be in the JSON array format. Each vector in the array contains the following fields:

[ 
    { 
       "data": {
          "float32":[float]
       },
       "key": "string",
       "metadata": {
           "key1": ["value1", "value2"],
           "key2": "value2"
       }
    }
]

The following table describes each field.

Name	Data type	Required	Example	Description
key	String	Yes	doc-001	The primary key of the vector. It uniquely identifies the vector. The following limits apply: If a key already exists, the vector is overwritten. If duplicate keys exist within the same batch, the entire operation fails. The key must be 1 to 1,024 characters in length. The key must be in UTF-8 format. Parent node: vectors
data	Container	Yes	-	The content of the vector. Parent node: vectors
float32	Numeric array	Yes	[0.1, 0.2, 0.3]	The vector data. The data type is float32. The vector dimensions must match the dimensions defined in the index. Zero vectors are not allowed when the cosine distance measure is used. Parent node: data
metadata	Container	No	-	The metadata. The following limits apply: The total size cannot exceed 200 KB. Limits for filterable metadata: Each vector supports 0 to 100 filterable fields. The size of each filterable metadata field cannot exceed 2 KB. Supported data types: string, number, boolean, and list. When you configure filterable metadata: The total length of filterable metadata in a single filter instruction cannot exceed 20 KB. The number of filterable metadata items in a single filter instruction cannot exceed 1,024. Filter conditions can be nested up to 8 levels deep. Empty filter conditions are allowed. Parent node: vectors

Examples

This example adds a vector to a vector index named index in a vector bucket named examplebucket. The vector data is [1], the primary key is vector1, and the metadata is {"Key1": "32"}.

Use a JSON configuration file. The following content is in the vectors.json file:

[
  {
    "data": {
      "float32": [1]
    },
    "key": "vector1",
    "metadata": {
      "Key1": "32"
    }
  }
]

Command example:

ossutil vectors-api put-vectors --bucket examplebucket --index-name index --vectors file://vectors.json

Use a JSON configuration parameter:

ossutil vectors-api put-vectors --bucket examplebucket --index-name index --vectors "[{\"data\":{\"float32\":[1]},\"key\":\"vector1\",\"metadata\":{\"Key1\":\"32\"}}]"