Documentation: explain syntax of SurrealQL @placeholders

[stijndcl]

Description

I appreciate the detailed syntax/grammar breakdowns in the SurrealQL section of the docs, but noticed that many fragments are full of @<thing> which are not explained anywhere (at least not that I could find quickly - please point me to the docs if they are). I think it wouldn't hurt to have a section that elaborates on all of these so a user can easily see what they can insert in these spots.

For some of them you can piece them together by combining all the code fragments from the examples and the book, but IMO this is not ideal, and also doesn't guarantee that every available option is covered.

Example from the SELECT statement:

SELECT 
    VALUE @field | @fields [ AS @alias ] [ OMIT @fields ... ]
    FROM [ ONLY ] @targets
    [ WITH [ NOINDEX | INDEX @indexes ... ]]
    [ WHERE @conditions ]
    [ SPLIT [ ON ] @field, ... ]
    [ GROUP [ ALL | [ BY ] @field, ... ]]
    [ ORDER [ BY ] 
        @field [ COLLATE ] [ NUMERIC ] [ ASC | DESC ], ...
        | RAND() ]
    [ LIMIT [ BY ] @limit ]
    [ START [ AT ] @start 0 ]
    [ FETCH @fields ... ]
    [ TIMEOUT @duration ]
    [ TEMPFILES ]
    [ EXPLAIN [ FULL ]]
;

What are @field, @fields, @alias, @targets, @indexes, @conditions, @limit, @start and @duration? Dozens of these appear all throughout the docs but are never defined or explained. In a lot of cases you can slot in an arbitrary identifier here, but in many cases you can get far more complex, and IMO showing the syntax and/or railroad diagram would help clarify these.

Especially things like @value or @values (eg. for the INSERT statement) come to mind for me, as expressions can get sophisticated. What kind of expressions are there? Same goes for everything you can pass into the @field of a SELECT, etc.

Thanks!

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