Check out v4 of the Fauna CLI

v4 of the Fauna CLI is now in beta.

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

Function.create()

Learn: User-defined functions (UDFs)

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

Create a user-defined Function document.

Signature

Function.create(data: {*: any}) => <Function>

Description

The Function.create() method creates a user-defined Function (UDF) with the provided data, which includes a user-defined function name field. The function is subsequently invoked by its name.

Staged schema

If a database has staged schema, this method adds a function to the staged schema, not the active schema.

If the database has no staged schema, using this method is equivalent to making an unstaged schema change. Changes are applied immediately to the database’s active schema.

Avoid concurrent schema changes

Concurrent unstaged schema changes can cause contended transactions, even if the changes affect different resources. This includes unstaged changes made using:

A schema change triggers a transaction that validates the entire database schema. To avoid errors, do one of the following instead:

Parameters

Parameter Type Required Description

data

Object

Yes

Object describing the UDF. See data fields.

data fields

Name Type Required Description

name

String

Yes

Unique name of the UDF. The name is case insensitive and can’t be a reserved word.

body

String

Yes

FQL expression of the function.

If the function body includes variable interpolation, use one of the following methods to avoid interpolation until the function executes:

  • Enclose the function body in single quotation marks.

  • Escape the interpolation markers.

  • Use heredoc syntax to declare a multiline literal body.

Supports the ... syntax for variadic arguments. See Variadic functions.

role

String

Role to apply when the UDF is called to give the UDF the privileges to that role. Built-in roles include admin, server, and server-readonly. Setting the role privilege gives the function permission to create, change, and remove documents. A UDF can also change the function privileges of a role.

The role can be defined only if you have sufficient privilege, such as admin, server, or a user-defined role that grants write privilege to functions.

Except as noted, a UDF can’t invoke an action that exceeds the privileges of role.

A caller who is a member of a user-defined role with limited privileges can execute a function that has a role that grants the call action privilege. The call action permits the function to execute even if it results in actions that exceed the limited privileges of the caller. Take care when assigning roles with create and call privileges to functions, such as the server role.

If a UDF returns document references, the secret used to call the UDF must have read privileges for the referenced document’s collection. As a workaround, update the UDF to project the desired fields and return the data as an array or object.

See Resolve document references returned by UDFs.

data

Object

User-defined metadata.

Return value

Type Description

Function

New UDF document. See Function.

Examples

  1. Create a UDF:

    Function.create({
  name: 'hello',
  body: '(x) => "Hello #{x}!"'
})
    {
  name: "hello",
  coll: Function,
  ts: Time("2099-10-25T17:56:30.150Z"),
  body: "(x) => \"Hello \#{x}!\""
}

  2. Call the UDF:

    hello("World")
    "Hello World!"

 

  1. Use heredoc syntax to avoid interpolation until the function executes:

    Function.create({
  name: "hello2",
  body: <<-EOB
name => "Hello to you, #{name}!"
EOB
})
    {
  name: "hello2",
  coll: Function,
  ts: Time("2099-11-03T17:06:02.790Z"),
  body: <<-END
    name => "Hello to you, #{name}!"
    END
}

  2. Call the UDF:

    hello2("World")
    "Hello to you, World!"

 

Create a UDF with the admin role:

Function.create({
  name: 'Doublex',
  body: '(x) => x + x',
  role: 'admin',
})
{
  name: "Doublex",
  coll: Function,
  ts: Time("2099-06-25T15:03:14.060Z"),
  body: "(x) => x + x",
  role: "admin"
}

 

Create a UDF with a data metadata field:

Function.create({
  name: "square",
  body: "x => x * x",
  data: {
    version: "1.0"
  }
})
{
  name: "square",
  coll: Function,
  ts: Time("2099-01-08T20:30:50.090Z"),
  body: "x => x * x",
  data: {
    version: "1.0"
  }
}

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!