From 26ac1ce07113731b9b9d601fa51a2fecabbf5558 Mon Sep 17 00:00:00 2001 From: Wilfried Goesgens Date: Thu, 4 Aug 2016 13:53:49 +0200 Subject: [PATCH] By simran: review UDF documentation. --- .../Books/AQL/Extending/Conventions.mdpp | 42 +++++++------------ .../Books/AQL/Extending/Functions.mdpp | 6 +++ Documentation/Books/AQL/Extending/README.mdpp | 25 +++++++++++ Documentation/Books/AQL/Functions/README.mdpp | 35 +--------------- 4 files changed, 46 insertions(+), 62 deletions(-) diff --git a/Documentation/Books/AQL/Extending/Conventions.mdpp b/Documentation/Books/AQL/Extending/Conventions.mdpp index 7c439c3a2a..7ac558fe20 100644 --- a/Documentation/Books/AQL/Extending/Conventions.mdpp +++ b/Documentation/Books/AQL/Extending/Conventions.mdpp @@ -2,24 +2,24 @@ !SECTION Naming -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. +Built-in AQL functions that are shipped with ArangoDB reside in the namespace +*_aql*, which is also the default namespace to look in if an unqualified +function name is found. -Examples: +To refer to a user-defined AQL function, the function name must be fully +qualified to also include the user-defined namespace. The *::* symbol is used +as the namespace separator. Users can create a multi-level hierarchy of function +groups if required: ```js -RETURN myfunctions::myfunc() -RETURN myfunctions::math::random() +MYGROUP::MYFUNC() +MYFUNCTIONS::MATH::RANDOM() ``` -**Note**: As all function names in AQL, user function names are also -case-insensitive. +**Note**: Adding user functions to the *_aql* namespace is disallowed and will +fail. -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 function names are case-insensitive like all function names in AQL. !SECTION Variables and side effects @@ -87,8 +87,8 @@ and state outside of the user function itself. User functions must only return primitive types (i.e. *null*, boolean values, numeric values, string values) or aggregate types (arrays or objects) composed of these types. -Returning any other JavaScript object type from a user function may lead -to undefined behavior and should be avoided. +Returning any other JavaScript object type (Function, Date, RegExp etc.) from +a user function may lead to undefined behavior and should be avoided. !SECTION Enforcing strict mode @@ -111,17 +111,3 @@ function (values) { ``` Any violation of the strict mode will trigger a runtime error. - -!SECTION Miscellaneous - -Internally, user functions are stored in a system collection named -*_aqlfunctions* of the selected database. The functions will be exclusively -available for queries in that particular database. - -Documents in the *_aqlfunctions* collection (or any other system collection) -should not be accessed directly, but only via the dedicated interfaces. - -Keep in mind that system collections are excluded from dumps created with -[arangodump](../../Manual/Administration/Arangodump.html) by default. To include AQL user -functions in a dump, the dump needs to be started with the -option *--include-system-collections true*. diff --git a/Documentation/Books/AQL/Extending/Functions.mdpp b/Documentation/Books/AQL/Extending/Functions.mdpp index 687d746e3f..be8c689698 100644 --- a/Documentation/Books/AQL/Extending/Functions.mdpp +++ b/Documentation/Books/AQL/Extending/Functions.mdpp @@ -12,6 +12,12 @@ function code must be specified. This can easily be done in [arangosh](../../Manual/GettingStarted/Arangosh.html). The [HTTP Interface ](../../HTTP/AqlUserFunctions/index.html) also offers User Functions management. +Documents in the *_aqlfunctions* collection (or any other system collection) +should not be accessed directly, but only via the dedicated interfaces. +Otherwise you might see caching issues or accidentally break something. +The interfaces will ensure the correct format of the documents and invalidate +the UDF cache. + !SUBSECTION Registering an AQL user function For testing, it may be sufficient to directly type the function code in the shell. diff --git a/Documentation/Books/AQL/Extending/README.mdpp b/Documentation/Books/AQL/Extending/README.mdpp index 9166d2dfec..dc2fb7beae 100644 --- a/Documentation/Books/AQL/Extending/README.mdpp +++ b/Documentation/Books/AQL/Extending/README.mdpp @@ -13,3 +13,28 @@ 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; see [Conventions](Conventions.md). + +!SECTION Technical Details + +Internally, user-defined functions (UDF) are stored in a system collection named +*_aqlfunctions* of the selected database. When an AQL statement refers to such a function, it is loaded from that collection. The functions will be exclusively +available for queries in that particular database. + +When used in clusters, the UDF is executed on the coordinator. Depending on your +query layout, this may result in many documents having to be passed up from the +DB-Servers to the Coordinator. To avoid this, you should make sure that the query +contains effective `FILTER` statements that can be used on the DB-Server side to +reduce the query result before passing it up to the Coordinator and your UDF. + +Since the Coordinator doesn't have own local collections, the `_aqlfunctions` +collection is sharded across the cluster. Therefore (as usual), it has to be +accessed through the coordinator - you mustn't talk to the DB-Servers directly. +Once it is in there, it will be available on all coordinators. + +Since the optimizer doesn't know anything about this function, it won't be able +to use indices for these functions. + +Keep in mind that system collections are excluded from dumps created with +[arangodump](../../Manual/Administration/Arangodump.html) by default. +To include AQL user functions in a dump, the dump needs to be started with +the option *--include-system-collections true*. diff --git a/Documentation/Books/AQL/Functions/README.mdpp b/Documentation/Books/AQL/Functions/README.mdpp index a0be51d6d2..b386295ca2 100644 --- a/Documentation/Books/AQL/Functions/README.mdpp +++ b/Documentation/Books/AQL/Functions/README.mdpp @@ -29,37 +29,4 @@ i.e. *LENGTH(foo)* and *length(foo)* are equivalent. It is possible to extend AQL with user-defined functions. These functions need to be written in JavaScript, and be registered before usage in a query. Please refer -to [Extending AQL](../Extending/index.html) for more details on this. - -By default, any function used in an AQL query will be sought in the built-in -function namespace *_aql*. This is the default namespace that contains all AQL -functions that are shipped with ArangoDB. -To refer to a user-defined AQL function, the function name must be fully qualified -to also include the user-defined namespace. The *::* symbol is used as the namespace -separator: - -```js -MYGROUP::MYFUNC() -MYFUNCTIONS::MATH::RANDOM() -``` - -As all AQL function names, user function names are also case-insensitive. - -!SUBSUBSECTION Technical Details -ArangoDB stores user defined functions in the `_functions` system collection. -When an AQL statement refers to such a function, its loaded from that collection. - -Since the optimizer doesn't know anything about this function, it won't be able -to use indices for these functions. - -When used in clusters, the UDF is executed on the coordinator. Depending on your -query layout, this may result in many documents having to be passed up from the -DB-Servers to the Coordinator. To avoid this, you should make sure that the query -contains effective `FILTER` statements that can be used to DB-Server to reduce -the query result before passing it up to the Coordinator and your UDF. - -Since the Coordinator doesn't have own local collections, the `_functions` collection -is sharded across the cluster. Therefore (as usual) it has to be accessed through the coordinator - -you mustn't talk to the DB-Servers directly. Once its in there, it will be available -on all coordinators. - +to [Extending AQL](../Extending/index.html) for more details.