NyaruCollection

The collection name as passed to NyaruDB.collection(_:of:options:).

Inserts a new document into the collection.

The document must contain the configured idField. If another document with the same id already exists, a duplicateID error is thrown.

Inserts a batch of documents atomically.

All ids are validated before anything is written — if any id already exists in the collection or is duplicated within the batch, no documents are inserted and duplicateID is thrown.

Accumulates insert operations in memory and flushes them as a single batch when the body completes, producing one index merge pass instead of one per call.

Insertions inside the body are synchronous — no await required:

try await collection.insertBatch { batch in
  for chunk in incomingChunks { batch.insert(contentsOf: chunk) }
}

If the body throws, nothing is written to disk. This is a write buffer, not a transaction: update, delete, and patch are not buffered or rolled back — call them outside the batch.

Replaces the document with the same id.

The full document is replaced (not merged). If no document with the given id exists, documentNotFound is thrown. To insert-or-replace, use upsert instead.

Replaces the document with the same id, or inserts it if absent.

Unlike update, this never throws documentNotFound — if no document exists for the id, the document is inserted.

Deletes a document by its id.

The record is tombstoned in the shard file (space is reclaimed during compaction). The index entries are also removed.

Deletes multiple documents by id in a single batched pass: one storage hop per shard and one index sweep per field, instead of a full read/remove cycle per document.

Unknown ids are skipped (they do not count toward the result and do not throw).

Partially updates a document by applying top-level field changes without decoding the full document type.

This is useful when you want to change a few fields without fetching, decoding, modifying, re-encoding, and re-inserting the entire document. The merged document is validated against the type T before anything is written to disk.

Restrictions:

• Only top-level fields can be patched (nested paths like "address.city" are rejected).
• The document id field cannot be changed through patch.

• The merged result must still decode as T, otherwise the patch is rejected and no data is written.

Performs a point lookup by document id through the primary index.

Returns the total number of live documents in the collection.

Returns every document in the collection.

For large collections this materialises the entire dataset in memory. Consider using stream() for bounded-memory iteration.

Returns a pull-based async sequence over all documents.

Each next() call serves from an in-memory batch and only touches the collection actor when the batch is exhausted. Memory is bounded by one batch (batchSize elements), making this suitable for iterating large collections without materialising everything at once.

Returns a fluent query builder for this collection.

let results = try await collection.find()
    .where("age", isGreaterThan: 18)
    .sort(by: "name")
    .limit(10)
    .execute()

Rewrites every shard file to remove tombstoned records and rebuilds all indexes.

Call this opportunistically, such as when the app transitions to the background or after a significant number of deletions. There is no automatic background timer — compaction is always explicit.

Whether any shard’s tombstone ratio exceeds the configured DatabaseOptions.maxFragmentation threshold.

Use this to decide when to call compact() — for example, on app backgrounding:

if try await collection.needsCompaction() {
  try await collection.compact()
}

Returns a snapshot of collection statistics.

The returned CollectionStats includes the document count, shard count, total on-disk size, index entry counts, and the fragmentation ratio.