Skip to main content

surrealdb_catalog/
lib.rs

1//! The SurrealDB catalog.
2//!
3//! Schema definitions in two forms per entity: a `Stored*` twin persisted
4//! with canonical SurrealQL text for its expression-bearing fields, and a
5//! runtime form holding compiled ASTs, bridged by `FromStored`/`to_stored`.
6//! The provider traits here are the read/write contract the datastore layer
7//! implements to serve definitions to the engine.
8//!
9//! Every persisted catalog entry is a keyed map in the stored-value grammar, declared once per type
10//! by `#[derive(Stored)]` and frozen by `catalog-schema.lock`; entries a 3.x binary wrote in the
11//! `revision` encoding stay readable. The envelope, the dispatch between the two grammars, the
12//! feature-level rules and the embedded frame are described in [`stored`].
13//!
14//! This crate is an internal implementation detail of SurrealDB: its API is
15//! unstable and changes without notice. Depend on the `surrealdb` SDK or
16//! `surrealdb-core` instead.
17
18#![allow(clippy::mutable_key_type)]
19// TODO: Remove once this crate no longer needs it; see `absolute_paths` in the workspace lints.
20#![allow(clippy::absolute_paths)]
21
22#[macro_use]
23extern crate surrealdb_collections;
24#[macro_use]
25extern crate tracing;
26
27// The module tree spells intra-layer paths as `crate::catalog::<name>` and
28// names its neighbours as `crate::<layer>`; these aliases keep those paths
29// valid for the layers this crate sits on.
30pub use surrealdb_expr::{expr, parser as syn, val};
31pub use surrealdb_iam as iam;
32
33pub(crate) mod half {
34	pub use surrealdb_types::f16;
35}
36
37pub(crate) mod types {
38	//! The public type surface, re-exported with `Public` prefixes so internal
39	//! and public forms stay visually distinct at use sites.
40
41	#[allow(unused_imports)]
42	pub use surrealdb_types::{
43		Action as PublicAction, Array as PublicArray, Bytes as PublicBytes,
44		Datetime as PublicDatetime, Duration as PublicDuration, File as PublicFile,
45		Geometry as PublicGeometry, GeometryKind as PublicGeometryKind, Kind as PublicKind,
46		KindLiteral as PublicKindLiteral, Notification as PublicNotification,
47		Number as PublicNumber, Object as PublicObject, Range as PublicRange,
48		RecordId as PublicRecordId, RecordIdKey as PublicRecordIdKey,
49		RecordIdKeyRange as PublicRecordIdKeyRange, Set as PublicSet, SurrealValue,
50		Table as PublicTable, Uuid as PublicUuid, Value as PublicValue,
51		Variables as PublicVariables,
52	};
53}
54
55pub(crate) mod catalog {
56	//! Self-alias so `crate::catalog::` paths written inside the module tree
57	//! resolve against the crate root. Internal: the crate's own surface is its
58	//! root, and core re-exports that root as `catalog`.
59	pub(crate) use crate::*;
60}
61
62mod access;
63pub mod aggregation;
64/// The API route-path vocabulary persisted by API definitions.
65pub mod api_path;
66pub mod auth;
67mod compiled;
68mod conformance;
69mod database;
70mod error;
71/// The store-wide feature level record.
72pub mod feature;
73mod generation;
74/// Row layouts of table generations.
75pub mod layout;
76mod layout_derive;
77mod migration;
78mod module;
79mod namespace;
80/// Cluster-node registration and liveness bookkeeping.
81pub mod node;
82/// Packed rows: writing and reading the rows of a packed descriptor.
83pub mod packed;
84pub mod providers;
85pub mod record;
86pub mod schema;
87/// Catalog entries in the stored-value grammar.
88pub mod stored;
89mod subscription;
90mod table;
91mod task;
92mod text;
93pub mod view;
94pub mod view_state;
95
96pub use access::*;
97pub use compiled::*;
98pub use conformance::{
99	Conformance, FieldCandidate, FieldClaim, TableConformance, birth_claims, birth_claims_of,
100	definition_digest,
101};
102pub use database::*;
103pub use error::{Error, extension_name};
104pub use feature::StoredFeatureLevel;
105pub use generation::{Generation, GenerationMark, GenerationRing, TableMigrations};
106pub use layout::{
107	Column, ColumnRole, GenerationLayout, LayoutDescriptor, LayoutRefusal, Location,
108	MAX_PATH_DEPTH, PLANNED_PHYSICAL_KINDS, PackedDescriptor, PhysicalKind, Presence,
109	RecordLayoutError, RowLayout, TableLayouts, VERIFIED_EPOCH, decode_generation,
110};
111pub use layout_derive::{TableShape, derive_layout};
112pub use migration::{Migration, MigrationRun, MigrationStep, MigrationTest};
113pub use module::*;
114pub use namespace::*;
115pub use record::*;
116pub use schema::{
117	ApiMethod, DiskAnnParams, Distance, FullTextParams, HnswParams, Scoring, StoredApiDefinition,
118	VectorType, *,
119};
120pub use subscription::*;
121pub use table::*;
122pub use task::*;
123pub use text::*;
124pub use view::*;
125pub use view_state::{StoredStat, ViewState};
126
127impl From<Error> for crate::expr::ControlFlow {
128	/// Boxes the catalog failure directly, so it stays the concrete type in the
129	/// `anyhow` slot and the downcasts that steer `IF EXISTS` keep matching it.
130	fn from(error: Error) -> Self {
131		crate::expr::ControlFlow::Err(anyhow::Error::new(error))
132	}
133}