FQL v4 will be decommissioned on June 30, 2025. Ensure that you complete your migration from FQL v4 to FQL v10 by that date.

For more details, review the migration guide. Contact support@fauna.com with any questions.

CreateFunction

This reference topic applies to FQL v4. Go to this page for the latest FQL v10 reference topics.

 
CreateFunction( param_object )
create_function( param_object )
CreateFunction( param_object )
CreateFunction( param_object )
CreateFunction( param_object )

Description

The CreateFunction operation adds a new user-defined function with the specified parameters.

Parameters

Parameter Type Definition and Requirements

param_object

Object

The param_object fields are described below.

param_object

Field Name Field Type Definition and Requirements

name

String

The name of the function.

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

body

Object

The FQL instructions to be executed.

data

Object

Optional - This is user-defined metadata for the user-defined function. It is provided for the developer to store information at the function level.

role

Object or Role Reference

Optional - Specifies the role that should be used when the user-defined function is called, which would typically be used to provide privilege escalation when current privileges would otherwise be too restrictive.

To use a built-in role, specify one of the strings admin, server, server-readonly, client. To use a user-defined role, specify a Role reference, e.g. Role("admin").

role can only be set by users with a privileged role, such as admin, server, or a user-defined role that grants write privilege for functions.

Use role carefully! Setting role to admin, server, or any other privileged role gives your function permission to create/modify/remove any documents when invoked by any caller. Users that can write functions can adjust role to change the function’s privileges.

Returns

An object containing the metadata of CreateFunction operations.

Field Name Field Type Definition and Requirements

ref

Reference

The reference is an automatically-generated, unique identifier within the database to identify the function that was created.

name

String

The logical name of the function created.

role

Object or Role Reference

The role that should be used when the function is called. Only included when role is specified in param_object.

ts

Long

The timestamp, with microsecond resolution, associated with the creation of the function.

body

Object

The FQL instructions to be executed.

Examples

The following query creates a user-defined function called "double":

client.query(
  q.CreateFunction({
    name: 'double',
    body: q.Query(
      q.Lambda('x', q.Add(q.Var('x'), q.Var('x')))
    ),
  })
)
.then((ret) => console.log(ret))
.catch((err) => console.error(
  'Error: [%s] %s: %s',
  err.name,
  err.message,
  err.errors()[0].description,
))
{
  ref: Function("double"),
  ts: 1591997162610000,
  name: 'double',
  body: Query(Lambda("x", Add(Var("x"), Var("x"))))
}
result = client.query(
  q.create_function({
    "name": "double",
    "body": q.query(
      q.lambda_("x", q.add(q.var("x"), q.var("x")))
    ),
  })
)
print(result)
{'ref': Ref(id=double, collection=Ref(id=functions)), 'ts': 1611102297910000, 'name': 'double', 'body': Query({'api_version': '4', 'lambda': 'x', 'expr': {'add': [{'var': 'x'}, {'var': 'x'}]}})}
result, err := client.Query(
	f.CreateFunction(f.Obj{
		"name": "double",
		"body": f.Query(f.Lambda("x", f.Add(f.Var("x"), f.Var("x")))),
	}),
)

if err != nil {
	fmt.Fprintln(os.Stderr, err)
} else {
	fmt.Println(result)
}
map[body:{[123 34 97 112 105 95 118 101 114 115 105 111 110 34 58 34 52 34 44 34 108 97 109 98 100 97 34 58 34 120 34 44 34 101 120 112 114 34 58 123 34 97 100 100 34 58 91 123 34 118 97 114 34 58 34 120 34 125 44 123 34 118 97 114 34 58 34 120 34 125 93 125 125]} name:double ref:{double 0xc000178270 0xc000178270 <nil>} ts:1631915951360000]
try
{
    Value result = await client.Query(
        CreateFunction(
            Obj(
                "name", "double",
                "body", Query(
                    Lambda("x", Add(Var("x"), Var("x")))
                )
            )
        )
    );
    Console.WriteLine(result);
}
catch (Exception e)
{
    Console.WriteLine($"ERROR: {e.Message}");
}
ObjectV(ref: RefV(id = "double", collection = RefV(id = "functions")),ts: LongV(1611102338170000),name: StringV(double),body: QueryV(System.Collections.Generic.Dictionary`2[System.String,FaunaDB.Query.Expr]))
CreateFunction({
  name: 'double',
  body: Query(
    Lambda('x', Add(Var('x'), Var('x')))
  )
})
{
  ref: Function("double"),
  ts: 1631916677410000,
  name: 'double',
  body: Query(Lambda("x", Add(Var("x"), Var("x"))))
}
Query metrics:

  •    bytesIn:  121

  •   bytesOut:  216

  • computeOps:    1

  •    readOps:    0

  •   writeOps:    1

  •  readBytes:  103

  • writeBytes:  362

  •  queryTime: 21ms

  •    retries:    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!