Skip to main content

Crate surrealdb_cnf

Crate surrealdb_cnf 

Source
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 in PROTECTED_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. 0 disables 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
ef multiplier for an allow-list-gated DiskANN search (default: 4). With an allow-list alone, DiskANN searches its top l candidates 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 as max(ef, ef * boost) capped by KNN_PREFILTER_EF_MAX. An HNSW search is widened by KNN_PREFILTER_HNSW_EF_BOOST instead.
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 ef of an allow-list-gated ANN traversal (default: 1024). Never clamps below the user-requested ef.
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 / s for an allow-list holding a share s = members / nodes of the graph’s nodes, so it computes about ef × degree / s distances, while the exact tier scores every member; the exact tier is taken wherever members × cost is at most that, which is members² × cost ≤ ef × degree × nodes (with s capped 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_COST estimates it cheaper than the gated traversal.
KNN_PREFILTER_HNSW_EF_BOOST
ef multiplier 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 requested ef holds 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 holds ef admitted candidates, since that end does not depend on ef; the exact tier serves such filters. Applied as max(ef, ef * boost) capped by KNN_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 None to seed from entropy.
is_refused_local_let_name
Whether a LET written inside a frame — a block, a clause, a field, an event, a function body, stored code — may not bind name: a protected parameter name, and a name the system binds in that frame. A LET the planner writes to bind a system name into a frame is exempt, see SYSTEM_BOUND_PARAM_NAMES.
set_default_hnsw_build_seed
Install the process-wide fallback HNSW build seed used when SURREAL_HNSW_BUILD_SEED is 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.