Expand description
§Surrealdb Config
Server-wide configuration constants, environment-variable defaults, and the
Config/ConfigMap mechanism each layer uses to declare and load its
own settings.
Unstable!
This crate is SurrealDB internal API. It does not adhere to SemVer and its API is free to change and break code even between patch versions. If you are looking for a stable interface to the SurrealDB library please have a look at the Rust SDK.Re-exports§
pub use config::Config;pub use config::ConfigMap;pub use config::format_duration;pub use config::parse_duration;pub use dynamic::DynamicConfiguration;
Modules§
- config
- Generic string-pair configuration map used to configure subsystems from environment variables, connection-string query parameters, or code.
- dynamic
Constants§
- ID_
CHARS - The characters which are supported in server record IDs
- NOTIFICATIONS_
CHANNEL_ SIZE - Default capacity for the bounded channel used to deliver live-query notifications from the datastore to subscribers.
- PROTECTED_
PARAM_ NAMES - Specifies the names of parameters which can not be specified in a query
- SERVER_
NAME - The publicly visible name of the server
- SYSTEM_
BOUND_ PARAM_ NAMES - Specifies the names the system binds itself in the frame of a clause, a field, an event or a
function body: the value a clause or an element filter reads (
this,self,parent), and the values an event or a field definition reads (value,input,before,after,event). They are not inPROTECTED_PARAM_NAMES: that list names the values read from the session, and the planner folds, captures and scopes by it, which these names are not.
Statics§
- BITMAP_
BRANCH_ BUDGET - Drained-entry budget for one range branch of a bitmap candidate plan
(default: 250000). A non-anchor range branch that drains more index
entries than this is abandoned — its predicate is instead enforced by the
residual WHERE filter — so an unselective range cannot make the bitmap
plan slower than the streaming plan it replaced.
0disables the budget. - DISKANN_
FILTER_ PREFETCH_ MAX_ CHUNK - Upper bound on the DiskANN filtered-KNN record-prefetch window (the geometric growth is capped here). Read once at first use.
- DISKANN_
FILTER_ PREFETCH_ MIN_ CHUNK - Initial (and minimum) window size for the DiskANN filtered-KNN record
prefetch. The committed-graph search prefetches candidate records in
distance-ascending windows that grow geometrically (doubling, capped by
DISKANN_FILTER_PREFETCH_MAX_CHUNK); this is the first window’s size and the floor. A smaller value bounds the over-fetch tighter when the result builder fills early (non-selective filters); a larger value amortises each window’s multi-get over more candidates. Read once at first use. - GENERATION_
ALLOCATION_ LIMIT - Used to limit allocation for builtin functions. Default: 2^20 (1 MiB), can be as large as 28 (2^28, 256 MiB)
- KNN_
PREFILTER_ EF_ BOOST efmultiplier for an allow-list-gated DiskANN search (default: 4). With an allow-list alone, DiskANN searches its toplcandidates and admits the members among them, so a selective allow-list leaves few admissible ones in that list; widening the search counteracts the loss. Applied asmax(ef, ef * boost)capped byKNN_PREFILTER_EF_MAX. An HNSW search is widened byKNN_PREFILTER_HNSW_EF_BOOSTinstead.- KNN_
PREFILTER_ EF_ BOOST_ THRESHOLD - Allow-list size above which the gated ANN traversal stops boosting
ef(default: 100000). Large allow-lists barely reject candidates on typical tables, so widening the search buys no recall; admission stays gated on bitmap membership at every size — an absolute cardinality says nothing about how near-universe the predicate really is, and an unrestricted search with a post-check would truncate results whenever the nearest overall neighbours are excluded. - KNN_
PREFILTER_ EF_ MAX - Ceiling for the boosted
efof an allow-list-gated ANN traversal (default: 1024). Never clamps below the user-requestedef. - KNN_
PREFILTER_ ENABLED - Master switch for pre-filtered vector search (#548, default: true).
When
false, KNN queries keep evaluating their WHERE residual inside the ANN traversal via per-candidate record fetches, exactly as before the allow-list bitmap prefilter existed. - KNN_
PREFILTER_ EXACT_ COST - The cost of scoring one allow-list member exactly from the vectors an HNSW
index stores, in distance computations of the gated graph traversal
(default: 5). The traversal admits about one candidate in
1 / sfor an allow-list holding a shares = members / nodesof the graph’s nodes, so it computes aboutef × degree / sdistances, while the exact tier scores every member; the exact tier is taken wherevermembers × costis at most that, which ismembers² × cost ≤ ef × degree × nodes(withscapped at one). A larger cost keeps more searches on the graph. - KNN_
PREFILTER_ EXACT_ THRESHOLD - Allow-list size at or below which a pre-filtered KNN search skips the
graph entirely and scores the members exactly (default: 2000). Below this
cardinality a bounded fetch-and-score over the bitmap is cheaper than a
graph traversal and — unlike filtered ANN search under a highly selective
filter — guaranteed to find the true top-K. Above it, an HNSW search that
can score the members from the vectors the index stores still takes the
exact tier wherever
KNN_PREFILTER_EXACT_COSTestimates it cheaper than the gated traversal. - KNN_
PREFILTER_ HNSW_ EF_ BOOST efmultiplier for an allow-list-gated HNSW traversal (default: 1, no widening). The gated traversal walks on past the candidates the allow-list rejects, so its recall at the requestedefholds up without widening. A wider search costs time in proportion and buys little recall, and none where the filter is selective enough that the traversal ends before it holdsefadmitted candidates, since that end does not depend onef; the exact tier serves such filters. Applied asmax(ef, ef * boost)capped byKNN_PREFILTER_EF_MAX.- MEMORY_
THRESHOLD - The tracked-memory ceiling, in bytes, above which queries are refused
(
SURREAL_MEMORY_THRESHOLD).0— the default — disables the guard entirely; any other value is floored to 1 MiB. - RAND_
SEED - Optional fixed seed for the deterministic data-generation RNG (see
surrealdb_expr::val::rnd). - REGEX_
CACHE_ SIZE - Specifies the number of computed regexes which can be cached in the engine (default: 1000)
- REGEX_
SIZE_ LIMIT - The maximum size of a compiled regular expression (default: 10 MiB)
- STRING_
SIMILARITY_ LIMIT - The maximum input string length for similarity/distance functions (default: 16384 bytes)
Functions§
- extract_
allowed_ paths - Parse an allowlist configuration string into a list of paths.
- hnsw_
build_ seed - The seed for the HNSW level-assignment RNG, or
Noneto seed from entropy. - is_
refused_ local_ let_ name - Whether a
LETwritten inside a frame — a block, a clause, a field, an event, a function body, stored code — may not bindname: a protected parameter name, and a name the system binds in that frame. ALETthe planner writes to bind a system name into a frame is exempt, seeSYSTEM_BOUND_PARAM_NAMES. - set_
default_ hnsw_ build_ seed - Install the process-wide fallback HNSW build seed used when
SURREAL_HNSW_BUILD_SEEDis unset, so a caller that wants reproducible graphs gets them without depending on its launcher exporting the variable. The environment variable still wins, which is what lets a single run be re-seeded from outside the process.