# Scans > UStore for Rust `use ustore::BlobsCursorConfig;` `use ustore::BlobsSampleConfig;` `use ustore::Cursor;` `use ustore::Measurement;` `use ustore::Page;` `use ustore::Scanned;` `use ustore::Sample;` `use ustore::Admission;` `use ustore::CaseSensitivity;` `use ustore::ChangeKind;` `use ustore::Changes;` `use ustore::ChangesCursor;` `use ustore::ChangesCursorConfig;` `use ustore::KeyRange;` `use ustore::Matching;` `use ustore::PatternKind;` `use ustore::PredicateCost;` `use ustore::ScanDirection;` `use ustore::ScanMode;` `use ustore::DocsCursor;` `use ustore::DocsCursorConfig;` `use ustore::DocsSampleConfig;` `use ustore::DocsScanConfig;` `use ustore::PagesCursor;` `use ustore::PagesCursorConfig;` `use ustore::PagesSampleConfig;` `use ustore::blobs::Scan;` `use ustore::blobs::Sample;` `use ustore::blobs::Measure;` `use ustore::docs::DocsScan;` `use ustore::docs::DocsSample;` `use ustore::docs::DocsMeasure;` `use ustore::pages::PagesSample;` `use ustore::pages::PagesMeasure;` `use ustore::*;` ## PredicateCallback A caller's verdict on one page of listed keys, writing one [`Admission`](#Admission) per key, every one starting as [`Admission::Reject`](#Reject). ```rust pub type PredicateCallback<'handler> = dyn FnMut(&[Key], &mut [Admission]) + Send + 'handler; ``` It runs on whichever thread runs the call, never on two at once within one call, so it owes `Send` and may be `FnMut`. A panic inside it rejects the rest of the call's keys and resurfaces once the call is final. Mirrors `ustore_predicate_callback_t`. ## BlobsCursorConfig What admits the keys a cursor hands out; see [`On::cursor`](https://www.unum.cloud/docs/ustore/rust/batches-and-arenas.md#cursor). ```rust pub struct BlobsCursorConfig<'config> ``` - `matching` `Matching<'config>`: Admits only the keys it approves; every key by default. Implements: `Debug`, `Default`, `From<[Matching](#Matching)<'config>>` ## BlobsSampleConfig The keys a sample draws; see [`On::sample`](https://www.unum.cloud/docs/ustore/rust/batches-and-arenas.md#sample). ```rust pub struct BlobsSampleConfig ``` - `wanted` `usize`: Keys drawn, at most. Implements: `Clone`, `Copy`, `Debug`, `From` ## Cursor A walk over the keys of one collection, which every pull resumes past the last key the pull before it handed out, so a key written behind the walk is never handed out and one written ahead of it is; see [`On::cursor`](https://www.unum.cloud/docs/ustore/rust/batches-and-arenas.md#cursor). ```rust pub struct Cursor<'view> ``` A page shorter than `wanted` exhausts the walk for good, so every pull after it hands out nothing, even once more keys are written. A pull that fails leaves the cursor where it was. Mirrors `ustore_blobs_cursor_t`; dropping it calls `ustore_blobs_cursor_free`. Implements: `Debug`, `Drop` ## * Pulls up to `wanted` next keys into `arena`, fewer once the walk nears its end and none past it. ```rust pub fn next<'arena>(&mut self, wanted: usize, arena: &'arena mut Arena) -> Result<&'arena [Key]> ``` Calls `ustore_blobs_cursor_next`. Calls `ustore_docs_cursor_next`. Calls `ustore_pages_cursor_next`. ## next_pairs Pulls up to `wanted` next keys with their values into `arena` in one call, where a key removed at the head between the listing and the read of one pull reads as an empty value. ```rust pub fn next_pairs<'arena>( &mut self, wanted: usize, arena: &'arena mut Arena, ) -> Result> ``` Calls `ustore_blobs_cursor_next`. ## Measurement The bounds one measurement reported over a range of keys, each a lower and an upper estimate. ```rust pub struct Measurement ``` - `min_cardinality` `usize`: Lower bound on the keys in the range. - `max_cardinality` `usize`: Upper bound on the keys in the range. - `min_value_bytes` `u64`: Lower bound on the bytes of values in the range. - `max_value_bytes` `u64`: Upper bound on the bytes of values in the range. - `min_space_usage` `u64`: Lower bound on the disk space the range takes. - `max_space_usage` `u64`: Upper bound on the disk space the range takes. Implements: `Clone`, `Copy`, `StructuralPartialEq`, `PartialEq`, `Eq`, `Debug`, `Default`, `Hash` ## Page The keys one pull of a [`Cursor`](#Cursor) handed out, with their values on one tape in the arena; see [`Cursor::next_pairs`](#next_pairs). ```rust pub struct Page<'arena> ``` Implements: `Clone`, `Copy`, `Debug` ## keys The keys of the page, in their order. ```rust pub fn keys(&self) -> &'arena [Key] ``` ## get The value of the key at `index`, or [`None`](https://www.unum.cloud/docs/ustore/rust/transactions.md#None) past the end of the page. ```rust pub fn get(&self, index: usize) -> Option<&'arena [u8]> ``` ## tape Every value of the page on the one tape the pull exported, without a copy. ```rust pub fn tape(&self) -> Tape<'arena> ``` ## Scanned The keys one scan listed, and their BM25 scores when its patterns carried weights; see [`On::scan`](https://www.unum.cloud/docs/ustore/rust/batches-and-arenas.md#scan). ```rust pub struct Scanned<'arena> ``` - `keys` `&'arena [Key]`: The keys, in the order of the scan's direction. - `scores` `Option<&'arena [f32]>`: One score per key when the patterns carried weights. Implements: `Clone`, `Copy`, `Debug` ## Sample Keys drawn at random from a collection, with the values read under them through the same view into an arena. ```rust pub struct Sample<'arena> ``` Implements: `Clone`, `Debug` ## keys The keys drawn, in the order of their values. ```rust pub fn keys(&self) -> &[Key] ``` ## values The value under every key, where a key removed between the draw and the read is missing. ```rust pub fn values(&self) -> Values<'arena> ``` ## Sample A random draw of keys from one collection; see [`On::sample`](https://www.unum.cloud/docs/ustore/rust/batches-and-arenas.md#sample). ```rust pub struct Sample<'arena> ``` Implements: `Debug` ## Admission Whether a predicate keeps a listed key or passes over it, as `ustore_admission_t` spells it. ```rust pub enum Admission ``` - `Reject` = `0`: Pass over the key. - `Admit` = `1`: Keep the key among the listed ones. Implements: `Clone`, `Copy`, `StructuralPartialEq`, `PartialEq`, `Eq`, `Debug`, `Default`, `Hash` ## CaseSensitivity Whether patterns compare bytes as they are or after Unicode case folding, as `ustore_case_sensitivity_t` spells it. ```rust pub enum CaseSensitivity ``` - `Cased` = `0`: Bytes as they are. - `Uncased` = `1`: Full Unicode case folding of both the patterns and the values. Implements: `Clone`, `Copy`, `StructuralPartialEq`, `PartialEq`, `Eq`, `Debug`, `Default`, `Hash`, `Display`, `FromStr` ## ChangeKind What one committed change did to its key. ```rust pub enum ChangeKind ``` - `Write` = `0`: Wrote the whole value. - `Removal` = `1`: Removed the key. - `Change` = `2`: Changed part of the value, as a document patch or a page edit does. Implements: `Clone`, `Copy`, `StructuralPartialEq`, `PartialEq`, `Eq`, `Debug`, `Hash`, `Display`, `FromStr` ## Changes The changes one pull of a [`ChangesCursor`](#ChangesCursor) handed out, oldest first, in the arena it filled. ```rust pub struct Changes<'arena> ``` Implements: `Clone`, `Copy`, `Debug` ## len How many changes the pull handed out. ```rust pub fn len(&self) -> usize ``` ## is_empty Whether the feed reached the newest commit. ```rust pub fn is_empty(&self) -> bool ``` ## keys The key of every change. ```rust pub fn keys(&self) -> &'arena [Key] ``` ## stamps The stamp every change was committed at. ```rust pub fn stamps(&self) -> &'arena [CommitStamp] ``` ## kinds What every change did. ```rust pub fn kinds(&self) -> &'arena [ChangeKind] ``` ## value The bytes the change at `index` carries, empty for a removal, or [`None`](https://www.unum.cloud/docs/ustore/rust/transactions.md#None) past the end or when the pull read no values. ```rust pub fn value(&self, index: usize) -> Option<&'arena [u8]> ``` ## ChangesCursor A feed of the changes committed to one collection after a stamp, oldest first, which every pull resumes past the last change the pull before it handed out; see [`Database::changes_cursor`](https://www.unum.cloud/docs/ustore/rust/quickstart.md#changes_cursor). ```rust pub struct ChangesCursor<'database> ``` It pins the stamp it reads from, as a snapshot does, and holds its database open until it is dropped. A pull that fails leaves it where it was. Implements: `Debug`, `Drop` ## next Pulls up to `wanted` next changes into `arena`, none once the feed is at its newest commit. ```rust pub fn next<'arena>(&mut self, wanted: usize, arena: &'arena mut Arena) -> Result> ``` ## next_pairs Pulls up to `wanted` next changes with the bytes every one carries into `arena` in one call. ```rust pub fn next_pairs<'arena>( &mut self, wanted: usize, arena: &'arena mut Arena, ) -> Result> ``` ## ChangesCursorConfig Where a feed of changes starts; see [`Database::changes_cursor`](https://www.unum.cloud/docs/ustore/rust/quickstart.md#changes_cursor). ```rust pub struct ChangesCursorConfig ``` - `since` `CommitStamp`: The feed hands out the changes committed after this stamp. Implements: `Clone`, `Copy`, `Debug`, `Default`, `From<[CommitStamp](https://www.unum.cloud/docs/ustore/rust/transactions.md#CommitStamp)>` ## KeyRange The keys a scan, a cursor or a measure walks: from `start`, inclusive, towards `end`, exclusive, in the order `direction` names. ```rust pub struct KeyRange ``` A key converts into the ascending range from it, and `start..end` into the one between them. - `start` `Option`: The key the walk starts from, or [`None`](https://www.unum.cloud/docs/ustore/rust/transactions.md#None) for the first key in its direction. - `end` `Option`: The key the walk stops before, or [`None`](https://www.unum.cloud/docs/ustore/rust/transactions.md#None) to walk to the last key in its direction. - `direction` `ScanDirection`: Which way the walk goes from `start`. Implements: `Clone`, `Copy`, `StructuralPartialEq`, `PartialEq`, `Eq`, `Debug`, `Default`, `Hash`, `From<[Key](https://www.unum.cloud/docs/ustore/rust/collections.md#Key)>`, `From>` ## Matching What a scan or a cursor narrows its keys by, every part left empty to keep every key: patterns over the values of blobs, a JSONPath or XPath filter over documents and pages, and a predicate over the keys. ```rust pub struct Matching<'matching> ``` Mirrors the `patterns`, `filter` and `predicate` fields of `ustore_blobs_scan_t` and its kin. - `patterns` `&'matching [&'matching str]`: The patterns every listed value matches one of, compiled once per call or once per cursor. - `pattern_kind` `PatternKind`: What the patterns are matched as. - `sensitivity` `CaseSensitivity`: Whether matching folds case. - `weights` `Option<&'matching [f32]>`: One weight per substring pattern, which turns on BM25 scores. - `filter` `Option<&'matching str>`: The JSONPath, root filter or XPath every listed document or page matches. - `predicate` `Option<&'matching mut PredicateCallback<'matching>>`: The caller's verdict on the keys of every page. - `predicate_cost` `PredicateCost`: Where the predicate is asked. Implements: `From<[Matching](#Matching)<'config>>`, `Default`, `Debug` ## PatternKind What the patterns of a [`Matching`](#Matching) are matched as, as `ustore_pattern_kind_t` spells it. ```rust pub enum PatternKind ``` - `Regex` = `0`: Regular expressions, of which a value matches at least one somewhere. - `Substrings` = `1`: Literal substrings, of which a value holds at least one. Implements: `Clone`, `Copy`, `StructuralPartialEq`, `PartialEq`, `Eq`, `Debug`, `Default`, `Hash`, `Display`, `FromStr` ## PredicateCost Where a scan asks its predicate, as `ustore_predicate_cost_t` spells it. ```rust pub enum PredicateCost ``` - `Cheap` = `0`: Once per page, before patterns or filters read any value, so it narrows those reads. - `Expensive` = `1`: Once per page about the keys patterns and filters kept, for handlers that pay per call. Implements: `Clone`, `Copy`, `StructuralPartialEq`, `PartialEq`, `Eq`, `Debug`, `Default`, `Hash`, `Display`, `FromStr` ## ScanDirection Which way a scan, a cursor or a measure walks its range from the start key. ```rust pub enum ScanDirection ``` - `Ascending` = `0`: Up from the start key, smallest key first. - `Descending` = `1`: Down from the start key, largest key first. Implements: `Clone`, `Copy`, `StructuralPartialEq`, `PartialEq`, `Eq`, `Debug`, `Default`, `Hash`, `Display`, `FromStr` ## ScanMode In what order a scan hands its keys over. ```rust pub enum ScanMode ``` - `Ordered` = `0`: In the order of the scan's direction. - `Unordered` = `1`: In any order, possibly removed or repeated, to speed up the read after the scan. Implements: `Clone`, `Copy`, `StructuralPartialEq`, `PartialEq`, `Eq`, `Debug`, `Default`, `Hash`, `Display`, `FromStr` ## DocsCursor A walk over the keys of one documents collection, which every pull resumes past the last key the pull before it handed out, as a [`crate::Cursor`](#Cursor) walks blobs, keeping the keys its [`Matching`](#Matching) admits. ```rust pub struct DocsCursor<'view> ``` Mirrors `ustore_docs_cursor_t`; dropping it calls `ustore_docs_cursor_free`. Implements: `Debug`, `Drop` ## next_pairs Pulls up to `wanted` next keys with their whole documents into `arena` in one call. ```rust pub fn next_pairs<'arena>( &mut self, wanted: usize, arena: &'arena mut Arena, ) -> Result> ``` Calls `ustore_docs_cursor_next`. ## DocsCursorConfig What admits the keys a cursor hands out; see [`On::docs_cursor`](https://www.unum.cloud/docs/ustore/rust/batches-and-arenas.md#docs_cursor). ```rust pub struct DocsCursorConfig<'config> ``` - `matching` `Matching<'config>`: Admits only the documents its filter and predicate approve; every document by default. Implements: `Debug`, `Default`, `From<[Matching](#Matching)<'config>>` ## DocsSampleConfig The document keys a sample draws; see [`On::docs_sample`](https://www.unum.cloud/docs/ustore/rust/batches-and-arenas.md#docs_sample). ```rust pub struct DocsSampleConfig ``` - `wanted` `usize`: Keys drawn, at most. Implements: `Clone`, `Copy`, `Debug`, `From` ## DocsScanConfig The document keys a scan keeps, what admits them and how it reports; see [`On::docs_scan`](https://www.unum.cloud/docs/ustore/rust/batches-and-arenas.md#docs_scan). ```rust pub struct DocsScanConfig<'config> ``` - `wanted` `usize`: Keys kept, at most. - `matching` `Matching<'config>`: Admits only the documents its filter and predicate approve; every document by default. - `mode` `ScanMode`: In what order the keys come. - `progress` `Option<&'config mut ProgressCallback<'config>>`: Reports the scans finished and stops wherever it says to. Implements: `From` ## PagesCursor A walk over the keys of one pages collection, which every pull resumes past the last key the pull before it handed out, as a [`crate::Cursor`](#Cursor) walks blobs, keeping the keys its [`Matching`](#Matching) admits. ```rust pub struct PagesCursor<'view> ``` Mirrors `ustore_pages_cursor_t`; dropping it calls `ustore_pages_cursor_free`. Implements: `Debug`, `Drop` ## next_pairs Pulls up to `wanted` next keys with their pages rendered as `encoding` names into `arena` in one call. ```rust pub fn next_pairs<'arena>( &mut self, wanted: usize, arena: &'arena mut Arena, encoding: PageEncoding, ) -> Result> ``` Calls `ustore_pages_cursor_next`. ## PagesCursorConfig What admits the page keys a cursor hands out; see [`On::pages_cursor`](https://www.unum.cloud/docs/ustore/rust/batches-and-arenas.md#pages_cursor). ```rust pub struct PagesCursorConfig<'config> ``` - `matching` `Matching<'config>`: Admits only the pages its filter and predicate approve; every page by default. Implements: `Debug`, `Default`, `From<[Matching](#Matching)<'config>>` ## PagesSampleConfig The page keys a sample draws; see [`On::pages_sample`](https://www.unum.cloud/docs/ustore/rust/batches-and-arenas.md#pages_sample). ```rust pub struct PagesSampleConfig ``` - `wanted` `usize`: Page keys drawn, at most. Implements: `Clone`, `Copy`, `Debug`, `From` ## Scan A walk over the keys of one collection; see [`On::scan`](https://www.unum.cloud/docs/ustore/rust/batches-and-arenas.md#scan). ```rust pub struct Scan<'arena, 'matching> ``` Implements: `Debug` ## Measure An estimate of what a range of keys holds; see [`On::measure`](https://www.unum.cloud/docs/ustore/rust/batches-and-arenas.md#measure). ```rust pub struct Measure<'arena> ``` Implements: `Debug` ## DocsScan A walk over the document keys of one collection; see [`On::docs_scan`](https://www.unum.cloud/docs/ustore/rust/batches-and-arenas.md#docs_scan). ```rust pub struct DocsScan<'arena, 'matching> ``` Implements: `Debug` ## DocsSample A random draw of document keys from one collection; see [`On::docs_sample`](https://www.unum.cloud/docs/ustore/rust/batches-and-arenas.md#docs_sample). ```rust pub struct DocsSample<'arena> ``` Implements: `Debug` ## DocsMeasure An estimate of what a range of documents holds; see [`On::docs_measure`](https://www.unum.cloud/docs/ustore/rust/batches-and-arenas.md#docs_measure). ```rust pub struct DocsMeasure<'arena> ``` Implements: `Debug` ## PagesSample A random draw of page keys from one collection; see [`On::pages_sample`](https://www.unum.cloud/docs/ustore/rust/batches-and-arenas.md#pages_sample). ```rust pub struct PagesSample<'arena> ``` Implements: `Debug` ## PagesMeasure An estimate of what a range of pages holds; see [`On::pages_measure`](https://www.unum.cloud/docs/ustore/rust/batches-and-arenas.md#pages_measure). ```rust pub struct PagesMeasure<'arena> ``` Implements: `Debug`