User-defined functions

User-defined functions (UDFs) allow developers to combine built-in or user-defined Fauna Query Language functions into named queries that you can execute repeatedly.

By default, UDFs run with the privileges of the current query session. For example, if your client code connects to Fauna using a key with the server role, any called UDFs run with server privileges by default. When you assign a specific role to a UDF, the UDF executes with the assigned role’s privileges which can differ from the caller’s.

This section demonstrates a few of the ways that UDFs can be helpful.

First, create some documents in a collection called "inventory":

CreateCollection({ name: "inventory" })
Map(
  [
    [1, "avocados", 100, 3.99],
    [2, "limes", 30, 0.35],
    [3, "cilantro", 100, 1.49],
  ],
  Lambda(
    ["id", "name", "quantity", "price"],
    Create(
      Ref(Collection("inventory"), Var("id")),
      {
        data: {
          name: Var("name"),
          quantity: Var("quantity"),
          price: Var("price"),
        },
      }
    )
  )
)

[
  {
    ref: Collection("inventory"),
    ts: 1660238557230000,
    history_days: 30,
    name: 'inventory'
  },
  {
    ref: Ref(Collection("inventory"), "1"),
    ts: 1660238557250000,
    data: { name: 'avocados', quantity: 100, price: 3.99 }
  },
  {
    ref: Ref(Collection("inventory"), "2"),
    ts: 1660238557250000,
    data: { name: 'limes', quantity: 30, price: 0.35 }
  },
  {
    ref: Ref(Collection("inventory"), "3"),
    ts: 1660238557250000,
    data: { name: 'cilantro', quantity: 100, price: 1.49 }
  }
]

Query metrics:

bytesIn: 323
bytesOut: 577
computeOps: 1
readOps: 0
writeOps: 3
readBytes: 42
writeBytes: 672
queryTime: 18ms
retries: 0

Create an index to look up inventory items by name:

CreateIndex({
  name: "known_names",
  source: Collection("inventory"),
  terms: [
    { field: ["data", "name"] },
  ],
})

{
  ref: Index("known_names"),
  ts: 1660238557540000,
  active: true,
  serialized: true,
  name: 'known_names',
  source: Collection("inventory"),
  terms: [ { field: [ 'data', 'name' ] } ],
  partitions: 1
}

Query metrics:

bytesIn: 133
bytesOut: 295
computeOps: 1
readOps: 0
writeOps: 4
readBytes: 1,621
writeBytes: 810
queryTime: 14ms
retries: 0

Before you add a new item to this collection, you might want to perform data validation to ensure consistent document structure. For this demonstration, assume that the name must exist within the collection, and the price must be a Double (a double-precision, floating-point number). With a UDF, you can create a function that performs the validation and creates the new document only if its fields contain valid values.

CreateFunction({
  name: "create_new_inventory", (1)
  body:
    Query(
      Lambda( (2)
        // the function takes three parameters
        ["name", "quantity", "price"],
        Let( (3)
          {
            // define two variables
            is_name_known: If( (4)
              GT(Count(Match(Index("known_names"), Var("name"))), 0),
              true,
              false
            ),
            is_price_double: IsDouble(Var("price")),
          },
          If(
            And(Var("is_name_known"), Var("is_price_double")),
            Create( (5)
              Collection("inventory"),
              {
                data: {
                  name: Var("name"),
                  quantity: Var("quantity"),
                  price: Var("price")
                },
              }
            ),
            Abort( (6)
              Concat(
                [
                  If(Var("is_name_known"), "", "Name is unknown. "),
                  If(Var("is_price_double"), "", "Price is not a double. "),
                ],
                ""
              )
            )
          )
        )
      )
    ),
})

{
  ref: Function("create_new_inventory"),
  ts: 1660238557830000,
  name: 'create_new_inventory',
  body: Query(Lambda(["name", "quantity", "price"], Let({"is_name_known": If(GT(Count(Match(Index("known_names"), Var("name"))), 0), true, false), "is_price_double": IsDouble(Var("price"))}, If(And(Var("is_name_known"), Var("is_price_double")), Create(Collection("inventory"), {"data": {"name": Var("name"), "quantity": Var("quantity"), "price": Var("price")}}), Abort(Concat([If(Var("is_name_known"), "", "Name is unknown. "), If(Var("is_price_double"), "", "Price is not a double. ")], ""))))))
}

Query metrics:

bytesIn: 737
bytesOut: 842
computeOps: 1
readOps: 0
writeOps: 1
readBytes: 33
writeBytes: 849
queryTime: 16ms
retries: 0

1	Give the function a name: `create_new_inventory`.
2	Implement the function logic in a `Lambda` or anonymous function. This function takes three inputs: `name`, `quantity`, and `price`.
3	To test for the two conditions, use `Let` to create two variables that both return a boolean: The `is_name_known` variable checks the `known_names` index for existence of the `brand` input. The `is_price_double` variable checks if the `price` input is a Double.
4	The `If` function behaves like a ternary operator: "If X then Y, otherwise Z." If the number of results matching `name` in the `known_names` index is greater than 0, the function returns `true`. Otherwise, it returns `false`.
5	Notice that the `If` function encloses the `Create` function. When the checks pass, `Create` is called. Otherwise, `Abort` is called to terminate the transaction with a custom error message.
6	The error message depends on the two boolean variables, `is_name_known` and `is_price_double`.

To run the UDF, use the Call function:

Call(Function("create_new_inventory"), ["avocados", 100, 2.89])

{
  ref: Ref(Collection("inventory"), "339717346418491904"),
  ts: 1660238558120000,
  data: { name: 'avocados', quantity: 100, price: 2.89 }
}

Query metrics:

bytesIn: 78
bytesOut: 218
computeOps: 1
readOps: 1
writeOps: 1
readBytes: 67
writeBytes: 367
queryTime: 15ms
retries: 0

The example runs successfully because the string avocados is present in the known_names index, and 2.89 is a double. However, if you try to run the function with faulty inputs, you get an error:

Call(Function("create_new_inventory"), ["bananas", 80, "1.89"])

{
  errors: [
    {
      position: [],
      code: 'call error',
      description: 'Calling the function resulted in an error.',
      cause: [
        {
          position: [
            'expr',
            'in',
            'else'
          ],
          code: 'transaction aborted',
          description: 'Name is unknown. Price is not a double. '
        }
      ]
    }
  ]
}

Query metrics:

bytesIn: 78
bytesOut: 237
computeOps: 1
readOps: 0
writeOps: 0
readBytes: 0
writeBytes: 0
queryTime: 5ms
retries: 0

In the future, if you need to refine the create_new_item function, you can update it and continue to use the client code unmodified, provided the function accepts the same inputs. For example, if you want to allow the function to run with the server role regardless of the caller’s role, update the role field of the UDF:

Update(Function("create_new_inventory"), { role: "server" })

{
  ref: Function("create_new_inventory"),
  ts: 1660238558690000,
  name: 'create_new_inventory',
  body: Query(Lambda(["name", "quantity", "price"], Let({"is_name_known": If(GT(Count(Match(Index("known_names"), Var("name"))), 0), true, false), "is_price_double": IsDouble(Var("price"))}, If(And(Var("is_name_known"), Var("is_price_double")), Create(Collection("inventory"), {"data": {"name": Var("name"), "quantity": Var("quantity"), "price": Var("price")}}), Abort(Concat([If(Var("is_name_known"), "", "Name is unknown. "), If(Var("is_price_double"), "", "Price is not a double. ")], "")))))),
  role: 'server'
}

Query metrics:

bytesIn: 84
bytesOut: 858
computeOps: 1
readOps: 0
writeOps: 1
readBytes: 563
writeBytes: 593
queryTime: 12ms
retries: 0

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!

User-defined functions

Limitations

Keyboard shortcuts

While reading

While searching

URL fragments