Documentation
¶
Overview ¶
Package qdrant implements the first external VectorIndex adapter (ADR-05, REQ-VEC-001/002). It uses the official Qdrant Go client (gRPC) to talk to a Qdrant server.
SERVER-TRACK BOUNDARY: this package is SERVER-track (arch_test.go bans it from local composition). The local composition path (internal/app) wires the sqlite_blob zero-CGO default and MUST NOT import this package. Provider selection (qdrant.New) happens ONLY in the server/external composition path. This preserves REQ-FOUND-001: CGO_ENABLED=0 local build with zero external vector dependencies.
Collection naming/namespacing: one Qdrant collection per (collection name). The collection's vector size is fixed at creation (dimension). Dimension and model mismatch are rejected FAIL-CLOSED before any server call (REQ-VEC-001 dim-mismatch corruption pin; model-namespace mismatch). The collection is lazily created on first use if it does not exist.
No plaintext secrets: the APIKey is passed to the gRPC dial config and is NEVER logged or surfaced in error messages (REQ-CP-002). Error wrapping excludes the key from every error string.
Timeouts/retries: every operation runs under a context with a configurable timeout; the underlying client is configured with a RetryConfig for transient gRPC failures (ResourceExhausted, Unavailable).
Index ¶
- type Adapter
- func (a *Adapter) Capabilities(_ context.Context) (domain.Capabilities, error)
- func (a *Adapter) Close() error
- func (a *Adapter) Delete(ctx context.Context, ids []int64) error
- func (a *Adapter) Health(ctx context.Context) domain.Health
- func (a *Adapter) ID() string
- func (a *Adapter) Search(ctx context.Context, q domain.VectorQuery) ([]domain.VectorCandidate, error)
- func (a *Adapter) Upsert(ctx context.Context, points []domain.VectorPoint) error
- type AdapterConfig
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Adapter ¶
type Adapter struct {
// contains filtered or unexported fields
}
Adapter implements domain.VectorIndex over a Qdrant server via the official Go client.
func New ¶
func New(cfg AdapterConfig) (*Adapter, error)
New constructs a Qdrant Adapter with a real gRPC client. The caller MUST be in the server/external composition path (this package is server-track). The returned Adapter owns its client; Close closes it.
func NewWithClient ¶
func NewWithClient(client qdrantClient, cfg AdapterConfig) *Adapter
NewWithClient constructs an Adapter over a pre-built (or fake) client. Used by tests and by compositions that manage the client lifecycle externally. The caller controls whether Close closes the client (see ownClient on the returned Adapter; default false for NewWithClient).
func (*Adapter) Capabilities ¶
Capabilities declares the adapter's supported features for capability-driven strategy selection (ADR-05).
func (*Adapter) Close ¶
Close releases resources. If the adapter owns its client (factory-built via New), the underlying gRPC client is closed.
func (*Adapter) Delete ¶
Delete removes vectors by observation ID. Missing IDs are tolerated (idempotent delete — Qdrant does not error on absent IDs).
func (*Adapter) Health ¶
Health reports the adapter's current health by probing the Qdrant server. The API key is never included in the health message.
func (*Adapter) Search ¶
func (a *Adapter) Search(ctx context.Context, q domain.VectorQuery) ([]domain.VectorCandidate, error)
Search translates a domain.VectorQuery into a Qdrant QueryPoints call. Filters are mapped to Must conditions (PreFilter). The score threshold is applied client-side after receiving results (Qdrant ScoreThreshold is forwarded too, but the client-side filter is authoritative for cross-adapter conformance).
func (*Adapter) Upsert ¶
Upsert stores a batch of vectors. Dimension and model-namespace mismatch are rejected FAIL-CLOSED before any server call (REQ-VEC-001 dim-mismatch pin; model mismatch). The batch is chunked at maxBatchSize. Each point's metadata plus model info is forwarded as Qdrant payload for traceability and PreFilter search.
type AdapterConfig ¶
type AdapterConfig struct {
Host string // gRPC host (default localhost)
Port int // gRPC port (default 6334)
Collection string // collection name (default cortex)
Dimension int // expected vector dimension (collection vector size)
ModelName string // model name for namespace enforcement (empty = skip)
APIKey string // optional API key (never logged)
UseTLS bool // TLS for gRPC
MaxBatchSize int // upsert batch ceiling (default 256)
MaxRetries uint // transient gRPC retries (default 3)
Timeout time.Duration
}
AdapterConfig holds the parameters to construct a Qdrant Adapter. It mirrors config.QdrantConfig but is declared here so the adapter package is self-contained (the server composition path maps config.QdrantConfig → AdapterConfig).
Source Files