Collection API Reference

The Collection struct provides CRUD operations, indexing, and aggregation for a group of documents.

Installation

Add PocketDB to your Cargo.toml:

[dependencies]
pocketdb = "0.1"

Or via the command line:

cargo add pocketdb

Import

use pocketdb::collection::Collection;

Collections are obtained from Database::collection():

let col = db.collection("users")?;

Methods

Collection::name

pub fn name(&self) -> &str

Returns the collection name.

---

Collection::insert

pub fn insert(&self, doc: Document) -> Result<ObjectId>

Inserts a single document, returning its generated _id.

Parameters:

• doc — The document to insert

Returns: Result<ObjectId> — The inserted document's ID

Example:

use pocketdb::doc;

let id = col.insert(doc! { "name" => "Alice", "age" => 30 })?;

---

Collection::insert_many

pub fn insert_many(&self, docs: Vec<Document>) -> Result<Vec<ObjectId>>

Inserts multiple documents, returning their IDs.

Parameters:

• docs — Vector of documents to insert

Returns: Result<Vec<ObjectId>>

---

Collection::find

pub fn find(&self, filter: Filter) -> QueryBuilder

Returns a QueryBuilder for constructing and executing queries.

Parameters:

• filter — The filter expression

Returns: QueryBuilder

Example:

use pocketdb::filter;

let results = col.find(filter! { "age" => > 18 })
    .sort("age", SortDirection::Asc)
    .limit(10)
    .run(&col.all_documents())?;

---

Collection::find_one

pub fn find_one(&self, filter: &Filter) -> Option<Document>

Finds the first document matching the filter.

Parameters:

• filter — The filter expression

Returns: Option<Document>

---

Collection::update_one

pub fn update_one(&self, filter: &Filter, update: &UpdateExpression) -> Result<bool>

Updates the first document matching the filter.

Parameters:

• filter — The filter expression
• update — The update expression

Returns: Result<bool> — true if a document was updated

---

Collection::update_many

pub fn update_many(&self, filter: &Filter, update: &UpdateExpression) -> Result<usize>

Updates all documents matching the filter.

Returns: Result<usize> — Number of documents updated

---

Collection::replace_one

pub fn replace_one(&self, filter: &Filter, replacement: &Document) -> Result<bool>

Replaces the first matching document's body, keeping its _id.

Returns: Result<bool> — true if a document was replaced

---

Collection::upsert

pub fn upsert(&self, filter: &Filter, doc: &Document) -> Result<ObjectId>

Updates if a match exists, otherwise inserts.

Returns: Result<ObjectId> — The document's ID

---

Collection::delete_one

pub fn delete_one(&self, filter: &Filter) -> Result<bool>

Deletes the first document matching the filter.

Returns: Result<bool> — true if a document was deleted

---

Collection::delete_many

pub fn delete_many(&self, filter: &Filter) -> Result<usize>

Deletes all documents matching the filter.

Returns: Result<usize> — Number of documents deleted

---

Collection::count

pub fn count(&self, filter: &Filter) -> Result<usize>

Counts documents matching the filter.

Returns: Result<usize>

---

Collection::distinct

pub fn distinct(&self, field: &str, filter: &Filter) -> Result<Vec<PocketValue>>

Returns distinct values of a field across matching documents.

Returns: Result<Vec<PocketValue>>

---

Collection::bulk_write

pub fn bulk_write(&self, ops: Vec<BulkOp>) -> Result<usize>

Executes a batch of mixed operations atomically.

BulkOp variants:

• BulkOp::Insert(Document)
• BulkOp::UpdateOne(Filter, UpdateExpression)
• BulkOp::UpdateMany(Filter, UpdateExpression)
• BulkOp::DeleteOne(Filter)
• BulkOp::DeleteMany(Filter)
• BulkOp::ReplaceOne(Filter, Document)

Returns: Result<usize> — Number of affected documents

---

Collection::create_index

pub fn create_index(&self, spec: IndexSpec) -> Result<()>

Creates an index on this collection.

---

Collection::drop_index

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

Drops an index by name.

---

Collection::list_indexes

pub fn list_indexes(&self) -> Vec<String>

Returns the names of all indexes on this collection.

---

Collection::explain

pub fn explain(&self, filter: &Filter) -> ExplainPlan

Returns the query plan for a filter, showing which index will be used.

---

Collection::aggregate

pub fn aggregate(&self) -> AggregationPipeline

Returns an aggregation pipeline for this collection.

---

Collection::all_documents

pub fn all_documents(&self) -> Vec<Document>

Returns all documents in the collection.

---

Collection::len

pub fn len(&self) -> usize

Returns the document count.

---

Collection::is_empty

pub fn is_empty(&self) -> bool

Returns whether the collection is empty.