Enum surreal_simple_querybuilder::foreign_key::ForeignKey

pub enum ForeignKey<V, K> {
    Loaded(V),
    Key(K),
    Unloaded,
}

Represents foreign data, from a foreign node that may need to be fetched during the query or else it won’t be loaded or it will simply be the ID to a foreign node.

A ForeignKey field may have one of the following values:

• Loaded data,
• An ID,
• None of the above (null)

When a field is set as a ForeignKey<V, K> or a Foreign<V>, the field will always be serialized into an ID so you can be sure you won’t get raw data inserted into your nodes by mistake.

Pairs well with objects that store IDs in the surreal DB, that you can also load using the FETCH keyword of SurrealQL.

Imagining the following structure:

create User:John set name = "John";
create File set name = "John file", author = User:John;

which could be represented like so in Rust:

struct User {
  name: String
}

struct File {
  name: String,
  author: ForeignKey<User, String>
}

This will cause the serde_json library to attempt to parse the File::author as a User, and if it fails will then attempt to parse it as a String type (a string in our case since this is how SurrealDB stores IDs). And if the attempt to parse the ID fails as well it will default to the Unloaded variant of a ForeignKey

You are then free to use the ForeignKey’s methods to safely access the foreign data

let file: File; // = query("SELECT * from File FETCH author");

if let Some(user) = file.author.value() {
  // the file had an author and it was loaded
  dbg!(&user);
}

if let Some(user_id) = file.author.key() {
  // the file had an author ID, but it wasn't loaded
  dbg!(&user_id);
}

Note that if you plan to use ForeignKey<T, String> (where the second generic type is a string), you can use the Foreign<T> type in the same module to shorten the declaration.

Variants

Loaded(V)

Key(K)

Unloaded

Implementations

impl<V, K> ForeignKey<V, K>where
    V: Debug,
    V: IntoKey<K>,

pub fn value(&self) -> Option<&V>

Access the inner value by checking if it is loaded or not, thus returning an Option<&T> that is Some if it is loaded and None if it isn’t.

pub fn key(&self) -> Option<&K>

Access the inner key by checking if the foreign key is currently holding the key, thus returning a Some<&I> if it is one and None if it isn’t.

pub fn is_unloaded(&self) -> bool

Return whether the current ForeignKey is unloaded. Returns false if self is either a key or a loaded value.

pub fn set_value(&mut self, value: V)

Drop any data self may currently hold and set it to the Loaded variant with the given value.

pub fn set_key(&mut self, identifier: K)

Drop any data self may currently hold and set it to the Key variant with the given identifier.

pub fn unload(&mut self)

Drop the currently held value and set self to the Unloaded variant.

Trait Implementations

impl<V, K> Debug for ForeignKey<V, K>where
    V: Debug,
    K: Debug,

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<V, K> Default for ForeignKey<V, K>

fn default() -> Self

Returns the “default value” for a type.

impl<'de, V, K> Deserialize<'de> for ForeignKey<V, K>where
    V: Deserialize<'de>,
    K: Deserialize<'de>,

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>where
    __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<V, K> Serialize for ForeignKey<V, K>where
    V: IntoKey<K>,
    K: Serialize,
    V: Debug,

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>where
    S: Serializer,

Serialize this value into the given Serde serializer.