Struct Docs 

pub struct Docs<T> { /* private fields */ }

A collection of T.

Cheap to clone and cheap to keep around, the same way crate::Map is: the handle is a pointer and an index, and every clone is the same collection.

Implementations

impl<T: Document> Docs<T>

pub fn name(&self) -> Result<String>

The name this collection was opened under.

Errors

Code::Invalid if called from inside a callback that is already holding this database.

pub fn tag(&self) -> Tag

This collection’s shape tag.

pub fn put(&self, doc: &T) -> Result<bool>

Store a document, replacing whatever was under its id.

Answers whether the id was new. Every index the type declares is brought up to date in the same call, and the old document is taken back out of them first, so an overwrite cannot leave a stale posting behind.

Errors

Code::Invalid for an id that cannot be a key, and Code::Full for a value at an indexed path that is too long to be one.

pub fn get(&self, id: &<T::Id as Asked>::Ask) -> Result<Option<T>>

Read a document by its id.

Errors

Code::Corrupt if the stored document is not a T.

pub fn contains(&self, id: &<T::Id as Asked>::Ask) -> Result<bool>

Whether an id is in the collection, without reading the document.

Errors

Code::Invalid for an id that cannot be a key.

pub fn remove(&self, id: &<T::Id as Asked>::Ask) -> Result<bool>

Take a document out, answering whether it was there.

Errors

Code::Invalid for an id that cannot be a key.

pub fn len(&self) -> Result<usize>

How many documents there are.

Errors

Code::Invalid if called from inside a callback that is already holding this database.

pub fn is_empty(&self) -> Result<bool>

Whether the collection is empty.

Errors

The same as Docs::len.

pub fn all(&self) -> Result<Vec<T>>

Every document, in no particular order.

A walk of the whole collection, which is what it says it is. The indexed calls are the ones with a cost model.

Errors

Code::Corrupt if any stored document is not a T.

pub fn find<V: Asked>( &self, path: impl Into<Path<T, V>>, value: &V::Ask, ) -> Result<Vec<T>>

Every document whose value at path is value.

One probe of the index and one probe of the primary table per document in the answer, so the cost is the size of the answer rather than the size of the collection.

Errors

Code::Invalid if the collection has no index on that path, because a query that quietly turns into a scan is the thing this API exists not to do.

pub fn count<V: Asked>( &self, path: impl Into<Path<T, V>>, value: &V::Ask, ) -> Result<usize>

How many documents have value at path, without reading any of them.

The number to sort filters by before intersecting them, and it is a probe rather than a walk.

Errors

The same as Docs::find.

pub fn range<V: Asked, R: RangeBounds<V::Ask>>( &self, path: Ordered<T, V>, range: R, ) -> Result<Vec<T>>

Every document whose value at path falls in range, smallest first.

The bounds are the ordinary Rust range syntax, so .., a..b, a..=b and ..b all work and mean what they say.

Errors

Code::Invalid if the collection has no index on that path. An index that answers equality only cannot get here at all, because Ordered is a different type from Path and this takes one of them.

pub fn range_rev<V: Asked, R: RangeBounds<V::Ask>>( &self, path: Ordered<T, V>, range: R, ) -> Result<Vec<T>>

Docs::range backwards, largest value first.

Errors

The same as Docs::range.

pub fn count_range<V: Asked, R: RangeBounds<V::Ask>>( &self, path: Ordered<T, V>, range: R, ) -> Result<usize>

How many documents fall in range at path, without reading any.

This reads the distinct values in the range rather than the documents, so a range covering a million documents under a hundred values costs a hundred.

Errors

The same as Docs::range.

pub fn nearest(&self, path: Vector<T>, q: &[f32], k: usize) -> Result<Vec<T>>

The k documents whose embedding at path is nearest to q, nearest first.

Errors

Code::Invalid if q is not as wide as the path says, and Code::Corrupt if a stored document is not a T.

pub fn nearest_to( &self, path: Vector<T>, id: &<T::Id as Asked>::Ask, k: usize, ) -> Result<Vec<T>>

The k documents most like the one under id, that one left out.

More like this, which is the question a collection with embeddings in it is really for, and it does not make the caller read the document back out to get its vector first. A document with no embedding has nothing to be like, so this answers nothing rather than an error.

Errors

Code::Invalid for an id that cannot be a key, and Code::Corrupt if a stored document is not a T.

pub fn near<'a>(&'a self, path: Vector<T>, q: &'a [f32]) -> Near<'a, T>

A nearest neighbour search that other indexed fields can narrow.

#[derive(Yo, Debug)]
struct Note {
    #[yo(id)]
    id: u64,
    #[yo(index)]
    lang: String,
    #[yo(vector = 3)]
    embedding: Vec<f32>,
}

let close = notes
    .near(Note::EMBEDDING, &[1.0, 0.05, 0.0])
    .filter(Note::LANG, "en")
    .take(2)?;
assert_eq!(close.iter().map(|n| n.id).collect::<Vec<_>>(), [1, 3]);

Every filter is decided inside the scan rather than over the answers, so asking for two English notes gives the two nearest English notes and not whichever of the nearest few happened to be English. See yo_doc::vector for the encoding and for the one direction it is not exact in.

pub fn memory_bytes(&self) -> Result<usize>

What this collection is holding, documents and indexes together.

Errors

Code::Invalid if called from inside a callback that is already holding this database.

Trait Implementations

impl<T> Clone for Docs<T>

fn clone(&self) -> Docs<T>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<T> Debug for Docs<T>

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

Formats the value using the given formatter.