# How to Configure Vector Stores (FAISS, Pinecone, Qdrant, PgVector) with Semantica: A Complete Guide

> Easily configure FAISS, Pinecone, Qdrant, and PgVector with Semantica. This guide provides clear steps to set up your chosen vector store for seamless integration.

- Repository: [Semantica /semantica](https://github.com/semantica-agi/semantica)
- Tags: how-to-guide
- Published: 2026-08-16

---

**Configure any supported vector database in Semantica by setting the `backend` parameter in `VectorStore`—choose from `"faiss"`, `"qdrant"`, `"pinecone"`, or `"pgvector"`—and pass backend-specific connection details to instantiate the concrete store class.**

Semantica provides a **backend-agnostic vector store abstraction** that unifies FAISS, Pinecone, Qdrant, PgVector, and Weaviate under a single API. This design lets you swap vector databases without changing your application code. According to the [semantica-agi/semantica](https://github.com/semantica-agi/semantica) source code, the `VectorStore` class in [`semantica/vector_store/vector_store.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/vector_store/vector_store.py) orchestrates backend selection and delegates operations to specialized implementations.

---

## Supported Vector Store Backends

Semantica supports five production-ready vector databases through dedicated modules in `semantica/vector_store/`:

| Backend | Module | Primary Classes | Best For |
|---------|--------|---------------|----------|
| **FAISS** | [`faiss_store.py`](https://github.com/semantica-agi/semantica/blob/main/faiss_store.py) | `FAISSStore`, `FAISSIndex`, `FAISSSearch` | Local, in-process similarity search without external dependencies |
| **Qdrant** | [`qdrant_store.py`](https://github.com/semantica-agi/semantica/blob/main/qdrant_store.py) | `QdrantStore`, `QdrantClient`, `QdrantCollection` | Self-hosted or cloud vector search with rich filtering |
| **Pinecone** | [`pinecone_store.py`](https://github.com/semantica-agi/semantica/blob/main/pinecone_store.py) | `PineconeStore`, `PineconeClient`, `PineconeIndex` | Fully managed, scalable vector search SaaS |
| **PgVector** | [`pgvector_store.py`](https://github.com/semantica-agi/semantica/blob/main/pgvector_store.py) | `PgVectorStore` | Existing PostgreSQL infrastructure with SQL-native queries |
| **Weaviate** | [`weaviate_store.py`](https://github.com/semantica-agi/semantica/blob/main/weaviate_store.py) | `WeaviateStore` | GraphQL-based semantic search with modular AI integrations |

Each backend implements the same core interface: `add_vectors()`, `search_similar()`, `save()`, `load()`, `delete()`, and `count()`.

---

## Architecture: How Backend Selection Works

### Backend Discovery in VectorStore.__init__

The `VectorStore` class maintains a `SUPPORTED_BACKENDS` registry. When you instantiate it with `backend="qdrant"` (or any supported value), `VectorStore.__init__` performs a **lazy import** of the corresponding module:

```python

# From semantica/vector_store/vector_store.py

class VectorStore:
    SUPPORTED_BACKENDS = {"faiss", "qdrant", "pinecone", "pgvector", "weaviate"}
    
    def __init__(self, backend: str, **backend_kwargs):
        if backend not in self.SUPPORTED_BACKENDS:
            raise ValueError(f"Unsupported backend: {backend}")
        
        # Lazy import keeps optional dependencies truly optional

        if backend == "faiss":
            from .faiss_store import FAISSStore
            self._backend_store = FAISSStore(**backend_kwargs)
        elif backend == "qdrant":
            from .qdrant_store import QdrantStore
            self._backend_store = QdrantStore(**backend_kwargs)
        # ... etc

```

**Optional dependency guards** (`FAISS_AVAILABLE`, `QDRANT_AVAILABLE`, etc.) ensure import errors are raised with helpful messages if required SDKs are missing.

### Unified API Contract

All backend classes satisfy the `VectorStore` contract:

- **`add_vectors(vectors, ids, metadata)`** — Bulk insertion with optional metadata per vector
- **`search_similar(query_vector, k, **options)`** — Returns list of `{id, score, metadata, vector, distance}` dictionaries
- **`save(path)` / `load(path)`** — Persistence (where backend supports it)
- **`delete(ids)` / `count()`** — Lifecycle operations

### Metadata Translation for Hybrid Search

Each store converts Semantica's generic metadata filters into native backend formats:

- **Qdrant**: `Filter` objects with `must`/`should`/`must_not` clauses
- **Pinecone**: Python `metadata` dictionaries
- **PgVector**: SQL `WHERE` clauses with `@@` operator
- **FAISS**: In-memory attribute filtering (if index supports it)

This enables **vector + metadata hybrid search** across all backends without query syntax changes.

---

## Configuration Examples by Backend

### FAISS: Local In-Memory Search

**Use FAISS** when you need zero external dependencies and can hold indexes in memory or on local disk.

```python
from semantica.vector_store import FAISSStore
import numpy as np

# Initialize with embedding dimension

store = FAISSStore(dimension=768)

# Add vectors with string IDs

vectors = np.random.rand(1000, 768).astype('float32')
store.add_vectors(
    vectors=vectors,
    ids=[f"doc_{i}" for i in range(1000)],
    metadata=[{"source": "local_docs"}] * 1000
)

# Search

results = store.search_similar(
    query_vector=np.random.rand(1, 768).astype('float32'),
    k=5
)
print(results)  # [{id, score, metadata, vector, distance}, ...]

# Persist to disk

store.save("/path/to/faiss_index.bin")

```

Key classes in [`semantica/vector_store/faiss_store.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/vector_store/faiss_store.py): `FAISSStore` wraps `FAISSIndex` for index management, `FAISSSearch` for query execution, and `FAISSIndexBuilder` for construction-time optimization.

### Qdrant: Self-Hosted or Cloud

**Use Qdrant** when you need persistent collections, payload filtering, and horizontal scaling.

```python
from semantica.vector_store import QdrantStore

# Connect to Qdrant server

store = QdrantStore(
    url="http://localhost:6333",  # or cloud endpoint

    api_key=None  # set for Qdrant Cloud

)
store.connect()

# Create collection with cosine similarity

store.create_collection(
    name="semantic_search",
    vector_size=768,
    distance="Cosine"  # also "Euclid", "Dot"

)

# Insert with metadata for filtering

store.add_vectors(
    vectors=np.random.rand(500, 768).astype('float32'),
    ids=list(range(500)),
    metadata=[{"category": "tech", "year": 2024}] * 500
)

# Hybrid search: vector similarity + metadata filter

results = store.search_similar(
    query_vector=np.random.rand(1, 768).astype('float32'),
    k=10,
    filter={
        "must": [
            {"key": "category", "match": {"value": "tech"}},
            {"key": "year", "range": {"gte": 2023}}
        ]
    }
)

```

The `QdrantStore` class in [`semantica/vector_store/qdrant_store.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/vector_store/qdrant_store.py) manages `QdrantClient` connections and `QdrantCollection` lifecycle. `QdrantSearch` handles payload-aware similarity queries.

### Pinecone: Managed Vector Search

**Use Pinecone** when you want serverless scaling without infrastructure management.

```python
from semantica.vector_store import PineconeStore

# Authenticate and connect

store = PineconeStore(
    api_key="YOUR_PINECONE_API_KEY",
    environment="us-west1-gcp"  # or "us-east-1-aws", etc.

)
store.connect()

# Create index (one-time setup)

store.create_index(
    name="semantic-index",
    dimension=768,
    metric="cosine"  # or "dotproduct", "euclidean"

)

# Target specific index for operations

store.use_index("semantic-index")

# Upsert vectors with metadata

store.add_vectors(
    vectors=np.random.rand(100, 768).astype('float32'),
    ids=[str(i) for i in range(100)],
    metadata=[{"topic": "machine_learning", "priority": "high"}] * 100
)

# Query with optional namespace

results = store.search_similar(
    query_vector=np.random.rand(1, 768).astype('float32'),
    k=5,
    namespace=None  # for multi-tenant isolation

)

```

`PineconeStore` in [`semantica/vector_store/pinecone_store.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/vector_store/pinecone_store.py) wraps the official `PineconeClient`, with `PineconeIndex` for index operations and `PineconeSearch` for query execution.

### PgVector: PostgreSQL-Native Vectors

**Use PgVector** when your application already runs on PostgreSQL and you want to keep vectors with relational data.

```python
from semantica.vector_store import PgVectorStore

# Connection string with pgvector extension enabled

store = PgVectorStore(
    connection_string="postgresql://user:pass@localhost:5432/semantic_db"
)
store.connect()

# Ensure table exists (creates with pgvector column)

store.ensure_table(
    table_name="document_vectors",
    dimension=768,
    metric="cosine"  # creates appropriate HNSW index

)

# Insert with JSONB metadata

store.add_vectors(
    vectors=np.random.rand(200, 768).astype('float32'),
    ids=list(range(200)),
    metadata=[{"doc_id": f"doc_{i}", "section": "header"} for i in range(200)]
)

# Search with SQL filter

results = store.search_similar(
    query_vector=np.random.rand(1, 768).astype('float32'),
    k=5,
    filter_sql="metadata->>'section' = 'header'"
)

```

`PgVectorStore` in [`semantica/vector_store/pgvector_store.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/vector_store/pgvector_store.py) uses `psycopg2` with the `pgvector` Python client. The `ensure_table()` method verifies the `vector` extension is installed and creates optimized HNSW or IVFFlat indexes.

### Weaviate: GraphQL Semantic Search

**Use Weaviate** for GraphQL-native queries and modular AI integrations.

```python
from semantica.vector_store import WeaviateStore

store = WeaviateStore(
    url="http://localhost:8080",  # or WCS cloud URL

    auth_client_secret="YOUR_API_KEY"  # for WCS

)
store.connect()

# Schema is auto-created based on configuration

store.create_schema(
    class_name="Document",
    vectorizer=None,  # use custom vectors (Semantica handles embeddings)

    properties=[
        {"name": "title", "dataType": ["text"]},
        {"name": "category", "dataType": ["text"]}
    ]
)

store.add_vectors(
    vectors=np.random.rand(50, 768).astype('float32'),
    ids=[f"uuid-{i}" for i in range(50)],
    metadata=[{"title": f"Doc {i}", "category": "research"} for i in range(50)]
)

# Near-vector search with GraphQL filter

results = store.search_similar(
    query_vector=np.random.rand(1, 768).astype('float32'),
    k=5,
    filter_path=["category"],
    filter_value="research"
)

```

---

## CLI Configuration

Semantica's command-line interface in [`semantica/vector_store/cli.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/vector_store/cli.py) exposes vector store selection via the `--backend` flag:

```bash

# Index documents using Qdrant

python -m semantica index \
  --source /path/to/documents \
  --backend qdrant \
  --qdrant-url http://localhost:6333

# Search using existing Pinecone index

python -m semantica search \
  --query "machine learning applications" \
  --backend pinecone \
  --pinecone-api-key $PINECONE_KEY \
  --pinecone-index my-index

```

The CLI forwards `backend` and backend-specific arguments to `VectorStore.__init__`, demonstrating the same abstraction pattern used programmatically.

---

## Dependency Requirements

Install only the SDKs you need:

```bash

# FAISS only

pip install faiss-cpu  # or faiss-gpu for CUDA

# Qdrant only

pip install qdrant-client

# Pinecone only

pip install pinecone-client

# PgVector only

pip install psycopg2-binary pgvector

# Weaviate only

pip install weaviate-client

# All backends

pip install faiss-cpu qdrant-client pinecone-client psycopg2-binary pgvector weaviate-client

```

Semantica's lazy imports ensure missing optional dependencies raise clear errors only when that backend is instantiated.

---

## Performance and Feature Comparison

| Feature | FAISS | Qdrant | Pinecone | PgVector | Weaviate |
|---------|-------|--------|----------|----------|----------|
| Deployment | Local/embedded | Self-hosted/cloud | Fully managed | PostgreSQL extension | Self-hosted/cloud |
| Persistence | File-based | Server persistence | Server persistence | PostgreSQL tables | Server persistence |
| Metadata filtering | Limited | Rich payload filters | Metadata filters | SQL WHERE | GraphQL filters |
| Hybrid search | Approximate | Full support | Full support | SQL + vector | Full support |
| Horizontal scaling | Manual sharding | Built-in | Automatic | Read replicas | Built-in |
| Best for | Prototyping, edge | Production, multi-tenant | Serverless scale | SQL-centric apps | GraphQL-native apps |

---

## Summary

- **Semantica's `VectorStore`** abstracts FAISS, Pinecone, Qdrant, PgVector, and Weaviate through a unified interface in [`semantica/vector_store/vector_store.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/vector_store/vector_store.py)
- **Backend selection** happens via the `backend` parameter with lazy imports guarding optional dependencies
- **All backends** implement `add_vectors()`, `search_similar()`, and persistence methods with identical signatures
- **Metadata filters** are automatically translated to each backend's native query language
- **CLI support** provides `--backend` flag for command-line workflows

---

## Frequently Asked Questions

### How do I switch from FAISS to Qdrant without changing my code?

Change only the initialization call. Replace `FAISSStore(dimension=768)` with `QdrantStore(url="http://localhost:6333")` and ensure your `add_vectors()` and `search_similar()` calls use the same parameters. The unified API in [`semantica/vector_store/vector_store.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/vector_store/vector_store.py) ensures method compatibility across backends.

### Does Semantica support multiple vector stores simultaneously?

Yes. Instantiate separate store objects for each backend in the same process. Each maintains independent state through its `_backend_store` attribute. There is no global singleton—`VectorStore` instances are fully isolated.

### What happens if I try to use PgVector without installing psycopg2?

`PgVectorStore.__init__` checks `PGVECTOR_AVAILABLE` (set by attempting `import pgvector`). If unavailable, it raises `ImportError` with instructions to `pip install psycopg2-binary pgvector`. This lazy import pattern applies to all optional backends in `semantica-agi/semantica`.

### Can I use Weaviate's built-in vectorizers instead of providing embeddings?

No—Semantica manages embedding generation externally and passes vectors to `WeaviateStore.add_vectors()`. Set `vectorizer=None` in `create_schema()` as shown in the Weaviate example above. This design keeps Semantica's embedding pipeline consistent across all backends.