User-defined functions

The Fauna Query Language provides many built-in functions that can be used to query and modify a database. Functions, also known as user-defined functions (or UDFs), provide a mechanism to store and run commonly used Fauna queries.

This section describes functions, their anatomy, how to create them, and how execute them.

To learn more about common user-defined function operations, see Function recipes.

Overview

Fauna supports two different types of functions:

  1. Built-in functions: these are used as the building blocks to query or mutate Fauna databases.

  2. User-defined functions (UDFs): these are used to combine functions, built-in or user-defined, into queries that can be executed repeatedly.

UDFs can be anonymous, when declared with the Lambda function, or can be named by using the CreateFunction function.

For example, a simple query that uses a built-in function could be:

Add(1, 1)

That query always returns the same result (2).

Suppose that we want to add 1 to several numbers. We could use an anonymous function:

Map(
  [ 1, 2, 3, 4, 5 ],
  Lambda(
    "number",
    Add(1, Var("number"))
  )
)

The result should be:

[ 2, 3, 4, 5, 6 ]

That query executes the anonymous Lambda function once per entry in the array that Map processes.

For more complex functions, where it might be unwieldy to include the function itself in each query that needs to use it, we can create a named function:

CreateFunction({
  name: "increment",
  body: Query(Lambda("number", Add(1, Var("number"))))
})

Now that the function has been stored and has a name, we can run a query that executes our function like this:

Call(Function("increment"), 50)

When we do so, the result should be:

51
CreateFunction must be called with "server" or "admin" privileges.

Schema for named functions

UDFs are documents that exist within internal "functions" collection of Fauna, which can be referred to by name using the built-in Function function. Each function document is stored within the context of the enclosing database: peer, parent, and child databases store functions independently.

When a function is deleted, its definition and associated data becomes inaccessible and is deleted asynchronously.

Field Type Definition and Requirements

name

String

The name of the function.

Cannot be events, sets, self, documents, or _. Cannot have the % character.

body

Query

The query to be run when the function is executed. Must be wrapped in a Query function. See the Lambda function for more details.

role

String

Optional- When the function is executed, it should be granted the privileges of the specified role. Can be one of admin, server, server-readonly, or client. See Permissions for more details.

data

Object

Optional - A JSON object that can be used to store metadata about a function.

Signature

The signature of a UDF takes two parameters: an parameter list and a query expression to be executed.

The parameter list specifies the name(s) of the parameters passed to the function upon execution. The parameter list could be a single String name, or an array of string names.

The query expression is any valid FQL query.

To use named parameters within the query expression, use the Var function.

Examples

Consider the following anonymous function (which would result in an error if you attempt to execute it as is; there is no calling context):

Lambda("X", Var("X"))

This function’s parameter list is simply X, which specifies that this function accepts only one parameter and that the parameter’s name is X.

The function’s expression is Var("X"), which means that the function’s output, or return value, is simply the value of the X variable: this function returns the value that was provided to it.

A multi-parameter function might look like this:

Lambda(
  ["X", "Y", "Z"],
  Format("%s %s %s", Var("X"), Var("Y"), Var("Z"))
)

This function accepts an array of parameters, called X, Y, and Z, and then formats the parameter values into a string showing all three values.

Functions must be executed with the same number of parameters that they are defined to accept.

Permissions

By default, UDFs are executed with the privileges of the current query session. For example, if your client code connects to Fauna using a "client" key, any called UDFs would, by default, execute with "client" privileges. See Keys for more details.

You can specify a role for named UDFs, which grants the functions of the named role while the UDF executes. This feature is similar to the Unix setuid facility. For example, a function whose role field is set to admin can perform the same query that an "admin" key makes possible, even for sessions authenticated with "client" keys.

Limitations

  • Fauna imposes a 30-second transaction timeout, terminating any transactions that exceed the limit. Transaction termination can happen with UDFs that take too long to execute.

  • Fauna terminates transactions when the execution of a UDF exceeds available memory.

  • Recursion is possible but is limited to a depth of 200 calls.

  • In some contexts, such as within index bindings, using "server read-only" keys, or attribute-based access control, Fauna may restrict UDFs from performing write or read operations.

Is this article helpful? 

Tell Fauna how the article can be improved:
 Visit Fauna's forums or email docs@fauna.com

Thank you for your feedback!