Api Vector - SoliDB Documentation

Vector Index Management

POST /_api/database/:db/vector/:collection

Create a new vector index for similarity search on an embedding field.

Request Body

Field	Type	Description	Required
name	string	Unique name for the vector index.	Yes
field	string	Document field containing embedding vectors.	Yes
dimension	integer	Vector dimension (e.g., 1536 for OpenAI embeddings).	Yes
metric	string	Distance metric: `cosine` (default), `euclidean`, `dot`.	No
quantization	string	Compression method: `none` (default), `scalar` (4x memory reduction).	No

Example Request

{ "name": "embedding_idx", "field": "embedding", "dimension": 1536, "metric": "cosine", "quantization": "scalar" }

Response

201 Created

{ "name": "embedding_idx", "field": "embedding", "dimension": 1536, "metric": "cosine", "quantization": "scalar", "indexed_vectors": 0, "memory_bytes": 0, "compression_ratio": 4.0 }

GET /_api/database/:db/vector/:collection

List all vector indexes for a collection.

Response

200 OK

{ "indexes": [ { "name": "embedding_idx", "field": "embedding", "dimension": 1536, "metric": "Cosine", "indexed_vectors": 15420 } ] }

DELETE /_api/database/:db/vector/:collection/:name

Delete a vector index.

Path Parameters

Parameter	Description
db	Database name
collection	Collection name
name	Vector index name to delete

Response

200 OK

{ "deleted": true, "name": "embedding_idx" }

Vector Quantization

POST /_api/database/:db/vector/:collection/:index/quantize

Apply scalar quantization to an existing vector index for 4x memory reduction. Vectors are compressed from f32 (4 bytes/dim) to u8 (1 byte/dim).

Path Parameters

Parameter	Description
db	Database name
collection	Collection name
index	Vector index name to quantize

Example Request

curl -X POST \ http://localhost:6745/_api/database/mydb/vector/articles/embedding_idx/quantize

Response

200 OK

{ "name": "embedding_idx", "vectors_quantized": 15420, "memory_before": 94494720, "memory_after": 23623680, "compression_ratio": 4.0, "status": "quantized" }

Asymmetric Search

After quantization, searches use asymmetric distance computation: query vectors remain at full f32 precision while database vectors are stored as u8. This maintains ~98% recall while achieving 4x compression.

POST /_api/database/:db/vector/:collection/:index/dequantize

Remove quantization from a vector index, reverting to full f32 precision search.

Example Request

curl -X POST \ http://localhost:6745/_api/database/mydb/vector/articles/embedding_idx/dequantize

Response

200 OK

{ "name": "embedding_idx", "status": "dequantized" }

Vector Similarity Search

POST /_api/database/:db/vector/:collection/:index/search

Perform a similarity search to find the nearest vectors to a query vector.

Path Parameters

Parameter	Description
db	Database name
collection	Collection containing documents with vectors
index	Name of the vector index to search

Request Body

Field	Type	Description	Required
vector	array[float]	Query vector (must match index dimension).	Yes
limit	integer	Maximum number of results to return. Default: 10.	No
ef_search	integer	HNSW search quality parameter. Higher values improve recall but increase latency. Only used when HNSW is active (>10K vectors). Default: max(limit*2, 40).	No

Example Request

{ "vector": [0.0123, -0.0456, 0.0789, ...], "limit": 10, "ef_search": 100 }

Response

200 OK

{ "results": [ { "doc_key": "article_001", "score": 0.9823 }, { "doc_key": "article_042", "score": 0.9654 }, { "doc_key": "article_017", "score": 0.9412 } ] }

Score Interpretation

For cosine metric, scores range from -1 to 1 (higher = more similar). For euclidean, scores are distances (lower = more similar). For dot product, higher scores indicate more similarity.

Hybrid Search (Vector + Fulltext)

POST /_api/database/:db/hybrid/:collection/search

Combine vector similarity with fulltext search for improved RAG results. Documents matching both sources rank highest.

Path Parameters

Parameter	Description
db	Database name
collection	Collection to search

Request Body

Field	Type	Description	Required
vector	array[float]	Query embedding vector.	Yes
text_query	string	Text query for fulltext search.	Yes
vector_index	string	Name of the vector index to use.	Yes
fulltext_field	string	Document field to search with fulltext.	Yes
vector_weight	float	Weight for vector scores (0-1). Default: 0.5.	No
text_weight	float	Weight for fulltext scores (0-1). Default: 0.5.	No
limit	integer	Maximum results to return. Default: 10.	No
fusion	string	Score fusion method: `weighted` (default) or `rrf`.	No

Example Request

{ "vector": [0.0123, -0.0456, ...], "text_query": "machine learning", "vector_index": "embedding_idx", "fulltext_field": "content", "vector_weight": 0.6, "text_weight": 0.4, "limit": 10 }

Response

200 OK

{ "results": [ { "doc_key": "article_001", "score": 0.85, "vector_score": 0.9, "text_score": 0.7, "sources": ["vector", "fulltext"] }, { "doc_key": "article_042", "score": 0.72, "vector_score": 0.8, "text_score": null, "sources": ["vector"] } ] }

Score Interpretation

score is the combined score (0-1). sources indicates which searches matched. Documents in both vector and fulltext results rank highest.

Complete Example

A full workflow for setting up and using vector search:

1. Create a collection and add documents with embeddings

# Create collection curl -X POST http://localhost:6745/_api/database/mydb/collection \ -H "Content-Type: application/json" \ -d '{"name": "articles"}' # Insert documents with embeddings curl -X POST http://localhost:6745/_api/database/mydb/document/articles \ -H "Content-Type: application/json" \ -d '{ "_key": "article_001", "title": "Introduction to Machine Learning", "embedding": [0.0123, -0.0456, 0.0789, ...] }'

2. Create a vector index

curl -X POST http://localhost:6745/_api/database/mydb/vector/articles \ -H "Content-Type: application/json" \ -d '{ "name": "embedding_idx", "field": "embedding", "dimension": 1536, "metric": "cosine" }'

3. Search for similar documents

curl -X POST http://localhost:6745/_api/database/mydb/vector/articles/embedding_idx/search \ -H "Content-Type: application/json" \ -d '{ "vector": [0.0111, -0.0222, 0.0333, ...], "limit": 5 }'

4. Or use SDBQL for more complex queries

curl -X POST http://localhost:6745/_api/database/mydb/query \ -H "Content-Type: application/json" \ -d '{ "query": "FOR doc IN articles LET sim = VECTOR_SIMILARITY(doc.embedding, @vec) FILTER sim > 0.8 SORT sim DESC LIMIT 10 RETURN {title: doc.title, score: sim}", "bindVars": { "vec": [0.0111, -0.0222, 0.0333, ...] } }'

Vector Search API

Vector Index Management

Request Body

Example Request

Response

Response

Path Parameters

Response

Vector Quantization

Path Parameters

Example Request

Response

Asymmetric Search

Example Request

Response

Vector Similarity Search

Path Parameters

Request Body

Example Request

Response

Score Interpretation

Hybrid Search (Vector + Fulltext)

Path Parameters

Request Body

Example Request

Response

Score Interpretation

Complete Example

1. Create a collection and add documents with embeddings

2. Create a vector index

3. Search for similar documents

4. Or use SDBQL for more complex queries