<commit_before>Extending AQL with User Functions {#ExtendingAql}
=================================================

@NAVIGATE_ExtendingAql
@EMBEDTOC{ExtendingAqlTOC}

Conventions {#ExtendingAqlConventions}
======================================

AQL comes with a built-in set of functions, but it is no
full-feature programming language.

To add missing functionality or to simplifiy queries, users
may add own functions to AQL. These functions can be written
in Javascript, and must be registered via an API. 

In order to avoid conflicts with existing or future built-in 
function names, all user functions must be put into separate
namespaces. Invoking a user functions is then possible by referring
to the fully-qualified function name, which includes the namespace,
too. 

The `:` symbol is used inside AQL as the namespace separator. Using 
the namespace separator, users can create a multi-level hierarchy of 
function groups if required.

Examples:

    RETURN myfunctions::myfunc()

    RETURN myfunctions::math::random()

Note: as all function names in AQL, user function names are also
case-insensitive.

Built-in AQL functions reside in the namespace `_aql`, which is also
the default namespace to look in if an unqualified function name is
found. Adding user functions to the `_aql` namespace is disallowed and 
will fail.

User functions can take any number of input arguments and should 
provide one result. They should be kept purely functional and thus free of
side effects and state. 

Especially it is unsupported to modify any global variables, or to change 
data of a collection from an AQL user function. 

User function code is late-bound, and may thus not rely on any variables
that existed at the time of declaration. If user function code requires
access to any external data, it must take care to set up the data by
itself.

User functions must only return primitive types (i.e. `null`, boolean
values, numeric values, string values) or aggregate types (lists or
documents) composed of these types.
Returning any other Javascript object type from a user function may lead 
to undefined behavior and should be avoided.


Registering and Unregistering User Functions {#ExtendingAqlHowTo}
=================================================================

AQL user functions can be registered using the `aqlfunctions` object as
follows:

    var aqlfunctions = require("org/arangodb/aql/functions");

To register a function, the fully qualified function name plus the
function code must be specified.

@copydetails JSF_aqlfunctions_register
<commit_msg>added note about backing up aql user functions<commit_after>Extending AQL with User Functions {#ExtendingAql}
=================================================

@NAVIGATE_ExtendingAql
@EMBEDTOC{ExtendingAqlTOC}

Conventions {#ExtendingAqlConventions}
======================================

AQL comes with a built-in set of functions, but it is no
full-feature programming language.

To add missing functionality or to simplifiy queries, users
may add own functions to AQL. These functions can be written
in Javascript, and must be registered via an API. 

In order to avoid conflicts with existing or future built-in 
function names, all user functions must be put into separate
namespaces. Invoking a user functions is then possible by referring
to the fully-qualified function name, which includes the namespace,
too. 

The `::` symbol is used inside AQL as the namespace separator. Using 
the namespace separator, users can create a multi-level hierarchy of 
function groups if required.

Examples:

    RETURN myfunctions::myfunc()

    RETURN myfunctions::math::random()

Note: as all function names in AQL, user function names are also
case-insensitive.

Built-in AQL functions reside in the namespace `_aql`, which is also
the default namespace to look in if an unqualified function name is
found. Adding user functions to the `_aql` namespace is disallowed and 
will fail.

User functions can take any number of input arguments and should 
provide one result. They should be kept purely functional and thus free of
side effects and state. 

Especially it is unsupported to modify any global variables, or to change 
data of a collection from an AQL user function. 

User function code is late-bound, and may thus not rely on any variables
that existed at the time of declaration. If user function code requires
access to any external data, it must take care to set up the data by
itself.

User functions must only return primitive types (i.e. `null`, boolean
values, numeric values, string values) or aggregate types (lists or
documents) composed of these types.
Returning any other Javascript object type from a user function may lead 
to undefined behavior and should be avoided.

Internally, user functions are stored in a system collection named
`_aqlfunctions`. That means that by default they are excluded from dumps
created with arangodump. To include AQL user functions in a dump, the
dump should be started with the option `--include-system-collections true`.

Registering and Unregistering User Functions {#ExtendingAqlHowTo}
=================================================================

AQL user functions can be registered using the `aqlfunctions` object as
follows:

    var aqlfunctions = require("org/arangodb/aql/functions");

To register a function, the fully qualified function name plus the
function code must be specified.

@copydetails JSF_aqlfunctions_register

{'fraction_non_alphanumeric': 0.09389842893679211, 'fraction_numerical': 0.0, 'mean_word_length': 5.023102310231023, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6706090', 'n_tokens_mistral': 1376, 'n_tokens_neox': 1300, 'n_words': 741}