Struct QdrantOps 

pub struct QdrantOps { /* private fields */ }

Thin wrapper over Qdrant client encapsulating common collection operations.

Implementations

impl QdrantOps

pub fn new(url: &str, api_key: Option<&str>) -> Result<Self, Box<QdrantError>>

Create a new QdrantOps connected to the given URL with optional API key.

When api_key is Some(k) and k is non-empty, the key is attached to the gRPC client builder. Empty strings are treated as None so callers can pass empty config values without accidentally disabling auth.

The key is consumed by qdrant-client during .build() and is never stored on QdrantOps itself.

Errors

Returns an error if the Qdrant client cannot be created (e.g. malformed URL).

pub fn with_timeout(self, timeout: Duration) -> Self

Override the per-call timeout applied to every Qdrant gRPC operation.

Defaults to 10 seconds. A slow or hung Qdrant server would otherwise block the calling async task indefinitely (#5484). The production bootstrap path drives this from MemoryConfig::qdrant_timeout_secs.

Examples

use std::time::Duration;
use zeph_memory::QdrantOps;

let ops = QdrantOps::new("http://localhost:6334", None)
    .unwrap()
    .with_timeout(Duration::from_secs(3));

pub fn client(&self) -> &Qdrant

Access the underlying Qdrant client for advanced operations.

Warning

Calls made directly through the returned client bypass the Self::with_timeout guard (#5484) — they are not wrapped by Self::timed. Prefer the inherent QdrantOps methods, which are all timeout-guarded, unless the client exposes an operation this type does not wrap.

pub async fn ensure_collection( &self, collection: &str, vector_size: u64, ) -> Result<(), Box<QdrantError>>

Ensure a collection exists with cosine distance vectors.

If the collection already exists but has a different vector dimension than vector_size, the collection is deleted and recreated. All existing data in the collection is lost. Callers on interactive/destructive-sensitive paths should pre-check via Self::collection_exists + Self::get_collection_vector_size and gate the call behind explicit confirmation instead of relying on this method’s silent recreate (see zeph knowledge ingest’s notes-sink resource setup for the reference pattern, #5444).

Errors

Returns an error if Qdrant cannot be reached or collection creation fails.

pub async fn get_collection_vector_size( &self, collection: &str, ) -> Result<Option<u64>, Box<QdrantError>>

Returns the configured vector size of an existing collection, or None if it cannot be determined (e.g. named-vector collections).

Precondition

The caller must already know the collection exists (e.g. via a prior Self::collection_exists check that returned true). This method does not treat “collection missing” and “dimension unreadable” as the same case: calling it on a non-existent collection surfaces the underlying collection_info gRPC error (Err), it does not return Ok(None). Every existing call site (this type’s own Self::ensure_collection, crate::EmbeddingRegistry) checks collection_exists first for this reason.

Used by crate::EmbeddingRegistry to validate query vector dimensions before issuing gRPC searches. Qdrant gRPC silently returns near-zero cosine scores when the query vector dimension does not match the stored collection dimension (unlike REST which returns 400). Also used by callers that need to detect an Self::ensure_collection dimension mismatch before invoking it, so a destructive recreate can be gated behind confirmation.

Errors

Returns an error on hard Qdrant communication failures, including calling this on a collection that does not exist (see Precondition above).

pub async fn collection_exists( &self, collection: &str, ) -> Result<bool, Box<QdrantError>>

Check whether a collection exists.

Errors

Returns an error if Qdrant cannot be reached.

pub async fn delete_collection( &self, collection: &str, ) -> Result<(), Box<QdrantError>>

Delete a collection.

Errors

Returns an error if the collection cannot be deleted.

pub async fn upsert( &self, collection: &str, points: Vec<PointStruct>, ) -> Result<(), Box<QdrantError>>

Upsert points into a collection.

Errors

Returns an error if the upsert fails.

pub async fn search( &self, collection: &str, vector: Vec<f32>, limit: u64, filter: Option<Filter>, ) -> Result<Vec<ScoredPoint>, Box<QdrantError>>

Search for similar vectors, returning scored points with payloads.

Uses the Qdrant Query API (client.query) which handles query vector normalization server-side for Cosine collections, producing correct similarity scores.

Errors

Returns an error if the search fails.

pub async fn delete_by_ids( &self, collection: &str, ids: Vec<PointId>, ) -> Result<(), Box<QdrantError>>

Delete points by their IDs.

Errors

Returns an error if the deletion fails.

pub async fn scroll_all( &self, collection: &str, key_field: &str, ) -> Result<HashMap<String, HashMap<String, String>>, Box<QdrantError>>

Scroll all points in a collection, extracting string payload fields.

Returns a map of key_field value -> { field_name -> field_value }.

Errors

Returns an error if the scroll operation fails.

pub async fn scroll_all_with_point_ids( &self, collection: &str, key_field: &str, ) -> Result<Vec<(String, HashMap<String, String>)>, Box<QdrantError>>

Scroll all points in a collection, returning (point_id, string_payload_fields) pairs.

Only points whose payload contains key_field as a StringValue are included. The Qdrant point ID is preserved as the first tuple element.

Errors

Returns an error if the scroll operation fails.

pub async fn ensure_collection_with_quantization( &self, collection: &str, vector_size: u64, keyword_fields: &[&str], ) -> Result<(), VectorStoreError>

Create a collection with scalar INT8 quantization if it does not exist, then create keyword indexes for the given fields.

If the collection already exists but has a different vector dimension than vector_size, the collection is deleted and recreated. All existing data in the collection is lost.

Errors

Returns an error if any Qdrant operation fails.

pub fn json_to_payload(value: Value) -> Result<HashMap<String, Value>, Error>

Convert a JSON value to a Qdrant payload map.

Errors

Returns a JSON error if deserialization fails.

Trait Implementations

impl Clone for QdrantOps

fn clone(&self) -> QdrantOps

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for QdrantOps

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl VectorStore for QdrantOps

fn ensure_collection( &self, collection: &str, vector_size: u64, ) -> Pin<Box<dyn Future<Output = Result<(), VectorStoreError>> + Send + '_>>

Create a collection with cosine-distance vectors of vector_size dimensions.

fn collection_exists( &self, collection: &str, ) -> Pin<Box<dyn Future<Output = Result<bool, VectorStoreError>> + Send + '_>>

Returns true if collection exists in the backend.

fn delete_collection( &self, collection: &str, ) -> Pin<Box<dyn Future<Output = Result<(), VectorStoreError>> + Send + '_>>

Delete a collection and all its points.

fn upsert( &self, collection: &str, points: Vec<VectorPoint>, ) -> Pin<Box<dyn Future<Output = Result<(), VectorStoreError>> + Send + '_>>

Upsert points into collection.

fn search( &self, collection: &str, vector: Vec<f32>, limit: u64, filter: Option<VectorFilter>, ) -> Pin<Box<dyn Future<Output = Result<Vec<ScoredVectorPoint>, VectorStoreError>> + Send + '_>>

Search collection for the limit nearest neighbours of vector.

fn delete_by_ids( &self, collection: &str, ids: Vec<String>, ) -> Pin<Box<dyn Future<Output = Result<(), VectorStoreError>> + Send + '_>>

Delete specific points from collection by their string IDs.

fn scroll_all( &self, collection: &str, key_field: &str, ) -> Pin<Box<dyn Future<Output = Result<HashMap<String, HashMap<String, String>>, VectorStoreError>> + Send + '_>>

Scroll (paginate) all points in collection and return a map of point_id → { key_field → value } payload entries.

fn scroll_all_with_point_ids( &self, collection: &str, key_field: &str, ) -> Pin<Box<dyn Future<Output = Result<ScrollWithIdsResult, VectorStoreError>> + Send + '_>>

Scroll all points in collection, returning (point_id, string_payload_fields) pairs.

fn health_check( &self, ) -> Pin<Box<dyn Future<Output = Result<bool, VectorStoreError>> + Send + '_>>

Return true if the backend is reachable and operational.

fn create_keyword_indexes( &self, collection: &str, fields: &[&str], ) -> Pin<Box<dyn Future<Output = Result<(), VectorStoreError>> + Send + '_>>

Create keyword payload indexes for the given field names.

fn get_points( &self, collection: &str, ids: Vec<String>, ) -> Pin<Box<dyn Future<Output = Result<Vec<VectorPoint>, VectorStoreError>> + Send + '_>>

Batched vector + payload retrieval by point IDs.