S3 Vector Buckets — API and Operations
This reference covers the base S3 Vectors service. Start with the Vector Buckets guide for a local example, or see the Distributed Vector Search reference for Enterprise query placement and engine pools.
Endpoint and components
| Component | Role |
|---|---|
| S3 gateway | Serves S3 Vectors requests on the normal S3 listener, commonly :8333. Routes requests signed for the s3vectors service to the vector API. |
| Masters | Discover registered vector engines; the gateway and engine use the same cluster and filer group. |
weed-vector |
Handles index management, vector writes, and single-engine queries. Reads and writes Lance table data through filers and volume servers. |
| Lance maintenance worker | Builds and refreshes ANN indexes. Queries can scan data before indexing finishes. |
weed-vector-worker |
Optional Enterprise search pool for distributed QueryVectors; it does not replace the write engine. |
Point an AWS SDK s3vectors client or aws s3vectors command at the S3 endpoint. A separate public Lance Namespace listener is not required for S3 Vectors: the gateway resolves index tables through its in-process catalog. Vector buckets use Lance table-bucket storage, with API-managed indexes in the reserved vector namespace.
Supported operations
The gateway implements these 19 operations:
| Resource | Operations |
|---|---|
| Buckets | CreateVectorBucket, GetVectorBucket, ListVectorBuckets, DeleteVectorBucket |
| Bucket policies | PutVectorBucketPolicy, GetVectorBucketPolicy, DeleteVectorBucketPolicy |
| Indexes | CreateIndex, GetIndex, ListIndexes, DeleteIndex |
| Vectors | PutVectors, GetVectors, ListVectors, DeleteVectors, QueryVectors |
| Tags | TagResource, UntagResource, ListTagsForResource |
Requests use the S3 Vectors JSON shapes and SigV4 service name s3vectors. See the official AWS CLI command reference for client syntax.
Index and vector fields
| Field | SeaweedFS behavior |
|---|---|
dataType |
float32. |
dimension |
1–4096. Stored and query vectors must match the index’s dimension. |
distanceMetric |
cosine or euclidean. |
Vector key |
Identifies the vector within its index. |
Vector data |
JSON such as {"float32":[1,0,0]}. |
Vector metadata |
Optional values returned or used in query filters. |
metadataConfiguration.nonFilterableMetadataKeys |
Keys stored for retrieval but rejected in query filters. |
Query topK |
1–10000. |
Query returnDistance, returnMetadata |
Request distances and metadata in query results. |
Choose the dimension, metric, and non-filterable keys when creating the index. For a different embedding model or dimension, create a new index and populate it with matching embeddings.
Local cluster flags
weed mini -vector starts the separate engine as a child process. The binary must already be installed.
| Flag | Default | Purpose |
|---|---|---|
-vector |
false |
Start the vector engine with the mini cluster. |
-vector.binary |
weed-vector |
Engine executable; mini also looks beside its own binary. |
-vector.port |
8090 |
Engine gRPC port. |
-vector.metricsPort |
0 |
Optional engine HTTP health and metrics port. |
-vectorBucket |
Empty | Comma-separated vector buckets to create at startup; falls back to S3_VECTOR_BUCKET. |
For example, weed mini -vector -vectorBucket=embeddings creates the vector bucket and starts its engine. -tableBucket=embeddings:LANCE also creates storage that the vector API can use once the engine is running. An Iceberg table bucket cannot be used as a vector bucket.
Separate engine
weed-vector --masters=10.0.0.1:9333,10.0.0.2:9333 \
--listen=0.0.0.0:8090 --advertise=10.0.0.20:8090 \
--metrics-port=9329 --metrics-ip=127.0.0.1
The advertised engine address must be reachable by gateways. Apply the cluster’s mutual TLS and authentication configuration when deploying across hosts.
| Engine setting | Default | Purpose |
|---|---|---|
--masters |
Required | Master addresses used for registration and discovery. |
--listen |
127.0.0.1:8090 |
Engine gRPC listener. |
--advertise |
Derived from listener | Reachable engine address registered with the masters. |
--filer-group |
Empty | Filer group used for storage. |
--read-cache-mb |
512 |
Cache immutable data and index reads; 0 disables it. |
--index-cache-mb |
1024 |
Indexes loaded by queries, kept for the next read. |
--metadata-cache-mb |
256 |
Table metadata (manifests, file footers) kept across reads. |
--nprobes |
Automatic | ANN partitions searched per query. |
--metrics-port |
0 |
HTTP health/metrics listener; 0 disables it. |
--metrics-ip |
127.0.0.1 |
HTTP listener address. |
--security-toml |
Discovered | Cluster certificates, signing keys, and encryption keys. |
Configure [grpc.vector] for the engine’s server identity, [grpc.client] for master and filer connections, and [https.client] for HTTPS volume reads. See the engine README and maintenance worker README for deployment details.
IAM and administration
Authorize requests with s3vectors:* IAM actions and vector bucket policies. Vector bucket and index ARNs use the s3vectors service, rather than ordinary S3 object ARNs. Tagging uses the resource-tag operations in the table above.
SeaweedFS checks the operation’s s3vectors action against the vector bucket or index resource. Use the s3vectors actions and resource ARNs when writing application IAM policies for this API.
The Admin UI provides Vector Buckets and index management pages. For trusted cluster administration, weed shell also supports the API’s operation names and JSON request shapes:
s3vectors -operation ListVectorBuckets
s3vectors -operation GetIndex -request '{"vectorBucketName":"embeddings","indexName":"documents"}'
s3vectors -operation QueryVectors -file query.json
The shell uses trusted cluster credentials, so it is an operator tool rather than a replacement for testing an application’s IAM policy.
Health and metrics
With the engine’s HTTP listener enabled, /health, /ready, and /metrics are available. Readiness requires an active registration with the master. Keep these unauthenticated endpoints on an internal interface or restrict network access.
- Engine metrics use
SeaweedFS_vector_: registration, requests, latency, in-flight requests, returned vectors, cache activity, and storage reads. - Gateway request metrics use
SeaweedFS_s3_withtype="s3vectors.<Operation>". - Scrape both to distinguish API latency from engine work. The monitoring guide covers the cluster’s other metrics.