Check out v4 of the Fauna CLI

v4 of the Fauna CLI is now GA.

The new version introduces enhancements to the developer experience, including an improved authentication workflow. To get started, check out the CLI v4 quick start.

Migrating from v3 of the CLI? See the CLI migration guide.

Function

Learn: User-defined functions (UDFs)

We recommend you use FSL to create and update user-defined functions (UDFs). See FSL function schema.

A user-defined function (UDF) is a set of one or more FQL statements stored as a reusable resource in a Fauna database. Like a stored procedure in SQL, a UDF can accept parameters, perform operations, and return results.

Function collection

Fauna stores UDFs as documents in the Function system collection. These documents have the FunctionDef type and are an FQL version of the FSL function schema.

Function documents have the following FQL structure:

{
  name: "getOrCreateCart",
  coll: Function,
  ts: Time("2099-09-25T21:53:08.780Z"),
  role: "server",
  body: <<-END
    (id) => {
      let customer = Customer.byId(id)!
      if (customer!.cart == null) {
        Order.create({
          status: "cart",
          customer: Customer.byId(id),
          createdAt: Time.now(),
          payment: {
          }
        })
      } else {
        customer!.cart
      }
    }
  END
}
Field Type Read-only Required Description

name

String

true

Name of the function.

Can’t be documents, events, self, sets, or a single underscore _, and can’t include a space character.

coll

String

true

Collection name: Function.

ts

Time

true

Last time the document was created or updated.

role

String

Associates a runtime role with the UDF. An FQL version of the @role annotation.

By default, UDFs run with the privileges of the calling query’s authentication secret. If a role is provided, the UDF runs using the annotated role’s privileges, regardless of the secret used to call it.

The Role can be a user-defined role or one of the following built-in roles:

  • admin

  • server

  • server-readonly

The role field is typically used to give a role controlled access to sensitive data without granting broader privileges. See Runtime privileges.

Use role carefully. Use the role with the fewest privileges needed perform the UDF’s operations.

body

String

true

FQL function body.

data

Object

Arbitrary user-defined metadata for the document.

Static methods

You can use the following static methods to manage the Function collection in FQL.

Method Description

Function()

Call a user-defined function (UDF) by its name.

Function.all()

Get a Set of all user-defined functions (UDFs).

Function.byName()

Get a user-defined function (UDF) by its name.

Function.create()

Create a user-defined function (UDF).

Function.firstWhere()

Get the first user-defined function (UDF) that matches a provided predicate.

Function.toString()

Get "Function" as a String.

Function.where()

Get a Set of user-defined functions (UDFs) that match a provided predicate.

Instance properties

Function documents have the following properties. You access the property using an existing UDF’s name.

Property Description

function.definition

Get or update a user-defined function (UDF)'s definition, represented as a Function document.

Instance methods

You can use the following instance methods to manage function definitions, represented as Function documents, in FQL. You call the methods on a FunctionDef.

Method Description

functionDef.delete()

Delete a user-defined function (UDF).

functionDef.exists()

Test if a user-defined function (UDF) exists.

functionDef.replace()

Replace a user-defined function (UDF).

functionDef.update()

Update a user-defined function (UDF).

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!