Documentation: Clarification on InsertRelation/Relate/Insert

[lawrencejob]

Description

Hi, please forgive my etiquette if I make a mistake here; I am new to OSS. I've spent the week trying to familiarise myself with the new SDK. I really appreciate the work that has gone into this.

I was wondering if there is an official answer as to how to create relationships using this SDK? There are currently two self-evident ways of doing it (Relate and InsertRelation), and I just saw the new documentation on the SurrealDB website, which suggests using Insert (particularly for my usecase where I need to insert many relations). After poring over the documentation and reading the source code, it looks like they all differ in how they encode the operation for transport, but all have the same result by the time it's applied to the database. Before I saw the new docs on the SurrealDB website I was about to fork the repo and start work on a ...args version of InsertRelation.

My request (and I'm happy to contribute) is that there is be opinionated guidance as to when to use each of the three approaches and the pitfalls. For example, Relate silently ignores a provided ID and InsertRelation crashes if it already exists (which is of course reasonable). I haven't tried Insert yet.

In an ideal world, the SDK would function as an affordance for how to best use the database, but perhaps if the database is so general there might not be a single best approach?

Thanks again, and I'd be keen to contribute with a PR if I better understood the design ethos.

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

[lawrencejob]

Further updates:

1. for my needs I'm going to use .Query. I've been reading the RPC protocol and I understand that there is no way to do multiple inserts of relations without using a custom query. I don't think I'd design it this way, but the protocol design is outside of the scope of the SDK.

2. what I said earlier about the documentation on SurrealDB for InsertRelation I think turned out to be a mistake in the documentation, it's not a viable option. When I run the example it says rpc request err There was a problem with the database: Found record: calls_at:⟨CHRX-dhWTaEvW⟩ which is a relation, but expected a RELATION IN record<services> OUT record<locations>.