box.schema.func.create()
-
box.schema.func.
create
(func-name[, {options-without-body}])¶ Create a function tuple without including the
body
option. For functions created with thebody
option, see box.schema.func.create(func-name [, {options-with-body}]).This is called a «not persistent» function because functions without bodies are not persistent. This does not create the function itself – that is done with Lua – but if it is necessary to grant privileges for a function,
box.schema.func.create
must be done first. For explanation of how Tarantool maintains function data, see the reference for the box.space._func space.Возможны следующие опции:
if_not_exists
=true|false
(default =false
) –true
means there should be no error if the_func
tuple already exists.setuid
=true|false
(default =false
) – withtrue
to make Tarantool treat the function’s caller as the function’s creator, with full privileges. Remember that SETUID works only over binary ports. SETUID doesn’t work if you invoke a function via an admin console or inside a Lua script.language
= „LUA“|“C“ (default = „LUA“).(since version 2.10.0)
takes_raw_args
=true|false
(default =false
)— if set totrue
for a Lua function and the function is called vianet.box
(conn:call()) or bybox.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.
Параметры: - func-name (
string
) – имя функции, которое должно соответствовать правилам именования объектов - options (
table
) –if_not_exists
,setuid
,language
,takes_raw_args
.
возвращает: nil
These functions can be called with
function-object:call(arguments)
; however, unlike the case with ordinary functions, array arguments will not be correctly recognized unless they are enclosed in braces.Пример:
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'})
-
box.schema.func.
create
(func-name[, {options-with-body}]) Create a function tuple. including the
body
option. (For functions created without thebody
option, see box.schema.func.create(func-name [, {options-without-body}]).This is called a «persistent» function because only functions with bodies are persistent. This does create the function itself, the body is a function definition. For explanation of how Tarantool maintains function data, see the reference for the box.space._func space.
Возможны следующие опции:
if_not_exists
=true|false
(default =false
) - boolean; same as for box.schema.func.create(func-name [, {options-without-body}]).setuid
=true|false
(default =false
) - boolean; same as for box.schema.func.create(func-name [, {options-without-body}]).language
= „LUA“|“C“ (default = ‘LUA’) - string. same as for box.schema.func.create(func-name [, {options-without-body}]).is_sandboxed
=true|false
(default =false
) - boolean; whether the function should be executed in a sandbox.is_deterministic
=true|false
(default =false
) - boolean;true
means that the function should be deterministic,false
means that the function may or may not be deterministic.is_multikey
=true|false
(default =false
)— iftrue
is set in the function definition for a functional index, the function returns multiple keys. For details, see the example.body
= function definition (default = nil) - string; the function definition.- Additional options for SQL = See Calling Lua routines from SQL.
takes_raw_args
– see the option description in box.schema.func.create(func-name [, {options-with-body}]).
Параметры: - func-name (
string
) – имя функции, которое должно соответствовать правилам именования объектов - options (
table
) –if_not_exists
,setuid
,language
,is_sandboxed
,is_deterministic
,body
.
возвращает: nil
C functions are imported from .so files, Lua functions can be defined within
body
. We will only describe Lua functions in this section.A function tuple with a body is «persistent» because the tuple is stored in a snapshot and is recoverable if the server restarts. All of the option values described in this section are visible in the box.space._func system space.
If
is_sandboxed
is true, then the function will be executed in an isolated environment: any operation that accesses the world outside the sandbox will be forbidden or will have no effect. Therefore a sandboxed function can only use modules and functions which cannot affect isolation: assert, error, ipairs, math.*, next, pairs, pcall, print, select, string.*, table.*, tonumber, tostring, type, unpack, utf8.*, xpcall. Also a sandboxed function cannot refer to global variables – they will be treated as local variables because the sandbox is established with setfenv. So a sandboxed function will happen to be stateless and deterministic.If
is_deterministic
is true, there is no immediate effect. Tarantool plans to use the is_deterministic value in a future version. A function is deterministic if it always returns the same outputs given the same inputs. It is the function creator’s responsibility to ensure that a function is truly deterministic.Using a persistent Lua function
After a persistent Lua function is created, it can be found in the box.space._func system space, and it can be shown with
box.func.func-name
and it can be invoked by any user with authorization to „execute“ it. The syntax for invoking is:
box.func.func-name:call([parameters])
or, if the connection is remote, the syntax is as in net_box:call().Пример:
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 ...