# oss-vector_storage

Part of **OSS**

# Object Storage Service Vector Storage CLI Reference

## Command Overview

| Command | Purpose | Syntax |
|--------|---------|--------|
| put-vector-bucket | Create a vector bucket | `ossutil vectors-api put-vector-bucket --bucket <name> [flags]` |
| get-vector-bucket | Retrieve vector bucket details | `ossutil vectors-api get-vector-bucket --bucket <name> [flags]` |
| list-vector-buckets | List all vector buckets | `ossutil vectors-api list-vector-buckets [flags]` |
| delete-vector-bucket | Delete a vector bucket | `ossutil vectors-api delete-vector-bucket --bucket <name>` |
| put-vector-index | Create a vector index | `ossutil vectors-api put-vector-index --bucket <b> --index-name <i> [flags]` |
| get-vector-index | Retrieve vector index details | `ossutil vectors-api get-vector-index --bucket <b> --index-name <i>` |
| list-vector-indexes | List indexes in a bucket | `ossutil vectors-api list-vector-indexes --bucket <b> [flags]` |
| delete-vector-index | Delete a vector index | `ossutil vectors-api delete-vector-index --bucket <b> --index-name <i>` |
| put-vectors | Write vector data to an index | `ossutil vectors-api put-vectors --bucket <b> --index-name <i> --vectors <data>` |
| get-vectors | Retrieve specific vectors by key | `ossutil vectors-api get-vectors --bucket <b> --index-name <i> --keys <k1,k2,...> [flags]` |
| list-vectors | List vectors in an index | `ossutil vectors-api list-vectors --bucket <b> --index-name <i> [flags]` |
| delete-vectors | Delete vectors by primary key | `ossutil vectors-api delete-vectors --bucket <b> --index-name <i> --keys <k1,k2,...>` |
| query-vectors | Perform similarity search | `ossutil vectors-api query-vectors --bucket <b> --index-name <i> --query-vector <v> --top-k <n> [flags]` |

## Command Details

### put-vector-bucket

**Purpose**: Create a new vector bucket in Object Storage Service.

**Syntax**:
```bash
ossutil vectors-api put-vector-bucket --bucket <bucket-name> [flags]
```

| Parameter | Short | Type | Required | Description |
|----------|-------|------|----------|-------------|
| --bucket | — | string | Yes | The name of the vector bucket (3–32 chars; lowercase letters, digits, hyphens; cannot start/end with hyphen) |
| --account-id | — | string | Yes | The account ID. Must be set via config file or CLI option along with region |

```bash
# Create a vector bucket named 'my-ai-bucket'
ossutil vectors-api put-vector-bucket --bucket my-ai-bucket --account-id 1234567890
```

### get-vector-bucket

**Purpose**: Retrieve detailed information about a vector bucket.

**Syntax**:
```bash
ossutil vectors-api get-vector-bucket --bucket <bucket-name> [--output-format <format>]
```

| Parameter | Short | Type | Required | Description |
|----------|-------|------|----------|-------------|
| --bucket | — | string | Yes | The name of the vector bucket |
| --output-format | — | string | No | Output format: 'xml', 'yaml', or 'json' (default) |

```bash
# Get bucket info in default JSON format
ossutil vectors-api get-vector-bucket --bucket examplebucket

# Get bucket info in XML format
ossutil vectors-api get-vector-bucket --bucket examplebucket --output-format xml
```

### list-vector-buckets

**Purpose**: List all vector buckets in the current account.

**Syntax**:
```bash
ossutil vectors-api list-vector-buckets [--prefix <p>] [--marker <m>] [--max-keys <n>]
```

| Parameter | Short | Type | Required | Description |
|----------|-------|------|----------|-------------|
| --prefix | — | string | No | Filter buckets whose names start with this prefix |
| --marker | — | string | No | Start listing after this bucket name (for pagination) |
| --max-keys | — | integer | No | Max number of buckets to return (1–1000; default: 100) |

```bash
# List all vector buckets
ossutil vectors-api list-vector-buckets

# List buckets starting with 'prod-'
ossutil vectors-api list-vector-buckets --prefix prod-

# Limit results to 50 buckets
ossutil vectors-api list-vector-buckets --max-keys 50
```

### delete-vector-bucket

**Purpose**: Delete an existing vector bucket (must be empty).

**Syntax**:
```bash
ossutil vectors-api delete-vector-bucket --bucket <bucket-name>
```

| Parameter | Short | Type | Required | Description |
|----------|-------|------|----------|-------------|
| --bucket | — | string | Yes | The name of the vector bucket to delete |

```bash
# Delete the vector bucket 'temp-bucket'
ossutil vectors-api delete-vector-bucket --bucket temp-bucket
```

### put-vector-index

**Purpose**: Create a vector index inside a vector bucket with configurable properties.

**Syntax**:
```bash
ossutil vectors-api put-vector-index --bucket <b> --index-name <i> [flags]
```

| Parameter | Short | Type | Required | Description |
|----------|-------|------|----------|-------------|
| --bucket | — | string | Yes | The name of the vector bucket |
| --index-name | — | string | Yes | Index name (1–63 chars; letters/digits; must start with letter) |
| --data-type | — | string | No | Vector data type (only 'float32'; default: float32) |
| --dimension | — | integer | No | Vector dimensions (1–4096; default: 512) |
| --distance-metric | — | string | No | Distance function: 'euclidean' or 'cosine' (default: euclidean) |
| --metadata | — | string | No | Non-filterable metadata keys as JSON string |

```bash
# Create a basic index with default settings
ossutil vectors-api put-vector-index --bucket examplebucket --index-name image-embeddings

# Create an index for cosine similarity with custom metadata
ossutil vectors-api put-vector-index --bucket examplebucket --index-name text-embeddings \
  --data-type float32 --dimension 768 --distance-metric cosine \
  --metadata '{"nonFilterableMetadataKeys":["author","source"]}'
```

### get-vector-index

**Purpose**: Retrieve configuration and status of a vector index.

**Syntax**:
```bash
ossutil vectors-api get-vector-index --bucket <b> --index-name <i>
```

| Parameter | Short | Type | Required | Description |
|----------|-------|------|----------|-------------|
| --bucket | — | string | Yes | The name of the vector bucket |
| --index-name | — | string | Yes | The name of the index |

```bash
# Get details of the 'image-embeddings' index
ossutil vectors-api get-vector-index --bucket examplebucket --index-name image-embeddings
```

### list-vector-indexes

**Purpose**: List all vector indexes in a specified bucket.

**Syntax**:
```bash
ossutil vectors-api list-vector-indexes --bucket <b> [--prefix <p>] [--max-results <n>] [--next-token <t>]
```

| Parameter | Short | Type | Required | Description |
|----------|-------|------|----------|-------------|
| --bucket | — | string | Yes | The name of the vector bucket |
| --prefix | — | string | No | Filter indexes by name prefix |
| --max-results | — | integer | No | Max indexes to return (0–500; default: 100) |
| --next-token | — | string | No | Pagination token from previous response (1–512 bytes) |

```bash
# List all indexes in 'examplebucket'
ossutil vectors-api list-vector-indexes --bucket examplebucket

# List indexes starting with 'prod-'
ossutil vectors-api list-vector-indexes --bucket examplebucket --prefix prod-

# Paginate results using next-token
ossutil vectors-api list-vector-indexes --bucket examplebucket --next-token CAESCG15aC1xxxxx
```

### delete-vector-index

**Purpose**: Delete a vector index and all its data.

**Syntax**:
```bash
ossutil vectors-api delete-vector-index --bucket <b> --index-name <i>
```

| Parameter | Short | Type | Required | Description |
|----------|-------|------|----------|-------------|
| --bucket | — | string | Yes | The name of the vector bucket |
| --index-name | — | string | Yes | The name of the index to delete |

```bash
# Delete the 'temp-index' from 'examplebucket'
ossutil vectors-api delete-vector-index --bucket examplebucket --index-name temp-index
```

### put-vectors

**Purpose**: Write vector data (with optional metadata) into a vector index.

**Syntax**:
```bash
ossutil vectors-api put-vectors --bucket <b> --index-name <i> --vectors <data>
```

| Parameter | Short | Type | Required | Description |
|----------|-------|------|----------|-------------|
| --bucket | — | string | Yes | The name of the vector bucket |
| --index-name | — | string | Yes | The name of the index |
| --vectors | — | string | Yes | JSON array of vectors or file path prefixed with `file://` |

```bash
# Insert vectors from a local JSON file
ossutil vectors-api put-vectors --bucket examplebucket --index-name embeddings --vectors file://vectors.json

# Insert inline vector data
ossutil vectors-api put-vectors --bucket examplebucket --index-name embeddings \
  --vectors "[{\"data\":{\"float32\":[1.0,2.0]},\"key\":\"vec1\",\"metadata\":{\"category\":\"A\"}}]"
```

### get-vectors

**Purpose**: Retrieve specific vectors by their primary keys.

**Syntax**:
```bash
ossutil vectors-api get-vectors --bucket <b> --index-name <i> --keys <k1,k2,...> [flags]
```

| Parameter | Short | Type | Required | Description |
|----------|-------|------|----------|-------------|
| --bucket | — | string | Yes | The name of the vector bucket |
| --index-name | — | string | Yes | The name of the index |
| --keys | — | strings | Yes | Comma-separated list of primary keys (1–100 unique keys) |
| --return-data | — | — | No | Return vector data if true or omitted (default: true) |
| --return-metadata | — | — | No | Return metadata if true or omitted (default: true) |

```bash
# Retrieve vectors with keys 'doc1' and 'doc2'
ossutil vectors-api get-vectors --bucket examplebucket --index-name embeddings --keys doc1,doc2

# Retrieve only metadata (no vector data)
ossutil vectors-api get-vectors --bucket examplebucket --index-name embeddings --keys doc1 --return-metadata
```

### list-vectors

**Purpose**: List vectors in an index with pagination and optional data/metadata control.

**Syntax**:
```bash
ossutil vectors-api list-vectors --bucket <b> --index-name <i> [flags]
```

| Parameter | Short | Type | Required | Description |
|----------|-------|------|----------|-------------|
| --bucket | — | string | Yes | The name of the vector bucket |
| --index-name | — | string | Yes | The name of the index |
| --max-results | — | integer | No | Max results per response (default: 500; max: 1000) |
| --next-token | — | string | No | Pagination token (1–512 bytes) |
| --return-data | — | — | No | Return vector data if true or omitted (default: true) |
| --return-metadata | — | — | No | Return metadata if true or omitted (default: true) |
| --segment-count | — | integer | No | Parallelism degree (max: 16; default: serial) |
| --segment-index | — | integer | No | Segment index (must be < segment-count) |

```bash
# List first 100 vectors with data and metadata
ossutil vectors-api list-vectors --bucket examplebucket --index-name embeddings --max-results 100

# Continue listing using next-token
ossutil vectors-api list-vectors --bucket examplebucket --index-name embeddings --next-token abc123xyz
```

### delete-vectors

**Purpose**: Delete vectors by their primary keys (batch operation).

**Syntax**:
```bash
ossutil vectors-api delete-vectors --bucket <b> --index-name <i> --keys <k1,k2,...>
```

| Parameter | Short | Type | Required | Description |
|----------|-------|------|----------|-------------|
| --bucket | — | string | Yes | The name of the vector bucket |
| --index-name | — | string | Yes | The name of the index |
| --keys | — | strings | Yes | Comma-separated primary keys (1–500 unique keys) |

```bash
# Delete vectors with keys 'old1' and 'old2'
ossutil vectors-api delete-vectors --bucket examplebucket --index-name embeddings --keys old1,old2
```

### query-vectors

**Purpose**: Perform similarity search against a vector index.

**Syntax**:
```bash
ossutil vectors-api query-vectors --bucket <b> --index-name <i> --query-vector <v> --top-k <n> [flags]
```

| Parameter | Short | Type | Required | Description |
|----------|-------|------|----------|-------------|
| --bucket | — | string | Yes | The name of the vector bucket |
| --index-name | — | string | Yes | The name of the index |
| --query-vector | — | string | Yes | Query vector as JSON (e.g., `{"float32":[1.0,2.0]}`) |
| --top-k | — | integer | Yes | Number of nearest neighbors to return (1–30) |
| --filter | — | string | No | Metadata filter in JSON format (max 64 KB) |
| --return-distance | — | — | No | Return similarity distance if true or omitted |
| --return-metadata | — | — | No | Return metadata if true or omitted |

```bash
# Find top 5 similar vectors
ossutil vectors-api query-vectors --bucket examplebucket --index-name embeddings \
  --query-vector '{"float32":[0.5,1.2]}' --top-k 5

# Apply metadata filter and return distances
ossutil vectors-api query-vectors --bucket examplebucket --index-name embeddings \
  --query-vector '{"float32":[0.5,1.2]}' --top-k 10 \
  --filter '{"$and":[{"category":{"$in":["tech","science"]}}]}' --return-distance
```

## Common Scenarios

### Scenario 1: Set Up Vector Search Pipeline
```bash
# Step 1: Create a vector bucket
ossutil vectors-api put-vector-bucket --bucket my-ai-bucket --account-id 1234567890

# Step 2: Create a vector index for document embeddings
ossutil vectors-api put-vector-index --bucket my-ai-bucket --index-name doc-embeddings \
  --dimension 768 --distance-metric cosine

# Step 3: Upload vector data from file
ossutil vectors-api put-vectors --bucket my-ai-bucket --index-name doc-embeddings --vectors file://docs.json

# Step 4: Perform a similarity search
ossutil vectors-api query-vectors --bucket my-ai-bucket --index-name doc-embeddings \
  --query-vector '{"float32":[0.1,0.9,0.85,...]}' --top-k 5 --return-metadata
```

### Scenario 2: Manage and Inspect Vector Data
```bash
# Step 1: List all vector buckets
ossutil vectors-api list-vector-buckets

# Step 2: List indexes in a specific bucket
ossutil vectors-api list-vector-indexes --bucket my-ai-bucket

# Step 3: Retrieve index configuration
ossutil vectors-api get-vector-index --bucket my-ai-bucket --index-name doc-embeddings

# Step 4: Sample vector data
ossutil vectors-api list-vectors --bucket my-ai-bucket --index-name doc-embeddings --max-results 10
```

## Environment Setup

### Installation
Install the `ossutil` CLI tool version 2.0 or later from the official Object Storage Service documentation. Ensure it supports the `vectors-api` subcommand.

### Configuration
Configure your credentials and region using:
```bash
ossutil config
```
Provide your AccessKey ID, AccessKey Secret, and default region. The `--account-id` may also be required for vector operations and can be set in the config file or passed per-command.

Authentication uses bearer token headers derived from your configured credentials. Ensure your RAM user or role has permissions for vector bucket and index operations (e.g., `oss:PutVectorBucket`, `oss:PutVectorIndex`, `oss:PutVectors`, `oss:QueryVectors`).

## FAQ

Q: How do I configure credentials for vector storage CLI commands?
A: Use `ossutil config` to set your AccessKey ID, AccessKey Secret, and region. The tool automatically uses these for authentication. For vector operations, you may also need to specify `--account-id` unless it's set in the config file.

Q: What is the difference between `get-vectors` and `list-vectors`?
A: `get-vectors` retrieves specific vectors by known primary keys (point lookup), while `list-vectors` scans the index sequentially (with pagination) and is used for enumeration or bulk export.

Q: How do I handle large batch vector uploads?
A: Use the `--vectors file://path/to/file.json` option with `put-vectors`. The input file must contain a JSON array of vector objects. Each batch can contain up to 1000 vectors, and the total data size must not exceed 8192 characters per request.

Q: What are common error messages and how to fix them?
A: 
- "Bucket does not exist": Ensure the vector bucket was created with `put-vector-bucket`.
- "Index not found": Verify the index exists using `list-vector-indexes`.
- "Invalid vector dimension": The query vector dimension must match the index dimension set during creation.
- "Permission denied": Check RAM policies for required vector operation permissions.

Q: How do I verify that a vector operation succeeded?
A: Most commands return no output on success. To confirm, use `get-vectors` or `list-vectors` to check if data exists, or `get-vector-index` to verify index properties. Enable verbose logging with global `ossutil` flags if needed.