User-defined functions

Reference:

A user-defined function (UDF) is a stored, reusable FQL statement. You can use UDFs to encapsulate business logic as a manageable, maintainable resource in Fauna.

Define a UDF

You create and manage UDFs as FSL function schemas:

// Defines the `productByNameAndQuantity()` UDF. The function:
// - Accepts the `name` and `quantity` arguments.
// - Uses the `Product` collection's `byName()` index to:
//   - Search for products with the provided `name`.
//   - Filter matching products to those with a quantity
//     less than or equal to the provided `quantity`.
// - Returns a set of the `name`, `description`, and `quantity` of
//   matching products.
function productsByNameAndQuantity(name, quantity) {
  Product.byName(name, { from: quantity }) {
    name: .name,
    description: .description,
    quantity: .quantity
  }
}

You manage and submit schemas to Fauna using the Fauna Dashboard or Fauna CLI.

Call a UDF

Once submitted, you can call the UDF in an FQL query:

// Call the `productsByNameAndQuantity()` with a `name` of
//  `limes` and a `quantity` of `50`:
productsByNameAndQuantity("limes", 50)

Type checking

You can explicitly type a UDF’s arguments and return value in its function schema:

// The `x` argument must be a `Number`.
// The function returns a `Number` value.
function MyFunction(x: Number): Number {
  x + 2
}

UDF privileges

A user-defined role can grant the privilege to call a UDF.

See Function privileges

Runtime privileges

By default, UDFs run with the privileges of the calling uery’s authentication secret.

When you define a UDF, you can include an optional @role annotation. If provided, the UDF runs using the role’s privileges, regardless of the secret used to call it:

// Runs with the built-in `server` role's privileges.
@role(server)
function inventory(name) {
  Product.byName(name) {
    name,
    description,
    quantity
  }
}

Control access with UDFs

A common pattern is to allow access to sensitive data through a UDF. The pattern lets you control how the data is accessed without granting broader privileges.

For more control, you can customize the format of data a UDF returns. This lets you mask, transform, or remove specific fields as needed.

Tutorial: Control access with ABAC

Function system collection

Fauna stores UDFs as documents in the Function system collection. These documents act as an FQL version of the FSL function schema. You can use Function methods to access UDFs in FQL.

See Function FQL docs

Multi-tenancy and scope

UDFs are scoped to a single database. A child database can’t access its parent database’s UDFs.

You can copy and deploy UDFs across databases using FSL and a CI/CD pipeline. See Manage schemas with a CI/CD pipeline.

Limits

UDFs are subject to the same global limits as FQL queries.

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!