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

Use the put-vectors command to write vector data to a vector index in a vector bucket.

Prerequisites

Before you begin, ensure that you have:

An OSS vector bucket with a vector index
The oss:PutVectors permission (see Permissions)
ossutil installed and configured

Syntax

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 as a JSON string, or a path to a JSON file prefixed with `file://`.

For global flags, see Global command-line options.

Note: The put-vectors command corresponds to the PutVectors API operation.

Vector data format

The vector data must be a JSON array. Each element in the array represents one vector.

[
  {
    "data": {
      "float32": [0.1, 0.2, 0.3]
    },
    "key": "doc-001",
    "metadata": {
      "category": ["news", "tech"],
      "source": "web"
    }
  }
]

Fields

Field	Type	Required	Description
`key`	string	Yes	The primary key of the vector. Uniquely identifies the vector within the index. If a key already exists, the vector is overwritten. If duplicate keys appear in the same batch, the entire operation fails. Must be 1–1,024 characters in UTF-8 format.
`data`	container	Yes	The vector content.
`data.float32`	numeric array	Yes	The vector values as float32 numbers. The number of elements must match the dimensions defined in the index. Zero vectors are not supported when using cosine distance.
`metadata`	container	No	Optional metadata attached to the vector. Values must be strings. Total size cannot exceed 40 KB. Filterable fields: 0–10, with the filterable portion not exceeding 2 KB. Empty filter conditions are allowed. See Limitations for filter instruction constraints.

Write vectors

For large datasets, store the vector data in a JSON file and reference it with the file:// prefix. For quick testing or small payloads, pass the vector data inline as a JSON string.

Tip: A single batch can contain at most 500 vectors. For large-scale ingestion, split your data into batches of 500 or fewer vectors.

Write from a file

Store the vector data in a JSON file, then reference the file with the file:// prefix.

vectors.json:

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

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

Write inline

Pass the JSON array directly as a string. Escape inner quotes with backslashes.

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

Permissions

Alibaba Cloud accounts have all permissions by default. RAM users and RAM roles have no permissions by default. Grant the required permissions through a RAM Policy or a bucket policy.

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

Limitations

Constraint	Limit
Max vectors per index	50,000,000 rows
Max vectors per batch	500
`key` length	1–1,024 characters (UTF-8)
`metadata` total size	40 KB
Filterable fields in `metadata`	0–10 fields; filterable portion cannot exceed 2 KB
Total filterable metadata per filter instruction	64 KB
Filterable metadata items per filter instruction	1,024
Filter condition nesting depth	8 levels