Documentation
¶
Overview ¶
Package qdrant exposes Qdrant through the Core vector-store capability interfaces. Documents are stored as points in a Qdrant collection (`{id, vector, payload}`); retrieval runs the collection's vector search. Documents containing media are rejected before indexing I/O because this adapter persists document text and metadata only.
Requirements: a reachable Qdrant server (self-hosted or Qdrant Cloud). The store uses the official qdrant-client-go gRPC client.
Vector similarity functions: cosine / dot / euclid / manhattan. The chosen value is bound to the collection at creation time.
Existing collection. The collection is verified whenever it is found, whatever StoreConfig.InitializeSchema says, because that flag answers whether a missing collection may be created and not whether the one found is the right one — and the second question matters most for a collection provisioned out of band. A configured metric that disagrees with the collection's returns scores that are wrong rather than absent, so it fails construction with ErrIncompatibleCollection, as does a collection that is neither found nor creatable. StoreConfig.Dimensions is compared only when declared, since it is required to create a collection and optional to attach to one.
Filter visitor produces Qdrant's structured filter syntax — `{"must": [{"key": "author", "match": {"value": "Alice"}}]}`, `{"should": [...]}`, `{"must_not": [...]}` for NOT, `{"range": {"gte": 100, "lt": 200}}` for numeric ranges. The result feeds the `Filter` field of the search request.
Payload. Qdrant's `payload` is arbitrary JSON; the store maps the document's text + metadata into the payload verbatim. Indexed payload fields (for filter performance) live on the collection schema and are configured out of band — the store does not create or modify them.
Write visibility. Qdrant acknowledges an update as soon as it reaches the write-ahead log unless the request asks to wait. Every store write — index and both delete paths — waits for the change to be applied, so a Search issued after a write observes it, and then reads the status of that wait. Only Completed means "update is applied and ready for search"; Acknowledged is "received, but not processed yet", WaitTimeout is a "timeout of awaited operations", and ClockRejected means the update was "rejected due to an outdated clock". The gRPC call succeeds under all four, so the status rather than the call is what establishes that the write happened.
Null tests emit is_empty rather than is_null. Qdrant separates the two: is_null matches records where the field "exists and has NULL value", while is_empty matches records where it "either does not exist, or has null or [] value". The filter AST treats an absent key and an explicit null alike, and an absent key is the ordinary case for metadata, so is_null would answer nothing for the documents an IS NULL test is usually asked about. is_empty is wider in one respect — it also matches a key holding an empty array, which the AST reports as non-null — and Qdrant offers no condition that separates that case.
See https://qdrant.tech/documentation/ for the full API surface. Metadata numbers use signed 64-bit integers where exact, otherwise doubles whose decimal JSON value round-trips without loss. Unrepresentable numbers are rejected at the payload boundary.
Index ¶
- Constants
- Variables
- type DistanceMetric
- type Store
- func (s *Store) DeleteIDs(ctx context.Context, ids []string) (err error)
- func (s *Store) DeleteWhere(ctx context.Context, expr filter.Predicate) (err error)
- func (s *Store) Index(ctx context.Context, request *vectorstore.IndexRequest) (err error)
- func (s *Store) Search(ctx context.Context, req *vectorstore.SearchRequest) (response *vectorstore.SearchResponse, err error)
- type StoreConfig
Constants ¶
const (
Provider = "Qdrant"
)
Provider is the stable backend name for host-side attribution.
Variables ¶
var ( ErrMissingClient = errors.New("qdrant: Client is required") ErrMissingCollectionName = errors.New("qdrant: CollectionName is required") ErrMissingEmbeddingModel = errors.New("qdrant: EmbeddingModel is required") ErrMissingDocumentBatcher = errors.New("qdrant: DocumentBatcher is required") ErrInvalidDistanceMetric = errors.New("qdrant: DistanceMetric must be cosine, dot, euclid, or manhattan") ErrInvalidPointID = errors.New("qdrant: invalid point ID") ErrIncompatibleCollection = errors.New("qdrant: incompatible collection schema") )
Functions ¶
This section is empty.
Types ¶
type DistanceMetric ¶
type DistanceMetric string
DistanceMetric identifies the metric configured on the Qdrant collection. It is required because Qdrant score direction and threshold semantics depend on the collection metric.
const ( DistanceCosine DistanceMetric = "cosine" DistanceDot DistanceMetric = "dot" DistanceEuclid DistanceMetric = "euclid" DistanceManhattan DistanceMetric = "manhattan" )
The metric is a closed vocabulary because score direction and threshold semantics depend on it: the same raw number means "near" under one metric and "far" under another, so an unrecognized value must be rejected rather than guessed.
func (DistanceMetric) String ¶
func (d DistanceMetric) String() string
func (DistanceMetric) Valid ¶
func (d DistanceMetric) Valid() bool
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store implements vectorstore.Store against a Qdrant collection. The distance metric is held here because Qdrant's score direction and threshold semantics depend on the metric the collection was created with.
func NewStore ¶
func NewStore(ctx context.Context, config StoreConfig) (*Store, error)
NewStore performs schema setup during construction, which is why it takes a context: a store returned before its collection exists would fail on the first index rather than at wiring, where the misconfiguration actually is.
func (*Store) DeleteIDs ¶
DeleteIDs removes points by their canonical uint64 or UUID identifiers. An empty slice is a no-op; unknown ids are ignored (idempotent). Like DeleteWhere, the request waits for the deletion to be applied.
func (*Store) DeleteWhere ¶
DeleteWhere removes every point matching expr. The request waits for the deletion to be applied, because Qdrant otherwise answers as soon as the operation reaches the write-ahead log and a following Search would still return the removed points. Implements vectorstore.FilterDeleter.
func (*Store) Index ¶
func (s *Store) Index(ctx context.Context, request *vectorstore.IndexRequest) (err error)
func (*Store) Search ¶
func (s *Store) Search(ctx context.Context, req *vectorstore.SearchRequest) (response *vectorstore.SearchResponse, err error)
type StoreConfig ¶
type StoreConfig struct {
// Client is the Qdrant client instance for communicating with Qdrant server.
// Required: must be provided, otherwise initialization will fail.
Client *qdrant.Client
// CollectionName is the name of the collection to use for storing vectors.
// Required: must be a non-empty string.
CollectionName string
// DistanceMetric must match the collection's unnamed dense-vector metric.
// When InitializeSchema is true and the collection does not exist, this
// metric is used to create it.
DistanceMetric DistanceMetric
// Dimensions stays explicit because schema verification must not trigger a
// hidden, billable embedding request.
Dimensions int
// InitializeSchema indicates whether to automatically create the collection
// if it does not exist. When set to true, the collection will be created
// with vector configuration based on EmbeddingModel dimensions.
// Optional: defaults to false.
InitializeSchema bool
// EmbeddingModel is the model used to generate vector embeddings from text.
// It is also used to determine the vector dimension when creating collections.
// Required: must be provided for both embedding generation and schema initialization.
EmbeddingModel embedding.Model
// DocumentBatcher is responsible for batching documents before insertion.
// This helps optimize bulk operations and embedding generation.
// Required: must be provided to handle document batching logic.
DocumentBatcher vectorstore.Batcher
}
StoreConfig contains configuration options for Qdrant vector store.
func (StoreConfig) Validate ¶
func (s StoreConfig) Validate() error
Source Files