Vector Database
Overview
A vector database stores the embeddings generated from your knowledge bases and is what RAG and the semantic cache search against. Apinizer connects to it as an ordinary connection, the same way it connects to other backing services.
Choosing a Backend
Three interchangeable backends are supported — pick whichever fits your deployment:
A good fit if you already run PostgreSQL and want vector search alongside your existing data.
A purpose-built vector database for teams that want a dedicated similarity-search engine.
A good fit if you already run Redis and want fast, in-memory similarity search.
Knowledge bases, RAG, and the semantic cache all work the same way regardless of which backend you choose — the backend is a deployment choice, not a feature trade-off.
The Database Type dropdown also lists a few additional vendors — Weaviate, Milvus, Chroma, Pinecone, and Other. These currently appear catalog-only: they're shown with a lock icon and can't be selected, because they aren't supported at runtime yet.
Built-in Templates
Two built-in templates ship with the installation: PgVector (Local) and Qdrant (Local). These are not working connections but skeletons for you to fill in — their addresses (localhost:5432, localhost:6333) are samples.
That is why the templates arrive disabled. Left enabled, the deploy and health-check paths would try to reach an address that does not exist. The intended flow is to clone a template, enter the real address and credentials, and enable the clone; the template itself stays disabled.
Built-in templates are owned by the installation and are marked as system records in the list. An upgrade may refresh their contents, which is why you clone them rather than edit them in place.
Creating a Connection
The connection form adapts to the database type you pick — each backend asks for its own connection details (for example JDBC settings for pgvector, a connection URI for Redis), while a shared set of fields (collection name, timeouts, similarity settings) stays the same across all three.
From the AI Gateway menu, open RAG, switch to the Vector DBs tab, then click Create.
Give the connection a name and choose PostgreSQL (pgvector), Qdrant, or Redis from the Database Type list. The rest of the form reshapes itself around your choice, and a tag near the top of the page shows which connection family (JDBC/HTTP/Redis) it belongs to.
Which fields you see depends on the database type:
- PostgreSQL (pgvector) — a JDBC URL in the form
jdbc:postgresql://host:5432/database, plus a database username and password. - Qdrant — an endpoint URL and an authentication scheme; depending on the scheme, additional fields (auth header name, API key, API secret) appear — see the table below.
- Redis — a Redis URI in the form
redis://host:6379; an ACL username and password are optional.
Every family also shares a Default Collection Name field and Connect Timeout / Request Timeout (ms) fields.
Passwords, API keys, and API secrets are always stored encrypted. When you edit an existing connection these fields show up blank; leaving one blank keeps its previous value (a "Configured" hint above the field is your reminder).
Distance Metric (Cosine, Euclidean, or Dot Product) determines how similarity is calculated and is pre-filled based on the database type you picked; override it if you need to. Embedding Dimension and Maximum Batch Size are filled in the same way, as reference values you can adjust.
If you picked PostgreSQL (pgvector), an optional Connection Pool section also appears (minimum idle connections, maximum pool size, pool timeouts) — any field you leave blank falls back to Apinizer's built-in pool defaults.
Pick an environment from the selector at the top of the form — the Test Connection button stays disabled until you do — then click it to verify reachability from that environment. Once it succeeds, click Save and Deploy; the connection is persisted and rolled out to all published environments (the selector above is only used to run the test, it does not choose deploy targets).
Save and Deploy does not verify the connection. It only stores the configuration and distributes it to the workers, so it succeeds even when the address, username, password or database name is wrong. This matches the behaviour of a classic Connection Settings → JDBC connection and lets you save a half-finished configuration and complete it later. Only Test Connection tells you whether the connection actually works — run it before you save.
The connection itself is opened the first time it is used, when RAG, semantic cache or topic guard runs a query. If it cannot be opened at that moment, the request is handled as though the database had never been deployed: the policy falls back to its own configured behaviour (skip or block) and the raw database error is never surfaced in the request response.
A redeploy always activates the last saved configuration and closes whatever connection is currently open. If you deploy a broken configuration over a working one, the working connection is not preserved — the new configuration takes effect and subsequent uses fail. Saving the correct details and redeploying restores the connection.
Fields by Authentication Scheme (Qdrant and other HTTP-based types)
| Authentication Scheme | Additional Fields Shown |
|---|---|
| None | (none) |
| Bearer Token | Auth Header Name, API Key |
| API Key Header | Auth Header Name, API Key |
| Basic Auth | API Key, API Secret |
| Custom | Auth Header Name, API Key, API Secret |
Embedding Provider
A single, configurable embedding provider (for example OpenAI, Voyage, or a self-hosted Ollama model) generates the vector representations used both when a knowledge base is indexed and when a request is matched against it. Using one provider consistently for both sides keeps indexed content and incoming requests comparable.
Different embedding providers produce vectors of different sizes. Changing the embedding provider after a vector database connection is already in use may require re-indexing your existing data.
Tenant Isolation
Every similarity search is filtered to the requesting project's boundary, the same isolation guarantee described in RAG scope isolation — one tenant's search can never return another tenant's content, regardless of which backend is in use.
Embedding Support Verification
Before a request is routed to an endpoint that requires embedding generation (RAG, semantic cache, embedding endpoint), Apinizer verifies that the selected provider actually supports embeddings. A request is never routed to a provider that can't generate them.
Vector database connections can also be managed through the APIops REST API; see API Reference: Vector DBs.
Deleting a Connection
A Vector DB connection that is in use cannot be deleted. The delete is rejected while anything still points at it, and the error message lists those references one by one, naming the API Proxy or the global policy they live in.
The reason is that a vector database is a reference-type asset: it is never copied into the policy document, it is resolved by id at runtime. Without the guard, deleting one would leave RAG Injection and Semantic Cache policies holding a broken reference, and the live gateway would fail on the very next request.
The check covers four containers at once — API Proxy, Proxy Group, Policy Group and standalone (global) policies — and looks at the vector database field of RAG Injection and Semantic Cache policies.
To delete the connection, remove those references first or point them at another connection. The same rule applies to deletes made through APIops: DELETE /apiops/projects/{projectName}/vector-dbs/{vectorDbName}/ returns 400 Bad Request for a connection that is still in use.
This is the twin of the same guard on LLM provider connections — see LLM Providers and Connections.