---
Title: Manage data
URL Source: https://company-skill.com/p/oss/oss-manage-data
Language: en
Description: You want to store, index, and retrieve high-dimensional vector data (e.g., embeddings) in Alibaba Cloud OSS, enabling similarity search with optional metadata filtering. This includes creating vector…
---

# Manage data

Part of **Object Storage Service (OSS)**. Route queries via `POST https://company-skill.com/api/route`.

## What You Want to Do

You want to store, index, and retrieve high-dimensional vector data (e.g., embeddings) in Alibaba Cloud OSS, enabling similarity search with optional metadata filtering. This includes creating vector buckets, defining vector indexes with specific `dimension`, `distanceMetric`, and `float32` format, inserting vectors using a `primary key`, and querying for `topK` nearest neighbors.

**Typical User Questions**:
- How to create a vector index in OSS?
- Can I perform similarity search via API?

## Decision Tree

Pick the best path for your situation:

- **If** you are building an AI/ML application that requires programmatic integration of vector storage and real-time similarity search using APIs like `PutVectorIndex` or `QueryVectors` → Use API (go to *oss/oss-vector*)
- **If** you are a data engineer performing offline batch operations (e.g., importing training datasets) using terminal commands like `ossutil put-vectors` → Use CLI (go to *oss/oss-vector*)
- **If** you need parallel listing of vectors using `segmentCount` up to 16 → Use API (go to *oss/oss-vector*)
- **Otherwise (default)** → Start with the **CLI path** if you lack programming resources or prefer scripting without implementing HTTP request signing; otherwise, use the **API path** for production AI applications.

## Path Comparison

| Path | Best For | Complexity | Code Required | Automation | Key Fact | Detail Skill |
|------|----------|------------|---------------|------------|----------|-------------|
| API | AI | high | Yes | Yes | Max 16 concurrent segments for listing vectors (`max_concurrency: 16`) | `oss/api/oss-vector` |
| CLI | medium | No | Yes | Requires `ossutil` installation and configuration | `oss/cli/oss-vector` |

## Path Details

### Path 1: API

**Best For**: AI

**Brief Description**: OSS Vector Storage API is a synchronous HTTP service that enables full lifecycle management of vector buckets and indexes. You can use `PutVectorIndex` to define a `vector index` with parameters like `dimension`, `distanceMetric`, and `nonFilterableMetadataKeys`, then insert vectors as `float32` arrays and run similarity searches via `QueryVectors` with `metadata filtering` and `topK` results.

**Key technical facts**:
- Billing: Per-request pricing model. Each API call (create/delete/list buckets/indexes/vectors, query operations) is billed as a separate request.
- Auth method: OSS Signature Version 4 using AccessKey credentials
- Regions available: cn-hangzhou, cn-shanghai, cn-beijing
- Max concurrency: 16

**When to Use**:
- Need programmatic integration of vector storage and similarity search in AI applications
- Require fine-grained control over vector index configuration (dimension, distance metric, metadata)
- Building automated workflows that require direct API calls for vector operations
- Need parallel processing support for listing vectors (segmentCount up to 16)

**When NOT to Use**:
- Prefer command-line interface for batch operations without writing code
- Need interactive exploration of vector data through CLI tools
- Lack programming resources to implement HTTP request signing and JSON payload construction

**Known Limitations**:
- Vector write operations are not atomic — during QPS limit exceeded scenarios (503 errors), batch operations may partially succeed
- Each vector index can store up to 50 million vectors — exceeding this limit returns VectorIndexParameterInvalid error
- Maximum 100 vector indexes per bucket
- Maximum 10 vector buckets per region per account
- `topK` parameter in `QueryVectors` is limited to 1-30 by default (can be increased to 100 with support)
- Metadata filter size in `QueryVectors` is limited to 64KB total with ≤1024 items and 8-level nesting

### Path 2: CLI

**Brief Description**: The `ossutil` command-line tool provides CLI equivalents for vector operations, including `put-vector-index` to create a `vector index` inside a `vector bucket`, `put-vectors` to insert data with a `primary key`, and `query-vectors` to retrieve `top-k results` with `metadata filtering`. It abstracts away HTTP signing but uses the same underlying OSS Vector Storage service.

**Key technical facts**:
- Billing: Per-request pricing model. Each CLI command execution results in API calls that are billed as separate requests.
- Auth method: OSS Signature Version 4 using AccessKey credentials configured in ossutil
- Prerequisites: `ossutil` command line tool installed and configured

**When to Use**:
- Data engineers need to perform batch import or query operations from command line
- Prefer scripting vector operations without implementing HTTP request signing logic
- Need quick ad-hoc queries and management of vector data through terminal commands
- Working in environments where CLI tools are preferred over custom code implementation

**When NOT to Use**:
- Building production AI applications requiring programmatic integration
- Need fine-grained control over HTTP request parameters not exposed in CLI flags
- Require parallel processing capabilities for vector listing (segmentCount parameter)
- Working in environments where installing additional CLI tools is restricted

**Known Limitations**:
- Limited to functionality exposed through `ossutil` commands — cannot access features only available via direct API calls
- Batch operations limited to same constraints as API (e.g., 500 vectors per `put-vectors` call)
- No explicit documentation of CLI-specific rate limits beyond underlying API limits
- Requires installation and configuration of `ossutil` tool before use

## FAQ

Q: Which path should I start with?
A: If you're building an AI application that needs embedded vector search, start with the API path. If you're a data engineer doing one-off imports or exploratory queries, start with the CLI path using `ossutil`.

Q: What if I need to list millions of vectors efficiently but used the CLI path?
A: You’ll miss out on parallel listing via `segmentCount` (max 16 segments), which is only available in the API path’s `ListVectors` operation — the CLI doesn’t expose this parameter.

Q: What if I exceed 50 million vectors per index but chose either path?
A: Both paths share the same backend limits — you’ll receive a `VectorIndexParameterInvalid` error regardless of API or CLI usage, since the 50M vector limit is enforced at the service level.

Q: Can I use metadata filtering with non-filterable fields in the CLI?
A: Yes, but you must declare `non-filterable metadata` keys when creating the index via `put-vector-index`; the CLI supports the same metadata model as the API, including 64KB filter size limits.

Q: What happens if my system clock is off by more than 15 minutes and I use the API path?
A: Request signatures will fail validation due to `OSS Signature Version 4` requirements, resulting in authentication errors — ensure your system clock is synchronized.

Q: Can I avoid writing code for production vector search by using the CLI?
A: Not recommended — the CLI lacks fine-grained control over request parameters and isn’t designed for embedding in applications; you’ll hit limitations in error handling, retry logic, and performance tuning.

Q: Does the CLI support `float32` vectors with custom `dimension` and `distanceMetric`?
A: Yes — when you run `put-vector-index`, you specify `dimension`, `distanceMetric`, and vector format just like in the API, because `ossutil` wraps the same underlying service.

## Related queries

manage vector data, manage vector index, store vectors in OSS, create vector index in OSS, perform similarity search via API, CLI tool for vector management, OSS vector retrieval support, insert vectors into index, vector storage OSS, how to query vectors, vector similarity search OSS, batch import

---
Part of [Object Storage Service (OSS)](https://company-skill.com/p/oss.md) · https://company-skill.com/llms.txt