The implementation of a user-defined N1QL function.
The arguments are passed as zero-arg functions that return a JSON value or undefined.
(This allows you to conditionally evaluate arguments, which can help performance.)
Your function will return a JSON value or undefined (aka MISSING.)
Argument values are deeply read-only. You MUST NOT modify arrays or objects. If you need to
return a modified version, make a copy and modify that.
By convention, most N1QL functions will return MISSING (undefined) if any argument is
MISSING, and otherwise NULL (null) if any argument is NULL.
You're not required to do this, but it's usually a good idea; it makes it easier for queries
to handle missing or invalid data.
Most N1QL functions are deterministic or "pure", that is, given the same arguments they will
return the same value. If your function is not, you must set the nondeterminstic option,
else query optimizations might cache stale values and cause incorrect behavior.
(Examples of non-deterministic functions are RANDOM() and CURRENT_DATE().)
Your function MUST NOT access external mutable state, nor keep any mutable state between
calls -- in particular, don't try to implement an aggregate function, it won't work!
(We may add support for custom aggregate functions in the future.)
Avoid throwing exceptions under "normal" circumstances like an illegal argument value.
Instead return null.
Any exception thrown will be caught and logged, and treated as a return value of null.
The implementation of a user-defined N1QL function.
The arguments are passed as zero-arg functions that return a JSON value or
undefined. (This allows you to conditionally evaluate arguments, which can help performance.)Your function will return a JSON value or
undefined(akaMISSING.)Argument values are deeply read-only. You MUST NOT modify arrays or objects. If you need to return a modified version, make a copy and modify that.
By convention, most N1QL functions will return
MISSING(undefined) if any argument isMISSING, and otherwiseNULL(null) if any argument isNULL. You're not required to do this, but it's usually a good idea; it makes it easier for queries to handle missing or invalid data.Most N1QL functions are deterministic or "pure", that is, given the same arguments they will return the same value. If your function is not, you must set the
nondeterminsticoption, else query optimizations might cache stale values and cause incorrect behavior. (Examples of non-deterministic functions areRANDOM()andCURRENT_DATE().)Your function MUST NOT access external mutable state, nor keep any mutable state between calls -- in particular, don't try to implement an aggregate function, it won't work! (We may add support for custom aggregate functions in the future.)
Avoid throwing exceptions under "normal" circumstances like an illegal argument value. Instead return
null. Any exception thrown will be caught and logged, and treated as a return value ofnull.