Documentation: add information about surrealdb::sql, Id, Thing, ulid

[szabgab]

Description

I can use

use surrealdb::sql::{Id, Thing};
let id = Id::ulid();
let thing = Thing::from(("user", id));

But I can't seem to find the documentation:

https://docs.rs/surrealdb/latest/surrealdb/index.html?search=sql returns nothing

https://docs.rs/surrealdb/latest/surrealdb/index.html?search=ulid returns a link to https://docs.rs/surrealdb/latest/surrealdb/struct.Uuid.html but ulid is not mentioned on that page.

Neither https://docs.rs/surrealdb/latest/surrealdb/index.html?search=Id nor https://docs.rs/surrealdb/latest/surrealdb/index.html?search=Thing returns a page about the right thing. That would be surrealdb::sql::{Id, Thing}

More specifically I was looking for a way to convert a string (received via http) to an Id. Copilot suggested Id::from_ulid_str but that does not seem to exists. (yet 😄 ).

Is there an existing issue for this?

• I have searched the existing issues

Code of Conduct

• I agree to follow this project's Code of Conduct

[Dhghomon]

Ah, I think this has to do with some moving around between surrealdb and surrealdb_core. After some looking around I see the types are defined here and have their own section on docs.rs:

https://docs.rs/surrealdb-core/latest/surrealdb_core/sql/enum.Id.html

And inside the main lib.rs is a line that brings in all the content from surrealdb_core which is why you are able to import them that easily:

pub use surrealdb_core::*;

I think so, anyway! I'll tag @rushmorem just in case there is more to say about this.

[rushmorem]

In v2 the sql module is undocumented. This is intentional. Some new, SDK specific, types were introduced to replace types like Thing (now RecordId) and Id (now RecordIdKey). Unfortunately some of these types are still referenced in some of our examples. I'm actually working towards updating some of these examples now.

[Dhghomon]

That's awesome news! I was just thinking again just the other day that a name besides Thing would have been much nicer and lo and behold we have these new names. 2024년 10월 10일 (목) 오전 12:08, Rushmore Mushambi ***@***.***>님이 작성:

…

In v2 the sql module is undocumented. This is intentional <surrealdb/surrealdb#4498>. Some new, SDK specific, types were introduced to replace types like Thing (now RecordId) and Id (now RecordIdKey). Unfortunately some of these types are still referenced in some of our examples. I'm actually working towards updating some of these examples now. — Reply to this email directly, view it on GitHub <#893 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ANP2GLYXLPUW6PGAA4JKLH3Z2VBIHAVCNFSM6AAAAABO6WQMLKVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDIMBSGYYTAMJQGI> . You are receiving this because you were assigned.Message ID: ***@***.***>

[szabgab]

Thanks. So if I understand correctly Thing should be replaced by RecordId in my code.

It seems internally it is still called Thing which is very confusing when we print the Result. Using v2.0.4

e.g. the output of this code includes Thing

use serde::{Deserialize, Serialize};
use surrealdb::engine::local::Mem;
use surrealdb::{RecordId, Surreal};

#[tokio::main]
async fn main() -> surrealdb::Result<()> {
    let dbh = Surreal::new::<Mem>(()).await?;

    dbh.use_ns("demo").use_db("demo").await?;

    let res = dbh.query("CREATE entry CONTENT {
        number: 42,

    };").await?;
    match res.check() {
        Ok(val) => println!("Success: {val:?}"),
        Err(err) => println!("Error: {err}"),
    }
    Ok(())
}

Success: Response { client: Surreal { router: OnceLock(Router { sender: Sender { .. }, last_id: 2, features: {Backup, LiveQueries} }), engine: PhantomData<surrealdb::api::engine::any::Any> }, results: {0: (Stats { execution_time: Some(1.434877ms) }, Ok(Array(Array([Object(Object({"id": Thing(Thing { tb: "entry", id: String("1iqktq46inqa3ekw677r") }), "number": Number(Int(42))}))]))))}, live_queries: {} }