docs: Update the docs for computables.
Add more details on computables as well as `__source__`.
Closes
@@ -13,6 +13,12 @@ are referenced in a query. The type of the property or link is determined
from the expression. Other than that computables behave exactly like their
non-computable counterparts.
+Links and properties have a *source* and one or more *targets*. The
+*source* is always the object on which the link is defined. *Targets*
+are either the objects to which the link points or the property
+values. The computable expressions define one or more *targets* and
+can refer to the *source* as ``__source__``.
+
Computables are useful in the situations where there is a frequent need for
some value that is derived from the values of existing properties and links.
@@ -31,3 +37,25 @@ last name:
}
Computables are also often used in :ref:`views <ref_datamodel_views>`.
+For example, using the ``User`` from the above example, a ``UserView``
+can be defined with a ``lastname_first`` computable which lists the
+full name in the format which is often used in formal alphabetized
+lists:
+
+.. code-block:: sdl
+
+ view UserView := User {
+ lastname_first := (
+ __source__.lastname ++ ', ' ++
+ __source__.firstname)
+ }
+
+Computables can be used in :ref:`shapes <ref_eql_expr_shapes>`, too:
+
+.. code-block:: edgeql
+
+ SELECT User {
+ lastname_first := (
+ __source__.lastname ++ ', ' ++
+ __source__.firstname)
+ };
