# oss-vector

Part of **OSS**

<!-- intent-backlink:auto -->

> 💡 **Path Selection**: This skill is one implementation path for [Manage vector data and indexes](../../intent/oss-manage-data/SKILL.md). If you're unsure which path to take, check the routing skill first.

# Object Storage Service Vector Storage

## Capabilities Overview

| Sub-capability | Calling Mode | Description |
|----------------|--------------|-------------|
| Manage Vector Bucket | Synchronous | Create, delete, and retrieve vector bucket information. |
| Manage Vector Index | Synchronous | Create, delete, and retrieve vector index configurations. |
| Manage Vectors | Synchronous | Insert, delete, and retrieve vector data from indexes. |
| List Vectors in Index | Synchronous | Retrieve vectors stored within a vector index. |
| Write Vector Data to Index | Synchronous | Write vector data to a vector index for later similarity searching. |
| Perform Vector Similarity Search | Synchronous | Query vector indexes to find similar vectors based on distance metrics. |

## API Calling Patterns

### Authentication
The primary authentication method is **OSS Signature Version 4** using AccessKey credentials.

- **Header format**:  
  `Authorization: OSS4-HMAC-SHA256 Credential=<AccessKeyID>/<Date>/<Region>/oss/aliyun_v4_request,Signature=<SignatureValue>`
- **Environment variable**: `ALIBABA_CLOUD_ACCESS_KEY_ID` and `ALIBABA_CLOUD_ACCESS_KEY_SECRET`
- Alternative methods like bearer tokens are mentioned in some docs but OSS Signature v4 is the standard for OSS APIs.

### Service Endpoint (Endpoint)
APIs use region-specific endpoints following this pattern:  
`https://{bucket-name}.{region}.oss-vectors.aliyuncs.com`

Common regions:
- `cn-hangzhou`
- `cn-shanghai`
- `cn-beijing`

### Synchronous Operations
All vector storage operations follow a synchronous request-response pattern:

1. Construct an HTTP request with the appropriate method (PUT/POST/GET/DELETE) and query parameters (e.g., `?putVectorIndex`)
2. Include required headers (`Host`, `Date`, `Authorization`, `Content-Type` for POST)
3. For POST requests, include a JSON body with operation-specific parameters
4. Send the request to the bucket-specific endpoint
5. Parse the JSON response or check HTTP status codes (200/204 for success)

No asynchronous polling or streaming is used in this API domain.

## Parameter Reference

### Manage Vector Bucket

| Parameter | Type | Required | Default | Constraints | Description |
|----------|------|----------|---------|-------------|-------------|
| prefix | string | false | - | - | Filters buckets by name prefix |
| marker | string | false | - | - | Pagination marker for listing buckets |
| max-keys | value | false | 100 | 1 to 1000 | Maximum buckets to return |

### Manage Vector Index

| Parameter | Type | Required | Default | Constraints | Description |
|----------|------|----------|---------|-------------|-------------|
| indexName | string | true | - | 1-63 chars, starts with letter | Custom index name |
| dataType | string | true | float32 | Must be 'float32' | Vector data type |
| dimension | integer | true | 512 | 1 to 4096 | Vector dimensions |
| distanceMetric | string | true | euclidean | euclidean / cosine | Distance measure function |
| nonFilterableMetadataKeys | array of strings | false | - | 1-10 entries, 1-63 bytes each | Non-filterable metadata keys |
| maxResults | Number | false | 100 | 0 to 500 | Max indexes to return |
| nextToken | String | false | - | - | Pagination token |

### Manage Vectors

| Parameter | Type | Required | Default | Constraints | Description |
|----------|------|----------|---------|-------------|-------------|
| indexName | string | true/false* | - | - | Target index name |
| keys | array/container | true | - | 1-500 unique keys | Vector primary keys to delete/get |
| returnData | boolean | false | false | true / false | Return vector data |
| returnMetadata | boolean | false | false | true / false | Return metadata |

*Required for GetVectors, optional for DeleteVectors

### Write Vector Data to Index

| Parameter | Type | Required | Default | Constraints | Description |
|----------|------|----------|---------|-------------|-------------|
| indexName | string | true | - | - | Target index name |
| vectors | container | true | - | 1-500 entries | Array of vectors to write |
| key | string | true | - | 1-1024 UTF-8 chars | Primary key (unique per vector) |
| float32 | array of numbers | true | - | Valid floats only | Vector data matching index dimension |
| metadata | container | false | - | Total ≤40KB, filterable ≤2KB | Metadata (string/string array) |

### Perform Vector Similarity Search

| Parameter | Type | Required | Default | Constraints | Description |
|----------|------|----------|---------|-------------|-------------|
| indexName | String | true | - | - | Target index name |
| queryVector | Container | true | - | Matches index dimension | Query vector data |
| topK | Number | true | 10 | 1-30 (up to 100 with support) | Number of results to return |
| filter | Container | false | - | ≤64KB, ≤1024 items, 8-level nesting | Metadata filter conditions |
| returnDistance | Boolean | false | false | true / false | Return similarity distances |
| returnMetadata | Boolean | false | false | true / false | Return metadata |

## Code Examples

### Create Vector Bucket - Bash - cn-hangzhou

```bash
PUT / HTTP/1.1
Host: examplebucket-123***456.cn-hangzhou.oss-vectors.aliyuncs.com
Date: Thu, 17 Apr 2025 03:15:40 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
```

### Create Vector Index - Bash - cn-hangzhou

```bash
POST /?putVectorIndex HTTP/1.1
Host: examplebucket-123***456.cn-hangzhou.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=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
Content-type: application/json

{
   "dataType": "float32",
   "dimension": 1024,
   "distanceMetric": "euclidean",
   "indexName": "vectorindex1",
   "metadata": { 
      "nonFilterableMetadataKeys": ["category", "timestamp"]
   }
}
```

### Write Vectors to Index - Bash - cn-hangzhou

```bash
POST /?putVectors HTTP/1.1
Host: examplebucket-123***456.cn-hangzhou.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=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
Content-type: application/json

{
   "indexName": "vectorindex1",
   "vectors": [
      {
         "key": "doc-001",
         "data": {
            "float32": [0.1, 0.2, 0.3, 0.4, 0.5]
         },
         "metadata": {
             "category": ["technology", "ai"],
             "title": "Introduction to Vector Search"
         }
      }
   ]
}
```

### Perform Vector Similarity Search - Bash - cn-hangzhou

```bash
POST /?queryVectors HTTP/1.1
Host: examplebucket-123***456.cn-hangzhou.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=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
Content-type: application/json

{
   "filter": {
       "$and": [{
           "category": {
               "$in": ["technology", "science"]
           }
       }, {
           "year": {
               "$eq": "2020"
           }
       }]
    },
   "indexName": "vectorindex1",
   "queryVector": {
       "float32": [0.15, 0.25, 0.35, 0.45, 0.55]
    },
   "returnDistance": true,
   "returnMetadata": true,
   "topK": 5
}
```

### List Vector Buckets - Bash - cn-hangzhou

```bash
GET /?prefix=my&marker=mybucket&max-keys=10 HTTP/1.1
Date: Thu, 15 May 2014 11:18:32 GMT
Host: cn-hangzhou.oss-vectors.aliyuncs.com
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=host,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
```

### Get Vector Index Details - Bash - all

```bash
POST /?getVectorIndex HTTP/1.1
Host: examplebucket-123***456.cn-hangzhou.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=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e

{
   "indexName": "vectorindex1"
}
```

## Response Format

```json
{
  "BucketInfo": {
      "CreationDate": "2013-07-31T10:56:21.000Z",
      "ExtranetEndpoint": "cn-hangzhou.oss-vectors.aliyuncs.com",
      "IntranetEndpoint": "cn-hangzhou-internal.oss-vectors.aliyuncs.com",
      "Location": "oss-cn-hangzhou",
      "Name": "acs:ossvector:cn-shanghai:103735**********:examplebucket",
      "Region": "cn-hangzhou"
    }
}
```

**Key Fields**:
- `BucketInfo.CreationDate` — Bucket creation timestamp
- `BucketInfo.ExtranetEndpoint` — Public access endpoint
- `BucketInfo.IntranetEndpoint` — Internal VPC endpoint
- `BucketInfo.Location` — OSS region identifier
- `BucketInfo.Name` — Full ARN of the bucket
- `BucketInfo.Region` — Region code

```json
{
   "index": { 
      "createTime": "2025-04-17T10:56:21.000Z",
      "dataType": "float32",
      "dimension": 1024,
      "distanceMetric": "euclidean",
      "metadata": { 
         "nonFilterableMetadataKeys": ["category", "timestamp"]
      },
      "status": "enable"
   }
}
```

**Key Fields**:
- `index.indexName` — Name of the vector index
- `index.createTime` — Index creation timestamp
- `index.dataType` — Vector data type (always float32)
- `index.dimension` — Vector dimensionality
- `index.distanceMetric` — Distance function (euclidean/cosine)
- `index.status` — Current index status (enable/disable)
- `index.metadata.nonFilterableMetadataKeys` — Configured metadata keys

```json
{
   "vectors": [ 
      { 
         "distance": 0.12,
         "key": "doc-001",
         "metadata": {
             "category": ["technology", "ai"],
             "title": "Introduction to Vector Search",
             "year": "2020"
         }
      }
   ]
}
```

**Key Fields**:
- `vectors[].key` — Primary key of the matching vector
- `vectors[].distance` — Similarity distance (lower = more similar)
- `vectors[].metadata` — Associated metadata fields

## Error Handling

| Error Code (Code) | Description (Description) | Recommended Action (Recommended Action) |
|-------------------|---------------------------|----------------------------------------|
| AccessDenied | You are not authorized to perform this operation. Only the owner can manage buckets/indexes. | Verify your RAM permissions and bucket policies; ensure you're using the correct AccessKey |
| InvalidVectorBucketName | The vector bucket name does not follow naming conventions. | Use 1-63 lowercase letters/digits, start with letter, no underscores/hyphens |
| VectorBucketNotEmpty | The vector bucket contains indexes and cannot be deleted. | Delete all indexes in the bucket first before deleting the bucket |
| NoSuchBucket | The specified vector bucket does not exist. | Verify bucket name and region; ensure bucket exists |
| NoSuchVectorIndex | The specified vector index does not exist. | Check index name spelling and confirm it exists in the bucket |
| VectorIndexParameterInvalid | Vector index parameters in the request are invalid. | Validate parameter values against constraints (e.g., dimension range) |
| MalformedJson | The JSON format of the request body is invalid. | Check JSON syntax and required field presence |
| VectorBucketIndexExceedLimit | Maximum 100 indexes per bucket limit reached. | Delete unused indexes or contact support for quota increase |
| VectorBucketIndexAlreadyExist | An index with this name already exists. | Use a different index name |
| QpsLimitExceeded | Request rate exceeds QPS limit (503 error). | Implement exponential backoff retry logic; reduce request frequency |
| TooManyBuckets | Maximum 10 buckets per region limit reached. | Delete unused buckets or use different regions |

### Rate Limits & Retry
- **Vector bucket creation**: Max 10 buckets per region per account
- **Vector index creation**: Max 100 indexes per bucket; 5 requests/second
- **ListVectorIndexes**: Max 16 concurrent calls
- **Vector operations (Put/Delete/Query)**: QPS limits apply (exact values not specified); 503 errors indicate throttling

**Retry strategy**: Implement exponential backoff with jitter for 5xx errors. For batch operations (PutVectors/DeleteVectors), note that writes are not atomic—partial success is possible during throttling.

## Environment Requirements

- **Authentication**: Set environment variables:
  ```bash
  export ALIBABA_CLOUD_ACCESS_KEY_ID=your_access_key_id
  export ALIBABA_CLOUD_ACCESS_KEY_SECRET=your_access_key_secret
  ```
- **Networking**: Ensure outbound HTTPS access to `*.oss-vectors.aliyuncs.com`
- **Clock synchronization**: System clock must be accurate (within 15 minutes) for signature validation

## FAQ

Q: How do I authenticate API requests to OSS Vector Storage?
A: Use OSS Signature Version 4 with your Alibaba Cloud AccessKey ID and Secret. The Authorization header must include your credentials formatted as `OSS4-HMAC-SHA256 Credential={AccessKeyID}/{Date}/{Region}/oss/aliyun_v4_request,Signature={Signature}`.

Q: What's the maximum number of vectors I can store in a single index?
A: Each vector index can store up to 50 million vectors. If you exceed this limit, you'll receive a VectorIndexParameterInvalid error.

Q: Can I filter search results by metadata during vector similarity search?
A: Yes, but only if you configured filterable metadata during index creation. The QueryVectors API supports complex filters using $and/$or operators with conditions like $eq, $in, etc., up to 64KB total filter size.

Q: Why am I getting "VectorBucketNotEmpty" when trying to delete a bucket?
A: You must delete all vector indexes in the bucket before deleting the bucket itself. Use ListVectorIndexes to identify existing indexes, then DeleteVectorIndex for each one.

Q: Are vector write operations atomic?
A: No. During high load or QPS limit exceeded scenarios (503 errors), batch write operations (PutVectors) may partially succeed—some vectors are written while others fail. Implement idempotent retries for reliability.

## Pricing & Billing

### Billing Model
Per-request pricing model. Each API call (create/delete/list buckets/indexes/vectors, query operations) is billed as a separate request.

### Price Reference

| Tier/Specification | Input Price | Output Price | Other Fees |
|--------------------|-------------|--------------|------------|
| default | 0.0001 / | 0.0001 / | - |
| ListVectorBuckets | 0 / | 0 / |

### Free Tier
- ListVectorBuckets: 1000 free requests per month
- Other operations: No free tier mentioned

### Usage Limits
- Single request response body: Max 8KB for GetVectorBucket
- ListVectorBuckets: Max 1000 buckets per response
- Vector index creation: Max 100 indexes per bucket
- Vector bucket creation: Max 10 buckets per region per account

### Billing Notes
- Request count determines cost, not data volume
- Response data size may affect costs for some operations (e.g., GetVectorBucket)
- No additional data transfer fees within Alibaba Cloud regions