Struct Collection 

pub struct Collection { /* private fields */ }

A zvec collection for storing and querying vector data.

Collections are the primary data container in zvec. They hold documents with typed fields and support vector similarity search.

The collection is automatically closed when dropped.

Implementations

impl Collection

pub unsafe fn as_raw(&self) -> *mut zvec_collection_t

Returns the raw FFI handle.

Safety

The caller must not use the handle after the Collection is dropped.

pub unsafe fn from_raw(handle: *mut zvec_collection_t) -> Self

Creates a Collection from a raw FFI handle.

Safety

The caller must ensure the handle is valid and was created by the zvec C API. The Collection takes ownership and will call zvec_collection_close on drop.

pub fn create_and_open( path: &str, schema: &CollectionSchema, options: Option<&CollectionOptions>, ) -> Result<Self>

Creates a new collection and opens it.

pub fn open(path: &str, options: Option<&CollectionOptions>) -> Result<Self>

Opens an existing collection.

pub fn flush(&self) -> Result<()>

Flushes collection data to disk.

pub fn schema(&self) -> Result<CollectionSchema>

Returns the collection schema.

pub fn stats(&self) -> Result<CollectionStats>

Returns collection statistics.

pub fn insert(&self, docs: &[&Doc]) -> Result<WriteResult>

Inserts documents into the collection.

pub fn update(&self, docs: &[&Doc]) -> Result<WriteResult>

Updates documents in the collection.

pub fn upsert(&self, docs: &[&Doc]) -> Result<WriteResult>

Inserts or updates documents (upsert).

pub fn delete(&self, pks: &[&str]) -> Result<WriteResult>

Deletes documents by primary keys.

pub fn delete_by_filter(&self, filter: &str) -> Result<()>

Deletes documents matching a filter expression.

pub fn query(&self, query: &SearchQuery) -> Result<Vec<Doc>>

Performs a vector similarity search.

pub fn multi_query(&self, query: &MultiQuery) -> Result<Vec<Doc>>

Performs a multi-query that combines several sub-queries with a rerank strategy (RRF or weighted).

pub fn fetch(&self, pks: &[&str]) -> Result<Vec<Doc>>

Fetches documents by primary keys, returning all fields including vectors.

pub fn fetch_with_options( &self, pks: &[&str], output_fields: Option<&[&str]>, include_vector: bool, ) -> Result<Vec<Doc>>

Fetches documents by primary keys with control over which fields to return.

Projections are destructive when written back

A projected fetch (output_fields set, or include_vector == false) returns a document shaped like the full schema in which the columns you did not ask for are empty rather than absent. Passing such a document to Collection::upsert or Collection::update therefore overwrites those columns: nullable ones are silently set to null, while a missing non-nullable one is rejected with ErrorCode::InvalidArgument.

A read-modify-write cycle must fetch the complete document:

use zvec_rust::*;

let mut docs = collection.fetch_with_options(&["doc1"], None, true)?;
docs[0].add_string("payload", "tombstone")?;
let refs: Vec<&Doc> = docs.iter().collect();
collection.upsert(&refs)?;

Keep projections for read-only paths.

Row order is not guaranteed

The returned documents are not guaranteed to come back in the order the primary keys were requested in, and the order can differ between platforms and between the in-memory writing segment and the persisted forward store. Match rows by primary key (or by a projected field) instead of by position.

pub fn iter(&self) -> Result<DocIterator<'_>>

Creates an iterator over all documents in the collection using default options (all scalar fields, vectors included).

The iterator traverses an isolated snapshot taken at creation time; documents written afterwards are not visible.

pub fn iter_with_options( &self, output_fields: Option<&[&str]>, include_vector: bool, ) -> Result<DocIterator<'_>>

Creates an iterator over all documents with control over which fields to return.

• output_fields: scalar fields to return; None returns all fields. An empty slice returns no scalar fields (primary key only).
• include_vector: whether to include vector fields.

The iterator traverses an isolated snapshot taken at creation time; documents written afterwards are not visible. While the iterator is open, schema changes (create/drop index, add/alter/drop column) and destroy are rejected by the C library.

pub fn create_index(&self, field_name: &str, params: &IndexParams) -> Result<()>

Creates an index on a field.

pub fn drop_index(&self, field_name: &str) -> Result<()>

Drops an index from a field.

pub fn optimize(&self) -> Result<()>

Optimizes the collection (rebuild indexes, merge segments, etc.).

pub fn add_column( &self, field_schema: &FieldSchema, default_expr: Option<&str>, ) -> Result<()>

Adds a column to the collection.

pub fn drop_column(&self, name: &str) -> Result<()>

Drops a column from the collection.

pub fn alter_column( &self, name: &str, new_name: Option<&str>, new_schema: Option<&FieldSchema>, ) -> Result<()>

Alters a column: renames it, or replaces its schema.

new_name and new_schema are mutually exclusive and at least one must be given; any other combination is rejected with ErrorCode::InvalidArgument. Renaming keeps the current schema, while a new schema replaces the field definition outright — its own name becomes the resulting column name, so pass name again to keep it unchanged. A nullable field cannot be made non-nullable.

The schema is deep-copied by the native layer, so new_schema stays owned by the caller and is dropped as usual.

pub fn close(self) -> Result<()>

Closes the collection explicitly.

The native handle is released by Drop, which reports a failed zvec_collection_close only as a warning on stderr, so this always returns Ok(()). Use Collection::try_close to observe a failed close.

pub fn try_close(self) -> Result<()>

Closes the collection explicitly and reports a failed close.

Consumes the collection exactly like Collection::close, but releases the native handle here instead of leaving it to Drop.

zvec_collection_close releases its handle whether it succeeds or fails — a failure only reports an exception raised while the handle was being released — so the handle is gone on both paths and a second close cannot be requested. Callers therefore get no handle back to retry with, and the collection’s data directory is left as the C library left it.

Open iterators borrow the collection, so none can be alive at this point; the C library then waits for the remaining handles before it closes the collection itself.

A null handle, reachable only through Collection::from_raw, is reported as ErrorCode::InvalidArgument rather than being ignored.

Errors

Returns whatever zvec_collection_close reported, together with the message the C library stored for that failure.

Examples

use zvec_rust::*;

collection.try_close()?;

Consuming the collection is what keeps a second close out of reach:

use zvec_rust::*;

collection.try_close()?;
collection.try_close()?;

Trait Implementations

impl Drop for Collection

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

impl Send for Collection

impl Sync for Collection