surrealdb_kvs/lib.rs
1//! # SurrealDB KVS
2//!
3//! Common types and traits shared by every SurrealDB key-value store backend:
4//! the [`Transactable`] transaction trait, the [`TransactionBuilder`] datastore
5//! abstraction, the raw [`Key`]/[`KeyRange`]/[`Val`] byte types, the
6//! [`key`]/[`value`] encoding contract a typed key and its stored value are
7//! written against, and the shared error, configuration, cursor, and timestamp
8//! machinery.
9//!
10//! This crate defines how a key and a value are *declared*; it does not declare
11//! any. Which keys exist is the keyspace, which lives above it.
12//!
13//! <section class="warning">
14//! <h3>Unstable!</h3>
15//! This crate is <b>SurrealDB internal API</b>. It does not adhere to SemVer and its API is
16//! free to change and break code even between patch versions. If you are looking for a stable
17//! interface to the SurrealDB library please have a look at
18//! <a href="https://crates.io/crates/surrealdb">the Rust SDK</a>.
19//! </section>
20
21pub mod api;
22pub mod builder;
23pub mod config;
24pub mod consts;
25pub mod cursor;
26pub mod destroy;
27pub mod err;
28pub mod isolation;
29pub mod key;
30pub mod maintenance;
31pub mod page;
32pub mod release;
33pub mod savepoint;
34pub mod snapshot;
35pub mod split;
36pub mod stale;
37#[cfg(any(test, feature = "test-utils"))]
38pub mod testing;
39pub mod threadpool;
40pub mod timestamp;
41mod types;
42pub mod value;
43
44pub use api::{
45 Batch, CountCost, GetMultiResult, KeysResult, RangeKeyVisitor, ScanCursorKeys, ScanCursorVals,
46 ScanResult, Transactable,
47};
48pub use builder::{Metric, Metrics, TransactionBuilder};
49pub use destroy::{DestroyRange, DestroyRangeHandle};
50pub use err::{Error, Result};
51pub use isolation::{Isolation, IsolationLevels, IsolationLevelsHandle};
52pub use maintenance::{Maintenance, MaintenanceHandle};
53pub use page::Page;
54pub use release::{FeatureLevel, Release};
55pub use savepoint::SavepointStack;
56pub use snapshot::{RangeCursor, Resume, Snapshot};
57pub use split::{Estimate, SplitTarget};
58pub use stale::{
59 MAX_POSITION_BYTES, ReadOutcome, ReadSnapshotRequest, SnapshotInfo, SnapshotPosition,
60 StaleReads, StaleReadsHandle,
61};
62pub use types::{Key, KeyRange};
63pub use value::{EncodeContext, Encoded};
64
65/// The value part of a key-value pair. An alias for [`Vec<u8>`].
66pub type Val = Vec<u8>;
67
68/// The Version part of a key-value pair. An alias for [`u64`].
69pub type Version = u64;
70
71/// Specifies whether the transaction is read-only or writeable.
72#[derive(Copy, Clone, Eq, PartialEq)]
73pub enum TransactionType {
74 Read,
75 Write,
76}
77
78/// The direction of a scan over a key range.
79///
80/// Defined here so every layer (backends, exec operators, indices, doc
81/// machinery) can name it without depending on a storage backend or a
82/// stream-scanner module.
83#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
84pub enum Direction {
85 /// Iterate from `range.start` toward `range.end` (lex-ascending).
86 Forward,
87 /// Iterate from `range.end - 1` toward `range.start` (lex-descending).
88 Backward,
89}
90
91/// Names the direction as a query plan reports it. These two strings appear
92/// in `EXPLAIN` output that clients read, so they are part of the public
93/// surface and must not change.
94impl std::fmt::Display for Direction {
95 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
96 match self {
97 Direction::Forward => f.write_str("forward"),
98 Direction::Backward => f.write_str("backward"),
99 }
100 }
101}