Document manipulation functions
Reshape a record without touching the table it came from.
Syntax
Write the function's name and the records or template.
MERGE(record1, record2)
UNSET(record, keys)
KEEP(record, keys)
FLATTEN(list)
HANDLEBARS(template, data, [mode])Parameters and arguments
Arguments are written in brackets, separated by commas. An argument in square brackets is optional.
MERGE
Required: Yesrecord1
Required: Yesrecord2UNSET
Required: Yesrecord
Required: YeskeysKEEP
Required: Yesrecord
Required: YeskeysFLATTEN
Required: YeslistHANDLEBARS
Required: Yestemplate
Required: Yesdata
Required: Nomode
Examples
A customer record laid over a record of defaults: the customer's own values win, and the defaults fill what is missing.
Return type and behaviour
Each function returns one value. The table shows its type, what it does and one way to write it; the examples use the functions in realistic statements.
| Function | Returns | Behaviour | Form |
|---|---|---|---|
MERGE | record | One record with the fields of both. Where both have a field, the second record's value is kept | MERGE({"a": 1}, {"b": 2}) |
UNSET | record | The record without those keys | UNSET({"a": 1, "b": 2}, "a") |
KEEP | record | The record with only those keys | KEEP({"a": 1, "b": 2}, "a") |
FLATTEN | list | One list with the items of each inner list, one level deep | FLATTEN([[1, 2], [3]]) |
HANDLEBARS | text | The template with each name filled in | HANDLEBARS("Hi {{name}}", {"name": "Ada"}) |
Errors and exceptions
| Error | What happened | How to recover |
|---|---|---|
HTQL-5001 | The function was given the wrong number of arguments. The message names the function and the counts | Give it the arguments listed under Parameters |
HTQL-1004 Unsupported function | The name is not a function this engine runs | Check the name and its spelling against this entry |
HTQL-5004 | An argument is missing | Give both records, or the record and the keys |
Limitations
- These functions return a new value. They do not change a table: use UPDATE for that.
- Coming: a variable that holds a record with a single field, passed to
HANDLEBARS, fills nothing: afterLET order = {"name": "Ada"},HANDLEBARS("Hi {{name}}", order)answers "Hi ". A record with two or more fields, or one written in the call, works.
Permissions and security
These functions read nothing from your tables and write nothing.
When a function is applied to a column or a variable, the statement that reads the data needs read access, as its own entry says.
Best practices
- Use MERGE to add defaults to a record.
- Use UNSET to drop fields before you return a record to a caller.