Expand description
The SurrealDB catalog.
Schema definitions in two forms per entity: a Stored* twin persisted
with canonical SurrealQL text for its expression-bearing fields, and a
runtime form holding compiled ASTs, bridged by FromStored/to_stored.
The provider traits here are the read/write contract the datastore layer
implements to serve definitions to the engine.
Every persisted catalog entry is a keyed map in the stored-value grammar, declared once per type
by #[derive(Stored)] and frozen by catalog-schema.lock; entries a 3.x binary wrote in the
revision encoding stay readable. The envelope, the dispatch between the two grammars, the
feature-level rules and the embedded frame are described in stored.
This crate is an internal implementation detail of SurrealDB: its API is
unstable and changes without notice. Depend on the surrealdb SDK or
surrealdb-core instead.
Re-exports§
pub use feature::StoredFeatureLevel;pub use layout::Column;pub use layout::ColumnRole;pub use layout::GenerationLayout;pub use layout::LayoutDescriptor;pub use layout::LayoutRefusal;pub use layout::Location;pub use layout::MAX_PATH_DEPTH;pub use layout::PLANNED_PHYSICAL_KINDS;pub use layout::PackedDescriptor;pub use layout::PhysicalKind;pub use layout::Presence;pub use layout::RecordLayoutError;pub use layout::RowLayout;pub use layout::TableLayouts;pub use layout::VERIFIED_EPOCH;pub use layout::decode_generation;pub use schema::ApiMethod;pub use schema::DiskAnnParams;pub use schema::Distance;pub use schema::FullTextParams;pub use schema::HnswParams;pub use schema::Scoring;pub use schema::StoredApiDefinition;pub use schema::VectorType;pub use view_state::StoredStat;pub use view_state::ViewState;pub use surrealdb_iam as iam;pub use schema::*;pub use record::*;pub use view::*;
Modules§
- aggregation
- Common code related to aggregation calculations.
- api_
path - The API route-path vocabulary persisted by API definitions.
- auth
- expr
- The type definitions for the computation format of the surreaql executor.
- feature
- The store-wide feature level record. The store-wide feature level record.
- layout
- Row layouts of table generations. Row layouts of table generations: the immutable descriptor each generation’s rows are read against, and the set of them one table holds.
- node
- Cluster-node registration and liveness bookkeeping.
- packed
- Packed rows: writing and reading the rows of a packed descriptor.
Packed rows: the rows of a table generation whose descriptor
(
PackedDescriptor) lists columns, written bypack, and decoded whole byPackedRow::decode. A reader that takes a packed row in place takes it only as aCheckedPackedRow, whichStoredRecord::checked_packedmakes by walking the row through the same code as the whole decode, instantiated to build nothing. So an in-place read refuses every row the whole decode refuses, with the same error, whichever fields it asks for. - providers
- Catalog providers.
- record
- Record module for SurrealDB
- schema
- stored
- Catalog entries in the stored-value grammar. Catalog entries in the stored-value grammar.
- syn
- Compiles parser-next’s flat tree into logical plans and native payloads.
- val
- view
- view_
state - The running statistics of an aggregated view’s groups, in the stored grammar.
Macros§
- catalog_
vtable - Builds the
CatalogVTableof a type. - impl_
kv_ value_ catalog - Implements
KVValuefor a catalog type written in either grammar:revisionat the Legacy level, the stored grammar above it. - impl_
kv_ value_ stored - Implements
KVValuefor a catalog type that has norevisionform: the stored grammar only, refused at the Legacy level, and written only through the levelled transaction path.
Structs§
- Access
Grant - Access
Grant Walker - Walker for a revisioned struct. Generated by
#[revisioned(...)]. - Compiled
Subscription - The evaluable half of a subscription.
- Database
Compatibility - A database’s compatibility level: how strictly its
SCHEMAFULLtables hold their stored rows to their field definitions. - Database
Definition - Database
Definition Walker - Walker for a revisioned struct. Generated by
#[revisioned(...)]. - Database
Id - Field
Candidate - One field definition compiled for the claim rules (
birth_claims_of) and for the derivation of a packed layout (derive_layout). - Field
Claim - The claim that one field of a table conforms.
- Generation
- A generation of a table: a nonzero
u16, which names one descriptor of the table’s ring. - Generation
Mark - The highest generation minted for a table name of a database, stored under the database’s
!gnkey for that name. - Generation
Ring - A table’s generation ring: the generations from
basetoheadin mint order, and the floor. - Grant
Bearer - Grant
Bearer Walker - Walker for a revisioned struct. Generated by
#[revisioned(...)]. - Grant
Jwt - Grant
JwtWalker - Walker for a revisioned struct. Generated by
#[revisioned(...)]. - Grant
Record - Grant
Record Walker - Walker for a revisioned struct. Generated by
#[revisioned(...)]. - Grant
Walker - Walker for a revisioned enum. Generated by
#[revisioned(...)]. - Logical
Block Body - A block clause of a definition — a function body — compiled to its logical
operator on first use and kept for the life of the definition. The block
counterpart of
LogicalBody, with the same identity and caching rules. - Logical
Body - An expression clause of a definition, compiled to its logical form on first use and kept for the life of the definition.
- Migration
- The migration a generation carries: a name, unique per table, and what the migration does to a row stamped before it.
- Migration
Run - The permanent record that a table ran the migration whose name keys it.
- Migration
Test - The whole test a rewritten value must pass, as the catalog stood when its step was minted.
- Module
Executable Walker - Walker for a revisioned enum. Generated by
#[revisioned(...)]. - Namespace
Definition - Namespace
Definition Walker - Walker for a revisioned struct. Generated by
#[revisioned(...)]. - Namespace
Id - Node
Live Query - Node
Live Query Walker - Walker for a revisioned struct. Generated by
#[revisioned(...)]. - Relation
- Silo
Executable - Silo
Executable Walker - Walker for a revisioned struct. Generated by
#[revisioned(...)]. - Stored
Subscription Definition - Stored
Subscription Definition Walker - Walker for a revisioned struct. Generated by
#[revisioned(...)]. - Stored
Subscription Fields Walker - Walker for a revisioned enum. Generated by
#[revisioned(...)]. - Stored
Table Definition - Stored
Table Definition Walker - Walker for a revisioned struct. Generated by
#[revisioned(...)]. - Subject
Walker - Walker for a revisioned enum. Generated by
#[revisioned(...)]. - Subscription
Definition - Runtime form of
StoredSubscriptionDefinition. - Surql
Text - Canonical SurrealQL text stored in a catalog definition, tagged with the
type
Tit compiles back to. - Surrealism
Executable - Surrealism
Executable Walker - Walker for a revisioned struct. Generated by
#[revisioned(...)]. - Table
Conformance - The claims of a table, strictly ascending by field.
- Table
Definition - Runtime form of
StoredTableDefinition. - TableId
- Table
Migrations - A table’s generation ring, stored under the table’s
!mikey. - Table
Shape - What derivation reads of a table definition.
- Task
Lease - Represents a distributed task lease stored in the datastore.
- Task
Lease Walker - Walker for a revisioned struct. Generated by
#[revisioned(...)].
Enums§
- Conformance
- What is known of a field’s values across the rows of its table.
- Error
- A failure in the catalog layer.
- Grant
- Migration
Step - What a migration does to a row older than it.
- Module
Executable - Module
Name - The parsed name of an extension: an
ext::name, or the package release of an unnamed silo definition. - Stored
Subscription Fields - Subject
- Subscription
Fields - Runtime form of
StoredSubscriptionFields. - Subscription
Query - A subscription’s query, which may no longer compile.
- Table
Type - The type of records stored by a table
Constants§
- INERT_
SUBSCRIPTION_ MARKER - Marker appended to an inert subscription’s rendering.
Traits§
- From
Stored - Builds a runtime catalog form from its stored (canonical-text) counterpart.
- Surql
Target - A type that round-trips through the canonical SurrealQL text stored in catalog definitions.
Functions§
- birth_
claims - The claims a table takes at its birth from its field definitions, each definition given as its
FieldKeycomponent and stored value. - birth_
claims_ of - The claims a table takes at its birth from its compiled field definitions.
- definition_
digest - The digest of a field definition: FNV-1a-64 over its canonical stored bytes, with the 64 bits
read as an
i64. - derive_
layout - The layout the rows of
tableare written in at a generation minted now, derived from the table’s definition and its compiled field definitions alone. - extension_
name - The name SurrealQL addresses an extension by, from its storage name: a
named extension is stored as
mod::nameand addressed asext::name; an unnamed silo definition is stored assilo::org::pkg::<v>and addressed assilo::org::pkg<v>. Any other name is returned as it is. - from_
stored_ all - Build every runtime definition in a stored slice.
- table_
select_ permission - The SELECT permission guarding a table, for callers holding a table lookup that may have missed.
Type Aliases§
- Block
Text - Canonical text of a
{ ... }block (function bodies). - Expr
Text - Canonical text of an expression (
VALUE/ASSERT/WHEN/THEN/ permission clauses, API actions, fetch targets, …). - Fields
Text - Canonical text of a
SELECT-clause field list (live subscriptions). - Idiom
Text - Canonical text of an idiom path (index columns).
- Kind
Text - Canonical text of a kind-grammar type annotation (
TYPE, function argument/return types). - Logical
Block Text - Canonical text of a
{ ... }block, compiled to the logical operator the streaming engine runs. The same grammar and the same stored bytes asBlockText; only the compile target differs. SeeSurqlText::<Block>::to_logical. - Logical
Expr Text - Canonical text of an expression, compiled to the logical scalar the
streaming engine evaluates. The same grammar and the same stored bytes as
ExprText; only the compile target differs. SeeSurqlText::to_logical. - Path
Text - Canonical text of an API’s route path (
/users/:id<int>/*rest).