Hawkin
/
arangodb
mirror of https://gitee.com/bigwinds/arangodb
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

By simran: review UDF documentation.

This commit is contained in:
Wilfried Goesgens 2016-08-04 13:53:49 +02:00
parent ecf537af5a
commit 26ac1ce071
4 changed files with 46 additions and 62 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

42
Documentation/Books/AQL/Extending/Conventions.mdpp
View File

@ -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*.

6
Documentation/Books/AQL/Extending/Functions.mdpp
View File

@ -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.

25
Documentation/Books/AQL/Extending/README.mdpp
View File

@ -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*.

35
Documentation/Books/AQL/Functions/README.mdpp
View File

@ -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.