VectorService API

Package: dodil.k3.vector.v1

VectorService owns vector engine lifecycle, vector collections, search, and external vector writes.

What It Is For

Configure vector infrastructure per bucket.
Create collection definitions (template-driven or manual).
Execute dense/hybrid search queries.
Write/delete external pre-embedded vectors.

Endpoint Map

Engine

gRPC method	HTTP route
`ConfigureEngine`	`POST /:bucket/vector`
`GetEngine`	`GET /:bucket/vector`
`DeleteEngine`	`DELETE /:bucket/vector`
`ListVBaseInstances`	`GET /admin/vbase-instances`

Collections

gRPC method	HTTP route
`AddVectorPipeline`	`POST /:bucket/vector/pipelines`
`AddVectorCollection`	`POST /:bucket/vector/collections`
`ListCollections`	`GET /:bucket/vector/collections`
`GetCollection`	`GET /:bucket/vector/collections/:collection_id`
`DeleteCollection`	`DELETE /:bucket/vector/collections/:collection_id`

Search and Writes

gRPC method	HTTP route
`Search`	`POST /:bucket/vector/search`
`Search` (compat)	`POST /:bucket/search/vector`
`InsertVectors`	`POST /:bucket/vector/collections/:collection_id/vectors`
`UpsertVectors`	`PUT /:bucket/vector/collections/:collection_id/vectors`
`DeleteVectors`	`POST /:bucket/vector/collections/:collection_id/vectors:delete`

Key Arguments

Configure engine

Field	Type	Required	Purpose
`bucket`	string	yes	Bucket scope
`mode`	string	yes	`auto`, `external`, or `pick`
`vbase_endpoint`	string	no	Required for external mode
`vbase_db_name`	string	no	Required for external mode
`vbase_port`	int32	no	External mode port
`service_id`	string	no	Existing instance for `pick` mode

AddVectorPipeline (template-driven)

Field	Type	Required	Purpose
`bucket`	string	yes	Bucket scope
`name`	string	yes	Collection name
`template_id`	string	yes	Scriptum template ID
`description`	string	no	Operator description
`template_inputs`	map<string,value>	no	Contract-driven runtime inputs

AddVectorCollection (manual schema)

Field	Type	Required	Purpose
`bucket`	string	yes	Bucket scope
`name`	string	yes	Collection name
`dimensions`	int32	yes	Vector dimension
`distance_metric`	enum	no	`COSINE` default, or `EUCLIDEAN`, `DOT_PRODUCT`
`embedding_type`	enum	no	`FLOAT` default; also binary/float16/bfloat16/int8
`sparse_mode`	enum	no	`NONE`, `BM25`, or `EXTERNAL`
`embed_model`	string	no	Query-side embedding model hint

Search request

Field	Type	Required	Purpose
`bucket`	string	yes	Bucket scope
`query`	oneof	yes	`text`, `vector`, or `s3_key`
`collection_name`	string	no	Restrict to one collection
`top_k`	int32	no	Max result count (default 10)
`min_score`	float	no	Score threshold
`search_mode`	enum	no	`VECTOR`, `HYBRID`, `AUTO`
`rerank`	bool	no	Enable reranker
`include_content`	bool	no	Include chunk text
`include_highlights`	bool	no	Include highlight snippets
`pre_filter`	object	no	Metadata filter tree
`source_ids`	string[]	no	Restrict by source IDs

External vector writes

These endpoints require collections in external mode (embedding_source=EXTERNAL).

VectorRecord key fields:

Field	Type	Required	Purpose
`id`	string	yes	Caller-provided vector primary key
`dense_*`	oneof	yes	Dense payload matching collection embedding type
`sparse`	sparse vector	conditional	Required when `sparse_mode=EXTERNAL`
`text`	string	conditional	Used for BM25 sparse mode
`metadata`	struct	no	Filterable metadata

Examples

Configure auto engine


curl -sS -X POST "https://k3.dev.dodil.io/kb-prod/vector" \
  -H "Authorization: Bearer $K3_TOKEN" \
  -H "x-organization-id: $K3_ORG" \
  -H "Content-Type: application/json" \
  -d '{"bucket":"kb-prod","mode":"auto"}'

Create pipeline-driven collection


curl -sS -X POST "https://k3.dev.dodil.io/kb-prod/vector/pipelines" \
  -H "Authorization: Bearer $K3_TOKEN" \
  -H "x-organization-id: $K3_ORG" \
  -H "Content-Type: application/json" \
  -d '{
    "bucket": "kb-prod",
    "name": "contracts-embeddings",
    "template_id": "object_embedding_index"
  }'

Search by text


curl -sS -X POST "https://k3.dev.dodil.io/kb-prod/vector/search" \
  -H "Authorization: Bearer $K3_TOKEN" \
  -H "x-organization-id: $K3_ORG" \
  -H "Content-Type: application/json" \
  -d '{
    "bucket": "kb-prod",
    "text": "termination clause notice period",
    "collection_name": "contracts-embeddings",
    "top_k": 8,
    "min_score": 0.2,
    "include_content": true
  }'

Upsert external vectors


curl -sS -X PUT "https://k3.dev.dodil.io/kb-prod/vector/collections/col_ext/vectors" \
  -H "Authorization: Bearer $K3_TOKEN" \
  -H "x-organization-id: $K3_ORG" \
  -H "Content-Type: application/json" \
  -d '{
    "bucket": "kb-prod",
    "collection_id": "col_ext",
    "vectors": [
      {
        "id": "doc-1#chunk-1",
        "dense_float": {"values": [0.11, 0.52, 0.07]},
        "metadata": {"source": "contracts", "year": 2026}
      }
    ]
  }'

Common Use Cases

Build RAG retrieval with text search over chunked documents.
Support external embedding pipelines that write vectors directly.
Run hybrid retrieval with filters and reranking for enterprise search.

Next: TableService