Documentation: offer examples that are more real and complex

[jasonjurotich]

Description

I am just beginning to use surreal and I realized that the examples are not sufficient to be able to use them in many real life scenarios. I am using the Rust SDK for everything up to now.

For example, at least for me, but I don't think I am the only one with this case, I pull in json responses from http requests, and there can be over 50 different types of json values because I am using APIs from Google, Stripe, Notion, Whatsapp, etc. and trying to set up structs for all this, along with concrete fields for each key in the json responses for surreal fields would cause a massive amount of boilerplate (given that some json responses can have up to 50 key value pairs, etc.).

Most of the time I need to receive the json response from wherever it comes and throw the entire thing in a field (or column if this was postgres) and then just query what is inside these responses. In this case, I am not going to create structs for all these, but rather pull info out as generic values (as in a Vec in Rust) and pass it to another function to do something with it, or create another table in surreal to use instead of Structs in order to run a simpler query somewhere else.

As well, I need to relate multiple fields from different tables, but again, I can't create record links or graphs with these both because the boilerplate would be enormous if I did that for everything, and also because many times I will not know what the keys are, and even when I do know what they are, sometimes the values change (like emails) so I have to use uuids for the record ids, which makes making record links very difficult (from what I understand, but I could be wrong here).

The point is, it would be very useful to have better and more real examples in the documentation to understand how to take better advantage of what surreal can do, indifferent as to whether my case is super rare, or not "common" (in the case that everyone religiously tries to use structs for everything, no matter how complex it gets or how much boilerplate it produces).

As an example, I have this below, which I figured out after a ton of guessing and battling with claude (which seems to be the only LLM with any real knowledge of surreal right now), but which I know is probably not the best or the most efficient, and besides that, I am sure that the outcome I need could be done with function inside of surreal, but I still don't have clear how that would work.

So here is my example below, and hopefully can be used to clarify everything I put above, in order to give a better idea of what could be good to add to the documentation later on...

let sql3 = " 
select data.name, data.email,
(select data.color as col, data.hobby as hobby from colors where data.email = $parent.data.email)[0] as co,
(select data.zip as zip, data.address as adress from addresses where data.name = $parent.data.name)[0] as adds
from users;
";

  let result: Vec<Value> = db.query(sql3).await?.take(0)?;
  let json_value: serde_json::Value = json!(result);

  let flattened: Vec<Map<String, Value>> = json_value
    .as_array()
    .unwrap_or(&vec![])
    .iter()
    .filter_map(|item| item.as_object().map(flatten_object))
    .collect();

  let flattened_json = json!(flattened);
  println!("Flattened JSON: {:#?}", flattened_json);
  
  fn flatten_object(obj: &Map<String, Value>) -> Map<String, Value> {
  let mut flattened = Map::new();

  for (key, value) in obj {
    if let Value::Object(nested) = value {
      for (nested_key, nested_value) in nested {
        flattened.insert(nested_key.clone(), nested_value.clone());
      }
    } else {
      flattened.insert(key.clone(), value.clone());
    }
  }

  flattened
}

that in turn would give me this

Flattened JSON: Array [
    Object {
        "adress": String("12 Oakridge Rd"),
        "zip": String("89012"),
        "col": String("Brown"),
        "hobby": String("Gardening"),
        "email": String("[email protected]"),
        "name": String("Jane Brown"),
    },
    Object {
        "adress": String("31 Willow Way"),
        "zip": String("78901"),
        "col": String("Pink"),
        "hobby": String("Reading"),
        "email": String("[email protected]"),
        "name": String("John Davis"),
    },
]

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