|
| 1 | +--- |
| 2 | +title: Stored Procedures |
| 3 | +--- |
| 4 | + |
| 5 | +## Using Stored Procedures |
| 6 | + |
| 7 | +### Creating a Procedure on the Tarantool Node |
| 8 | + |
| 9 | +```lua |
| 10 | +function insert_person(id) |
| 11 | + return crud.insert('person', {id, true, 'hello'}) |
| 12 | +end |
| 13 | +box.schema.func.create('insert_person') |
| 14 | + |
| 15 | +function echo(in_value) |
| 16 | + return in_value |
| 17 | +end |
| 18 | +box.schema.func.create('echo') |
| 19 | +``` |
| 20 | + |
| 21 | +The `person` space has the following data format: |
| 22 | + |
| 23 | +```lua |
| 24 | +format = { |
| 25 | + { 'id', type = 'number' }, |
| 26 | + { 'is_married', type = 'boolean', is_nullable = true }, |
| 27 | + { 'name', type = 'string' }, |
| 28 | + { 'bucket_id', 'unsigned' }, |
| 29 | +} |
| 30 | +``` |
| 31 | + |
| 32 | +### Calling Stored Procedures |
| 33 | + |
| 34 | +To call a stored procedure, use the `TarantoolClient` API: |
| 35 | + |
| 36 | +```java |
| 37 | +// ... creating TarantoolCrudClient client |
| 38 | + |
| 39 | +final List<?> data = crudClient.call("insert_person", Arrays.asList(1)).join().get(); |
| 40 | +``` |
| 41 | + |
| 42 | +The stored procedure `insert_person` accepts one argument `id`. In the procedure, a record with the identifier `id` is inserted. The `crud.insert(...)` method returns a Go-like tuple `result, err`, where |
| 43 | + |
| 44 | +```plaintext |
| 45 | +// structure |
| 46 | +result : { |
| 47 | + rows: array<array<object>>, |
| 48 | + metadata: map<string, object> |
| 49 | +} |
| 50 | +
|
| 51 | +// structure |
| 52 | +err: { |
| 53 | + line: string, |
| 54 | + class_name: string, |
| 55 | + err: string, |
| 56 | + file: string, |
| 57 | + str: string |
| 58 | +} |
| 59 | +``` |
| 60 | + |
| 61 | +On the first call to the stored function, the Java client will return the following query result: |
| 62 | + |
| 63 | +```plaintext |
| 64 | +data = [ |
| 65 | + { |
| 66 | + rows=[ |
| 67 | + Tuple(formatId = 55, data = [1, false, hello, 477], format = []) |
| 68 | + ], |
| 69 | + metadata=[ |
| 70 | + {name=id, type=number}, |
| 71 | + {type=boolean, name=is_married, is_nullable=true}, |
| 72 | + {name=name, type=string}, |
| 73 | + {name=bucket_id, type=unsigned} |
| 74 | + ] |
| 75 | + }, // result |
| 76 | + null // error |
| 77 | +] |
| 78 | +``` |
| 79 | + |
| 80 | +On a repeated call due to identifier duplication, the `crud.insert(...)` method will return an error: |
| 81 | + |
| 82 | +```plaintext |
| 83 | +data = [ |
| 84 | + null, // result |
| 85 | + { // error |
| 86 | + line=120, |
| 87 | + class_name=InsertError, |
| 88 | + |
| 89 | + err=Failed to insert: Duplicate key exists in unique index "pk" in space "person" with old \ |
| 90 | + tuple - [1, false, "hello", 477] and new tuple - [1, false, "hello", 477], |
| 91 | + |
| 92 | + file=/app/.rocks/share/tarantool/crud/insert.lua, |
| 93 | + |
| 94 | + str=InsertError: Failed to insert: Duplicate key exists in unique index "pk" in space \ |
| 95 | + "person" with old tuple - [1, false, "hello", 477] and new tuple - [1, false, "hello", 477] |
| 96 | + } |
| 97 | +] |
| 98 | +``` |
| 99 | + |
| 100 | +```java |
| 101 | +// ... creating TarantoolBoxClient |
| 102 | +// Calling a stored procedure with an input argument of type int |
| 103 | +final List<?> data = crudClient.call("echo", Arrays.asList(1)).join().get(); |
| 104 | + |
| 105 | +// Calling a stored procedure with an input argument of type String |
| 106 | +final List<?> data = crudClient.call("echo", Arrays.asList("hello")).join().get(); |
| 107 | + |
| 108 | +// Calling a stored procedure with an input argument of type boolean |
| 109 | +final List<?> data = crudClient.call("echo", Arrays.asList(true)).join().get(); |
| 110 | +``` |
| 111 | + |
| 112 | +The stored procedure `echo` accepts one argument `in_value`. In the procedure, the input argument is returned. When calling the stored function, the Java client will return the following query result: |
| 113 | + |
| 114 | +```plaintext |
| 115 | +// Result of crudClient.call("echo", Arrays.asList(1)).join().get(); |
| 116 | +data = [1] // array with one int element |
| 117 | +
|
| 118 | +// Result of crudClient.call("echo", Arrays.asList("hello")).join().get(); |
| 119 | +data = ["hello"] // array with one String element |
| 120 | +
|
| 121 | +// Result of crudClient.call("echo", Arrays.asList(true)).join().get(); |
| 122 | +data = [true] // array with one boolean element |
| 123 | +``` |
| 124 | + |
| 125 | +Stored procedures can accept 0 or more input and output arguments. Conversion |
| 126 | +of Java types to Tarantool types is performed using Jackson serializers/deserializers |
| 127 | +([more details](./tuple_pojo_mapping.md)). To specify custom type conversions, |
| 128 | +refer to the [Jackson documentation](https://github.com/FasterXML/jackson-databind/wiki). |
0 commit comments