Documentation: Clarify expected arguments for queries.

[alyti]

Description

Right now there's a large number of query types that accept queries only accept idents/literals, I've seen many users run into confusing parser errors/invalid queries due to this as it's not clearly noted anywhere.

Ideally these queries should at least support $variables, this way users don't have to open themselves to sql injections (by formatting their queries manually).
In the interim it should at least be documented for beta.9 and maybe beta.10 (as it's still an issue on nightly).

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

[Ekwuno]

Hi @alyti thanks for pointing this out. Are you referring to SDKs or SurrealQL? Also if you have any links or examples that would be helpful as well.

[alyti]

I am referring to SurrealQL, notably almost all if not all queries in DEFINE and REMOVE don't work with anything but simple literals.

[alyti]

Also RELATE to and from record could use some clarification on the accepted syntax, since I've also seen people try to use dot notation with variables inside (RELATE $after.id->...->...) and get confused too.

[kearfy]

I believe this issue came from a discussion in discord. There are generally some syntax "tricks" for which you need a deeper understanding of SurrealQL to know they even exist. In this case, Aly and theUno in Discord tried to create a relation from nested variables:

RELATE $nested.prop->...->...

The solution in this specific scenario is to wrap the variable around () brackets:

RELATE ($nested.prop)->...->...

As you can see here, it's not specific to relate statements, and not even this one specific "feature" (?) if I interpet this ticket correctly. I'm wondering when we'll be able to close it 😛

Link to discord message for reference, read a bit back for full context: https://discord.com/channels/902568124350599239/1018618253695795261/1134091589099196446

[alyti]

As you can see here, it's not specific to relate statements, and not even this one specific "feature" (?) if I interpet this ticket correctly. I'm wondering when we'll be able to close it 😛

Yeah relate doc is just a side-quest, main issue is REMOVE/DEFINE queries only accepting literals, no tricks there this time 😛