Documentation: 8 things I struggled with while learning surrealQL

[lveillard]

Description

THings that are missing, aha moments or concepts without proper examples:

1. • FROM can be from multiple tables FROM a,b,c
2. • Aha moment: There is no array::map function but we can do SELECT VALUE {function} (array)
3. • The difference between default and value when defining a field
4. • <future> can be used as well in FIELD VALUE to generate onRead computed values. In the doc appears to work only on CREATE queries
5. • FROM can be used with edges relative to the $parent, like this: SELECT *, (SELECT * FROM ->installed->property) FROM tableName
6. • How to filter by id in a FROM when it has the edge structure as the point 5) here 👆 . This for instance does not work SELECT *, (SELECT * FROM (->installed->property):recordId) FROM tableName while this does SELECT *, (SELECT * FROM tableName2:recordId) FROM tableName
7. • While virtual fields can be done with FIELD VALUE , I cant find any place to do virtual edges (infered edges computed onRead)

8. Polymorphism:

I think it deserves a full page, is polymorphism. For instance edges can point to multiple tables:

DEFINE TABLE SpaceObj_space TYPE RELATION IN SpaceObj|SpaceDef|Kind|Self OUT Space SCHEMAFULL PERMISSIONS FULL;

Also we can fetch polymorphic edges with this structure:

  SELECT
      meta::id(id) as `$id`,
      (
        SELECT
          meta::id(id) as `$id`,
        FROM <-`SpaceObj_space`<-(`SpaceObj`,`Kind`,`Self`)   --This is the interesting part
      ) AS `objects`,
      meta::id(id) AS id
    FROM Space:`space-2`

And a last thing around polymorphism not explained that Im not even sure is doable. This works

FROM <-`SpaceObj_space`<-(`SpaceObj`,`Kind`,`Self`)

But afaik there is no equivalent shortcut for tables:

`FROM (User, SuperUser):user7 --throws error

and requires doing the combinations:

`FROM User:user7, SuperUser:user7

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]

Thanks @lveillard! I noticed something similar to FROM when I first encountered CREATE and saw that you can create multiple tables and added that to the documentation. I guess FROM will need an example as well.

Also, I'm writing something interesting at the moment and I think I can fit some of your points in there.

[Xkonti]

@lveillard Your list is very helpful! Could you elaborate on the point 4?

can be used as well in FIELD VALUE to generate onRead computed values. In the doc appears to work only on CREATE queries

I'm not sure what the read-only field definition would look like. Could you show an example?

[lveillard]

Sorry the word "Futures" was missing in point 4. Imagine for instance a field full name defined as a future that gets the values of other two fields.

And thanks @Dhghomon, I'm happy my time sharing my struggles was useful.

Today my main blocking point is just not being able to use $input on events, I was able to find workarounds for the rest.

Im still unsure about point 3 tho.

My two other key feature request would be to:

1. future edges (inferred RELATE and refs)
2. nested ops. We can nest operations inside CREATE and Update, which includes link and unlink for references. An example:

CREATE company:1 set employees =+ (CREATE employee:1 set name = Ann)

We can also update other things of the parent by using $parent inside and any of its properties.

However this is not possible for Deletions. In deletions we need to use $before inside the return clause instead in order to nest things in a graphql manner. It has a workaround so I did not open an issue but I would like it to be consistente and have a Set in deletions, this would for instance enable cascade deletions like

DELETE company:1 set employees = { DELETE employees return none}

[Dhghomon]

Hi! A few months later I think points 2, 3 and 4 are probably addressed now. How are you finding the other issues? Could be good to close this and make a new issue for each remaining point with a link to here, and then they can be addressed and closed one at a time.

[lveillard]

Hello @Dhghomon! I get 2) but how are 3 and 4 fixed? Are they better detailed in the docs?
Also around <future> another thing that is not well documented is that

• They don't work as WHERE clauses (and worse that not working, it does not throw any error)
• They are not retroactive. Futures are not computed logics run onRead, but computed logics stored in records (afaik). So basucally if you change the formula, records are not automatically configured with the new future definition. Docs could show that UPDATE {tableName} is a workaround while there are not real onRead computed values

For the other issues yes i can open specific threads