Surrealism attribute reference

The #[surrealism] attribute controls which Rust items are exported from your module and how SurrealDB should treat them.

Basic export

Use #[surrealism] on a function to expose it to SurrealQL:

use surrealism::surrealism;

#[surrealism]
fn can_drive(age: i64) -> bool {
    age >= 18
}

After packaging and DEFINE MODULE, this function is callable through your module path.

writeable

Mark functions that perform writes with writeable:

#[surrealism(writeable)]
fn kv_set_value(key: String, value: String) -> bool {
    // implementation snipped
    true
}

This metadata is used by the query planner so read-only and write-capable functions can be scheduled with appropriate transaction modes.

comment = "..."

Attach human-readable metadata to an export:

#[surrealism(comment = "Parses a decimal string into an integer")]
fn parse_number(input: String) -> Result<i64, String> {
    input.parse::<i64>().map_err(|e| e.to_string())
}

The comment appears in module metadata outputs such as:

• •

  surreal module info

• •

  INFO FOR DB STRUCTURE module export metadata

init

Register one initialisation hook that runs once after module instantiation:

#[surrealism(init)]
fn warm_cache() {
    // implementation omitted
}

Use this for one-time setup such as preloading attached files or priming in-module caches.

Namespaced modules

Apply #[surrealism] to modules to group exports under namespaces:

#[surrealism]
mod math {
    use surrealism::surrealism;

    #[surrealism]
    pub fn add(a: i64, b: i64) -> i64 {
        a + b
    }

    #[surrealism]
    pub mod util {
        use surrealism::surrealism;

        #[surrealism]
        pub fn negate(value: i64) -> i64 {
            -value
        }
    }
}

Exports are prefixed by namespace, for example:

• •

  math::add

• •

  math::util::negate

Related docs

• •

  Creating custom modules

• •

  Module architecture

• •

  Module command reference