SurrealValue attributes

Reference for the #[surreal(...)] attributes used with the SurrealValue derive, covering renaming, defaults, flattening and enum tagging.

These attributes customise the SurrealValue derive, which is covered in Working with types along with the kind! macro and the Value helpers.

The SurrealValue derive uses its own #[surreal(...)] attribute that is inspired by Serde (familiar names, similar enum tagging ideas), but it is not Serde and not an inheritance of #[serde(...)] attributes.

Conversion runs through SurrealValue and its derive macro rather than Serde's Serialize and Deserialize. Where Serde would be reached for to customise field names or flattening, use the matching #[surreal(...)] form below.

Relationship to Serde

Idea	Serde	`SurrealValue` (`#[surreal(...)]`)
Rename one field / variant	`rename = "..."`	`rename = "..."`
Rename all fields / variants	`rename_all = "..."`	`rename_all = "..."` (same case strings as Serde)
Flatten nested object	`flatten`	`flatten`
Enum tagging	`tag` / `content` / `untagged`	`tag` / `content` / `untagged`
Missing field default	`default` / `default = "path"`	`default` / `default = "path"` (also on the container)
Catch-all unit variant	`other`	`other`
Skip a field	`skip`, `skip_serializing`, `skip_serializing_if`	Not supported on ordinary fields
Conditionally omit enum payload	(use field `skip_serializing_if`)	`skip_content` / `skip_content_if = "..."` on tagged enums
Serde-only types	(n/a)	`wrap` for `Serialize + Deserialize` types that do not implement `SurrealValue`
Tuple struct as array	(n/a)	`tuple`
Literal substitute for a unit	(n/a)	`value = ...`

Supported rename_all values match Serde’s usual set (lowercase, UPPERCASE, PascalCase, camelCase, snake_case, SCREAMING_SNAKE_CASE, kebab-case, SCREAMING-KEBAB-CASE). An explicit rename on a field or variant wins over the container rename_all.

#[surreal(uppercase)] and #[surreal(lowercase)] on enums are legacy aliases for rename_all = "UPPERCASE" and rename_all = "lowercase". Prefer rename_all in new code. Do not combine them with rename_all on the same enum.

The attributes below are the ones the derive currently recognises.

`surreal(default)`

The surreal(default) attribute fills in values when fields are missing during deserialisation. On a struct container, missing fields come from the type’s Default implementation. On a single field, use #[surreal(default)] for <T as Default>::default(), or #[surreal(default = "path")] for a custom function path.

use surrealdb::engine::any::connect;
use surrealdb_types::{SurrealValue, ToSql};

#[derive(SurrealValue)]
struct UserData {
    num: i32,
    other_num: i32,
}

#[derive(SurrealValue)]
#[surreal(default)]
struct UserDataDefault {
    num: i32,
    other_num: i32,
}

impl Default for UserDataDefault {
    fn default() -> Self {
        UserDataDefault {
            num: 10,
            other_num: 20,
        }
    }
}

#[tokio::main]
async fn main() {
    let db = connect("memory").await.unwrap();
    db.use_ns("ns").use_db("db").await.unwrap();

    let mut has_two_fields = db
        .query("CREATE user SET num = 10, other_num = 20")
        .await
        .unwrap();

    let mut has_one_field = db.query("CREATE user SET num = 5").await.unwrap();

    println!(
        "Regular deserialization from DB result: {}",
        has_two_fields
            .take::<Option<UserData>>(0)
            .unwrap()
            .unwrap()
            .into_value()
            .to_sql()
    );

    println!(
        "Deserialization using DB result plus default value: {}",
        has_one_field
            .take::<Option<UserDataDefault>>(0)
            .unwrap()
            .unwrap()
            .into_value()
            .to_sql()
    )
}

Regular deserialization from DB result: { num: 10, other_num: 20 }
Deserialization using DB result plus default value: { num: 5, other_num: 20 }

`surreal(rename)`

The surreal(rename) attribute is used to provide a different name for a field on the SurrealDB side than the one used in the Rust code.

use surrealdb_types::{SurrealValue, ToSql};

#[derive(SurrealValue)]
struct UserData {
    num: i32,
}

#[derive(SurrealValue)]
struct UserDataRename {
    #[surreal(rename = "user_num")]
    num: i32,
}

fn main() {
    let user_data = UserData { num: 555 };
    let user_data_rename = UserDataRename { num: 555 };

    println!("Before rename: {}", user_data.into_value().to_sql());
    println!("After rename: {}", user_data_rename.into_value().to_sql());
}

Before rename: { num: 555 }
After rename: { user_num: 555 }

`surreal(rename_all)`

Apply a case transform to every field name on a struct, or every variant name on an enum, unless a field or variant sets its own rename.

use surrealdb_types::{SurrealValue, ToSql};

#[derive(SurrealValue)]
#[surreal(rename_all = "camelCase")]
struct UserProfile {
    full_name: String,
    years_old: i64,
}

fn main() {
    let profile = UserProfile {
        full_name: "Ada".into(),
        years_old: 36,
    };
    // { fullName: 'Ada', yearsOld: 36 }
    println!("{}", profile.into_value().to_sql());
}

`surreal(flatten)`

Merge a nested object’s fields into the parent object instead of nesting them under one key. This is the Surreal equivalent of Serde’s #[serde(flatten)].

use surrealdb_types::{SurrealValue, ToSql, Value};

#[derive(SurrealValue)]
struct Coords {
    x: i64,
    y: i64,
}

#[derive(SurrealValue)]
struct Point {
    name: String,
    #[surreal(flatten)]
    coords: Coords,
}

fn main() {
    let point = Point {
        name: "origin".into(),
        coords: Coords { x: 0, y: 0 },
    };
    // { name: 'origin', x: 0, y: 0 }
    println!("{}", point.into_value().to_sql());
}

flatten cannot be combined with rename on the same field: there is no single key left to rename.

Note

A struct that flattens a field needs Value in scope, as in the import above. The code generated for flatten refers to Value without qualifying it, so leaving the import out fails to compile with cannot find type `Value` in this scope , reported against the SurrealValue derive rather than any line you wrote.

`surreal(uppercase)` and `surreal(lowercase)`

These two attributes are legacy aliases for rename_all = "UPPERCASE" and rename_all = "lowercase" on enums. Prefer rename_all when writing new types.

use surrealdb_types::{SurrealValue, ToSql};

#[derive(SurrealValue)]
enum LogLevel {
    Debug(String),
    Info(String),
}

#[derive(SurrealValue)]
#[surreal(uppercase)]
enum LogLevelUpper {
    Debug(String),
    Info(String),
}

#[derive(SurrealValue)]
#[surreal(lowercase)]
enum LogLevelLower {
    Debug(String),
    Info(String),
}

fn main() {
    let log_level = LogLevel::Debug("User1".into());
    let log_level_upper = LogLevelUpper::Debug("User1".into());
    let log_level_lower = LogLevelLower::Debug("User1".into());

    println!("Before attribute: {}", log_level.into_value().to_sql());
    println!("After uppercase: {}", log_level_upper.into_value().to_sql());
    println!("After lowercase: {}", log_level_lower.into_value().to_sql());
}

Before attribute: { Debug: 'User1' }
After uppercase: { DEBUG: 'User1' }
After lowercase: { debug: 'User1' }

`surreal(tuple)`

As SurrealQL does not have a tuple type, this attribute can be used to interface in which a Rust tuple struct is treated as an array (instead of a single value) and vice versa.

use surrealdb_types::{SurrealValue, ToSql};

#[derive(SurrealValue)]
struct UserData(i32);

#[derive(SurrealValue)]
#[surreal(tuple)]
struct UserDataTuple(i32);

fn main() {
    println!(
        "Without tuple attribute: {}",
        UserData(555).into_value().to_sql()
    );
    println!(
        "With tuple attribute: {}",
        UserDataTuple(555).into_value().to_sql()
    );
}

Without tuple attribute: 555
With tuple attribute: [555]

`surreal(untagged)`

The surreal(untagged) attribute removes the tag from the variant of an enum. This is similar to using VALUE in SurrealQL to show only the value and not the field name of a record.

use surrealdb_types::{SurrealValue, ToSql};

#[derive(SurrealValue)]
enum LogLevel {
    Debug(String),
    Info(String),
}

#[derive(SurrealValue)]
#[surreal(untagged)]
enum LogLevelUntagged {
    Debug(String),
    Info(String),
}

fn main() {
    let log_level = LogLevel::Debug("User1".into());
    let log_level_untagged = LogLevelUntagged::Debug("User1".into());

    println!("Before untagged: {}", log_level.into_value().to_sql());
    println!(
        "After untagged: {}",
        log_level_untagged.into_value().to_sql()
    );
}

Before untagged: { Debug: 'User1' }
After untagged: 'User1'

`surreal(tag)`

The surreal(tag) attribute can be used to give a tag to a variant. This will create a structure in which the new tag value is the field name, and the variant its value.

use surrealdb_types::{SurrealValue, ToSql};

#[derive(SurrealValue)]
enum LogLevel {
    Debug,
    Info,
}

#[derive(SurrealValue)]
#[surreal(tag = "log_level")]
enum LogLevelTag {
    Debug,
    Info,
}

fn main() {
    let log_level = LogLevel::Debug;
    let log_level_tag = LogLevelTag::Debug;
    println!("\n___surreal(tag)___");
    println!("Before tag: {}", log_level.into_value().to_sql());
    println!("After tag: {}", log_level_tag.into_value().to_sql());
}

Before tag: { Debug: {  } }
After tag: { log_level: 'Debug' }

`surreal(content)`

While the surreal(tag) attribute on its own can only be used on variants that do not hold data, the surreal(content) makes this possible.

use surrealdb_types::{SurrealValue, ToSql};

#[derive(SurrealValue)]
enum LogLevel {
    Debug(String),
    Info(String),
}

#[derive(SurrealValue)]
#[surreal(tag = "log_level", content = "user")]
enum LogLevelContent {
    Debug(String),
    Info(String),
}

fn main() {
    let log_level = LogLevel::Debug("User1".to_string());
    let log_level_tag = LogLevelContent::Debug("User1".to_string());

    println!("Before content: {}", log_level.into_value().to_sql());
    println!("After content: {}", log_level_tag.into_value().to_sql());
}

Before content: { Debug: 'User1' }
After content: { log_level: 'Debug', user: 'User1' }

`surreal(skip_content)` and `surreal(skip_content_if)`

On enums that use adjacent tagging (tag plus content), these control whether the content field is written (and whether it may be absent when reading).

They are the closest Surreal analogues to Serde’s skip_serializing_if, but they apply to the enum content field, not to arbitrary struct fields.

Attribute	Effect
`skip_content`	Never emit the content field for that enum or variant
`skip_content_if = "path"`	Emit content only when the predicate returns false (for example `Value::is_empty`)

use surrealdb_types::{SurrealValue, ToSql, Value};

#[derive(SurrealValue)]
#[surreal(tag = "kind", content = "details", skip_content_if = "Value::is_empty")]
enum ApiStatus {
    Ok,
    Error { message: String },
}

fn main() {
    // Unit variant: content omitted when empty
    // { kind: 'Ok' }
    println!("{}", ApiStatus::Ok.into_value().to_sql());

    // Named variant: content present when there is data
    // { kind: 'Error', details: { message: 'boom' } }
    println!(
        "{}",
        ApiStatus::Error {
            message: "boom".into()
        }
        .into_value()
        .to_sql()
    );
}

You can also put skip_content or skip_content_if on individual variants. They only apply to enums that already declare a tag (with or without content).

`surreal(other)`

On a unit variant, other marks a deserialisation catch-all: if no other variant matches, that variant is chosen instead of returning an error. At most one variant per enum should use it. It cannot be combined with rename or value on the same variant.

use surrealdb_types::SurrealValue;

#[derive(Debug, PartialEq, SurrealValue)]
#[surreal(untagged)]
enum WireFlag {
    #[surreal(value = true)]
    On,
    #[surreal(value = false)]
    Off,
    #[surreal(other)]
    Unknown,
}

`surreal(value)`

This attribute can be used on the fields of an enum marked with surreal(untagged) to give it a substitute value. The value that follows this attribute can be a NONE, NULL, bool, string, int, or float.

use surrealdb_types::{SurrealValue, ToSql};

fn main() {
    #[derive(Clone, Debug, SurrealValue)]
    #[surreal(untagged)]
    pub enum LogLevel {
        Regular,
        Verbose,
        Off,
    }

    #[derive(Clone, Debug, SurrealValue)]
    #[surreal(untagged)]
    pub enum LogLevelValue {
        #[surreal(value = "info")]
        Regular,
        #[surreal(value = "debug")]
        Verbose,
        #[surreal(value = NONE)]
        Off,
    }

    println!("Only untagged: {}", LogLevel::Off.into_value().to_sql());
    println!(
        "Untagged plus value: {}",
        LogLevelValue::Off.into_value().to_sql()
    );
}

With only untagged: 'Off'
With untagged plus substitute value: NONE

`surreal(wrap)`

This attribute can be used on fields with a type that implements serde's Serialize and Deserialize traits, but not SurrealValue.

This is meant for interoperability and should only be used if necessary.

use surrealdb_types::{SurrealValue, ToSql};
use serde::{Serialize, Deserialize};

#[derive(Clone, Debug, Serialize, Deserialize)]
pub struct ExternStruct {
    foo: String,
    bar: String,
}

#[derive(Clone, Debug, SurrealValue)]
pub struct OurStruct {
    baz: String,
    #[surreal(wrap)]
    external: ExternStruct
}

More examples

Here are some more examples from the SurrealDB source code showing how the surreal attribute can be used.

use surrealdb_types::{SurrealValue, Value};

#[derive(SurrealValue, Debug, PartialEq)]
#[surreal(untagged)]
enum EnumMixedWithValue {
    #[surreal(value = false)]
    None,
    Some(Vec<String>),
}

#[derive(SurrealValue, Debug, PartialEq)]
#[surreal(tag = "tag", content = "content")]
enum EnumTaggedWithTagAndContent {
    Foo,
    Bar { prop: String },
    Baz(String),
    Qux(String, i64),
}

#[derive(SurrealValue, Debug, PartialEq)]
#[surreal(tag = "tag", content = "content", lowercase)]
enum EnumTaggedWithTagAndContentLowercase {
    Foo,
}

#[derive(SurrealValue, Debug, PartialEq)]
#[surreal(tag = "tag", content = "content", uppercase)]
enum EnumTaggedWithTagAndContentUppercase {
    Foo,
}

#[derive(SurrealValue, Debug, PartialEq)]
#[surreal(tag = "tag")]
enum EnumTaggedWithTag {
    Foo,
    Bar { prop: String },
}

#[derive(SurrealValue, Debug, PartialEq)]
#[surreal(tag = "tag", lowercase)]
enum EnumTaggedWithTagLowercase {
    Foo,
}

#[derive(SurrealValue, Debug, PartialEq)]
#[surreal(tag = "tag", uppercase)]
enum EnumTaggedWithTagUppercase {
    Foo,
}

#[derive(SurrealValue, Debug, PartialEq)]
enum EnumTaggedVariant {
    Foo,
    Bar { prop: String },
    Baz(String),
    Qux(String, i64),
}

#[derive(SurrealValue, Debug, PartialEq)]
#[surreal(lowercase)]
enum EnumTaggedVariantLowercase {
    Foo,
}

#[derive(SurrealValue, Debug, PartialEq)]
#[surreal(uppercase)]
enum EnumTaggedVariantUppercase {
    Foo,
}

#[derive(SurrealValue, Debug, PartialEq)]
#[surreal(untagged)]
enum EnumUnitValue {
    #[surreal(value = true)]
    True,
    #[surreal(value = false)]
    False,
    #[surreal(value = null)]
    Null,
    #[surreal(value = none)]
    None,
    #[surreal(value = "Hello")]
    String,
    #[surreal(value = 123)]
    Int,
    #[surreal(value = 123.45)]
    Float,
}

#[derive(SurrealValue, Debug, PartialEq)]
#[surreal(untagged)]
enum EnumUntagged {
    Foo,
    Bar,
}

#[derive(SurrealValue, Debug, PartialEq)]
#[surreal(untagged, lowercase)]
enum EnumUntaggedLowercase {
    Foo,
    Bar,
}

#[derive(SurrealValue, Debug, PartialEq)]
#[surreal(untagged, uppercase)]
enum EnumUntaggedUppercase {
    Foo,
    Bar,
}

#[derive(SurrealValue, Debug, PartialEq)]
struct PersonRenamed {
    #[surreal(rename = "full_name")]
    name: String,
    #[surreal(rename = "years_old")]
    age: i64,
}

#[derive(SurrealValue, Debug, PartialEq)]
#[surreal(tuple)]
struct StringWrapperTuple(String);

#[derive(SurrealValue, Debug, PartialEq)]
#[surreal(value = true)]
struct UnitStructWithValue;

#[derive(Clone, Debug, SurrealValue, PartialEq)]
#[surreal(default)]
struct TestDefault {
    str: String,
    boolean: bool,
    optional: Option<String>,
}

impl Default for TestDefault {
    fn default() -> Self {
        TestDefault {
            str: "default".to_string(),
            boolean: true,
            optional: None,
        }
    }
}

fn main() {}

Relationship to Serde

surreal(default)

surreal(rename)

surreal(rename_all)

surreal(flatten)

surreal(uppercase) and surreal(lowercase)

surreal(tuple)

surreal(untagged)

surreal(tag)

surreal(content)

surreal(skip_content) and surreal(skip_content_if)

surreal(other)

surreal(value)

surreal(wrap)