semantica/docs/reference/vector_store.md

title, description, icon

title	description	icon
Vector Store Module	Unified interface for FAISS, Pinecone, Weaviate, Qdrant, Milvus, and PgVector with hybrid search.	database

Unified vector database interface supporting multiple backends and hybrid search.

---

Overview

The Vector Store Module provides a unified API for storing and searching vector embeddings across all major backends.

FAISS (local), Pinecone, Weaviate, Qdrant, Milvus, PgVector, in-memory. Combine dense vector similarity with sparse keyword/metadata filtering. Rich filtering (eq, ne, gt, lt, in, contains) on any field. Multi-tenant support via isolated namespaces.

---

Basic Usage

from semantica.vector_store import VectorStore

# In-memory (development)
store = VectorStore(backend="inmemory", dimension=768)

# FAISS (local, production)
store = VectorStore(backend="faiss", dimension=768, index_path="store.faiss")

# Add vectors
store.add_vectors(embeddings=embeddings, ids=["doc1", "doc2"], metadata=[{}, {}])

# Semantic search
results = store.search(query_vector, top_k=10)
for r in results:
    print(f"{r['id']} — score: {r['score']:.3f}")

---

Backends

```python store = VectorStore( backend="faiss", dimension=768, index_type="IVF", # Flat, IVF, HNSW index_path="store.faiss" ) ``` Best for: local development, on-premise production with no external services. ```bash pip install "semantica[pinecone]" ``` ```python store = VectorStore( backend="pinecone", dimension=768, api_key=os.getenv("PINECONE_API_KEY"), index_name="semantica-index", environment="us-east-1-aws" ) ``` ```bash pip install "semantica[weaviate]" ``` ```python store = VectorStore( backend="weaviate", dimension=768, url="http://localhost:8080", class_name="Document" ) ``` ```bash pip install "semantica[qdrant]" ``` ```python store = VectorStore( backend="qdrant", dimension=768, url="http://localhost:6333", collection_name="semantica" ) ```

---

Hybrid Search

Combines vector similarity with keyword/metadata filters.

results = store.hybrid_search(
    query_vector=query_embedding,
    query_text="machine learning",   # keyword component
    top_k=10,
    alpha=0.7,                       # 0=keyword only, 1=vector only
    filters={"category": "research", "year": {"$gte": 2022}}
)

---

Metadata Filtering

# Equality
results = store.search(query_vector, filters={"author": "John Smith"})

# Range
results = store.search(query_vector, filters={"date": {"$gte": "2023-01-01"}})

# Set membership
results = store.search(query_vector, filters={"tag": {"$in": ["ai", "ml"]}})

# Compound
results = store.search(query_vector, filters={
    "$and": [{"category": "research"}, {"year": {"$gte": 2022}}]
})

---

Namespaces (Multi-Tenant)

store = VectorStore(backend="faiss", dimension=768)

store.add_vectors(embeddings, ids, namespace="tenant_a")
store.add_vectors(embeddings, ids, namespace="tenant_b")

results = store.search(query_vector, namespace="tenant_a")

---

Batch Operations

# Batch add
store.add_vectors_batch(embeddings_list, ids_list, batch_size=1000)

# Batch delete
store.delete_vectors(ids=["doc1", "doc2", "doc3"])

# Update metadata
store.update_metadata("doc1", {"status": "archived"})

---

See Also

Generate the vectors stored here. AgentContext uses VectorStore for memory. PostgreSQL vector storage with pgvector. Ingest documents before embedding and storing.