box.schema.func.create()

box.schema.func.create(func_name[, function_options])¶

Create a function. The created function can be used in different usage scenarios, for example, in field or tuple constraints or functional indexes.

Using the body option, you can make a function persistent. In this case, the function is «persistent» because its definition is stored in a snapshot (the box.space._func system space) and can be recovered if the server restarts.

Параметры:	func_name (`string`) – a name of the function, which should conform to the rules for object names function_options (`table`) – see function_options
возвращает:	nil

Примечание

box.schema.user.grant() can be used to allow the specified user or role to execute the created function.

Example 1: a non-persistent Lua function

The example below shows how to create a non-persistent Lua function:

box.schema.func.create('calculate')
box.schema.func.create('calculate', {if_not_exists = false})
box.schema.func.create('calculate', {setuid = false})
box.schema.func.create('calculate', {language = 'LUA'})

Example 2: a persistent Lua function

The example below shows how to create a persistent Lua function, show its definition using box.func.{func-name}, and call this function using box.func.{func-name}:call([parameters]):

tarantool> lua_code = [[function(a, b) return a + b end]]
tarantool> box.schema.func.create('sum', {body = lua_code})

tarantool> box.func.sum
---
- is_sandboxed: false
  is_deterministic: false
  id: 2
  setuid: false
  body: function(a, b) return a + b end
  name: sum
  language: LUA
...

tarantool> box.func.sum:call({1, 2})
---
- 3
...

To call functions using net.box, use net_box:call().

Example 3: a persistent SQL expression used in a tuple constraint

The code snippet below defines a function that checks a tuple’s data using the SQL expression:

box.schema.func.create('check_person', {
    language = 'SQL_EXPR',
    is_deterministic = true,
    body = [["age" > 21 AND "name" != 'Admin']]
})

Then, this function is used to create a tuple constraint:

local customers = box.schema.space.create('customers', { constraint = 'check_person' })
customers:format({
    { name = 'id', type = 'number' },
    { name = 'name', type = 'string' },
    { name = 'age', type = 'number' },
})
customers:create_index('primary', { parts = { 1 } })

On an attempt to insert a tuple that doesn’t meet the required criteria, an error is raised:

customers:insert { 2, "Bob", 18 }
-- error: Check constraint 'check_person' failed for a tuple

function_options

object function_options¶

A table containing options passed to the box.schema.func.create(func-name [, function_options]) function.

function_options.if_not_exists¶: Specify whether there should be no error if the function already exists.

Type: boolean

Default: false

function_options.setuid¶: Make Tarantool treat the function’s caller as the function’s creator, with full privileges. Note that setuid works only over binary ports. setuid doesn’t work if you invoke a function using the admin console or inside a Lua script.

Type: boolean

Default: false

function_options.language¶

Specify the function language. The possible values are:

LUA: define a Lua function in the body attribute.
SQL_EXPR: define an SQL expression in the body attribute. An SQL expression can only be used as a field or tuple constraint.
C: import a C function using its name from a .so file. Learn how to call C code from Lua in the C tutorial.

Примечание

To reload a C module with all its functions without restarting the server, call box.schema.func.reload().

Type: string

Default: LUA

function_options.is_sandboxed¶

Whether the function should be executed in an isolated environment. This means that any operation that accesses the world outside the sandbox is forbidden or has no effect. Therefore, a sandboxed function can only use modules and functions that cannot affect isolation:

assert, assert, error, ipairs, math.*, next, pairs, pcall, print, select, string.*, table.*, tonumber, tostring, type, unpack, xpcall, utf8.*.

Also, a sandboxed function cannot refer to global variables – they are treated as local variables because the sandbox is established with setfenv. So, a sandboxed function is stateless and deterministic.

Type: boolean

Default: false

function_options.is_deterministic¶: Specify whether a function should be deterministic.

Type: boolean

Default: false

function_options.is_multikey¶: If true is set in the function definition for a functional index, the function returns multiple keys. For details, see the example.

Type: boolean

Default: false

function_options.body¶

Specify a function body. You can set a function’s language using the language attribute.

The code snippet below defines a constraint function that checks a tuple’s data using a Lua function:

box.schema.func.create('check_person', {
    language = 'LUA',
    is_deterministic = true,
    body = 'function(t, c) return (t.age >= 0 and #(t.name) > 3) end'
})

In the following example, an SQL expression is used to check a tuple’s data:

box.schema.func.create('check_person', {
    language = 'SQL_EXPR',
    is_deterministic = true,
    body = [["age" > 21 AND "name" != 'Admin']]
})

Example: A persistent SQL expression used in a tuple constraint

Type: string

Default: nil

function_options.takes_raw_args¶

Since: 2.10.0

If set to true for a Lua function and the function is called via net.box (conn:call()) or by box.func.<func-name>:call(), the function arguments are passed being wrapped in a MsgPack object:

local msgpack = require('msgpack')
box.schema.func.create('my_func', {takes_raw_args = true})
local my_func = function(mp)
    assert(msgpack.is_object(mp))
    local args = mp:decode() -- array of arguments
end

If a function forwards most of its arguments to another Tarantool instance or writes them to a database, the usage of this option can improve performance because it skips the MsgPack data decoding in Lua.

Type: boolean

Default: false

function_options.exports¶

Specify the languages that can call the function.

Example: exports = {'LUA', 'SQL'}

Версия:

box.schema.func.create()

function_options