Update docs to cover modifying functions.

docs/datamodel/computeds.rst

@@ -53,9 +53,10 @@ field is referenced in a query.
 
 .. warning::
 
-  Volatile functions are not allowed in computed properties defined in schema.
-  This means that, for example, your schema-defined computed property cannot
-  call :eql:func:`datetime_current`, but it *can* call
+  :ref:`Volatile and modifying <_ref_reference_volatility>` expressions are not
+  allowed in computed properties defined in schema. This means that, for
+  example, your schema-defined computed property cannot call
+  :eql:func:`datetime_current`, but it *can* call
   :eql:func:`datetime_of_transaction` or :eql:func:`datetime_of_statement`.
   This does *not* apply to computed properties outside of schema.
 

docs/datamodel/functions.rst

@@ -32,6 +32,121 @@ This function accepts a :eql:type:`str` as an argument and produces a
   test> select exclamation({'Hello', 'World'});
   {'Hello!', 'World!'}
 
+.. _ref_datamodel_functions_modifying:
+
+Sets as arguments
+^^^^^^^^^^^^^^^^^
+
+Calling a user-defined function on a set will always apply it as
+:ref:`*element-wise* <_ref_reference_cardinality_functions_operators>`.
+
+.. code-block:: sdl
+
+  function magnitude(x: float64) -> float64
+    using (
+      math::sqrt(sum(x * x))
+    );
+
+.. code-block:: edgeql-repl
+
+    db> select magnitude({3, 4});
+    {3, 4}
+
+In order to pass in multiple arguments at once, arguments should be packed into
+arrays:
+
+.. code-block:: sdl
+
+  function magnitude(xs: array<float64>) -> float64
+    using (
+      with x := array_unpack(xs)
+      select math::sqrt(sum(x * x))
+    );
+
+.. code-block:: edgeql-repl
+
+    db> select magnitude([3, 4]);
+    {5}
+
+Multiple packed arrays can be passed into such a function, which will then be
+applied element-wise.
+
+.. code-block:: edgeql-repl
+
+    db> select magnitude({[3, 4], [5, 12]});
+    {5, 13}
+
+Modifying Functions
+^^^^^^^^^^^^^^^^^^^
+
+.. versionadded:: 6.0
+
+User-defined functions can contain DML (i.e.,
+:ref:`insert <ref_eql_insert>`, :ref:`update <ref_eql_update>`,
+:ref:`delete <ref_eql_delete>`) to make changes to existing data. These
+functions have a :ref:`modifying <_ref_reference_volatility>` volatility.
+
+.. code-block:: sdl
+
+  function add_user(name: str) -> User
+    using (
+      insert User {
+        name := name,
+        joined_at := std::datetime_current(),
+      }
+    );
+
+.. code-block:: edgeql-repl
+
+    db> select add_user('Jan') {name, joined_at};
+    {default::User {name: 'Jan', joined_at: <datetime>'2024-12-11T11:49:47Z'}}
+
+Unlike other functions, the arguments of modifying functions **must** have a
+:ref:`cardinality <_ref_reference_cardinality>` of ``One``.
+
+.. code-block:: edgeql-repl
+
+    db> select add_user({'Feb','Mar'});
+    edgedb error: QueryError: possibly more than one element passed into
+    modifying function
+    db> select add_user(<str>{});
+    edgedb error: QueryError: possibly an empty set passed as non-optional
+    argument into modifying function
+
+Optional arguments can still accept empty sets. For example, if ``add_user``
+was defined as:
+
+.. code-block:: sdl
+
+  function add_user(name: str, joined_at: optional datetime) -> User
+    using (
+      insert User {
+        name := name,
+        joined_at := joined_at ?? std::datetime_current(),
+      }
+    );
+
+then the following queries are valid:
+
+.. code-block:: edgeql-repl
+
+    db> select add_user('Apr', <datetime>{}) {name, joined_at};
+    {default::User {name: 'Apr', joined_at: <datetime>'2024-12-11T11:50:51Z'}}
+    db> select add_user('May', <datetime>'2024-12-11T12:00:00-07:00') {name, joined_at};
+    {default::User {name: 'May', joined_at: <datetime>'2024-12-11T12:00:00Z'}}
+
+In order to insert or update a multi parameter, the desired arguments should be
+aggregated into an array as described above:
+
+.. code-block:: sdl
+
+  function add_user(name: str, nicknames: array<str>) -> User
+    using (
+      insert User {
+        name := name,
+        nicknames := array_unpack(nicknames),
+      }
+    );
 
 .. list-table::
   :class: seealso

docs/reference/edgeql/cardinality.rst

@@ -22,6 +22,8 @@ instance, when assigning to a ``required multi`` link, the value being
 assigned in question *must* have a cardinality of ``One`` or ``AtLeastOne``
 (as empty sets are not permitted).
 
+.. _ref_reference_cardinality_functions_operators:
+
 Functions and operators
 -----------------------
 

docs/reference/edgeql/volatility.rst

@@ -132,3 +132,8 @@ The :ref:`cartesian product <ref_reference_cardinality_cartesian>` of a
 
 ``Modifying`` expressions are not allowed in a non-scalar argument to a
 function, except for :ref:`standard set functions <ref_std_set>`.
+
+The non-optional parameters of ``Modifying``
+:ref:`functions <_ref_datamodel_functions_modifying>` must have a
+:ref:`cardinality <_ref_reference_cardinality>` of ``One``. Optional
+parameters must have a cardinality of ``AtMostOne``.

docs/reference/sdl/functions.rst

@@ -101,6 +101,8 @@ This declaration defines a new constraint with the following options:
     argument as a *whole set*, as opposed to being called on the input
     product element-by-element.
 
+    User defined functions can not use ``set of`` arguments.
+
     The ``optional`` qualifier indicates that the function will be called
     if the argument is an empty set.  The default behavior is to return
     an empty set if the argument is not marked as ``optional``.