Execute SQL query
See also: Value from SQL query
Event action – Abstract
Purpose: Executes a native SQL query in the Lobster_data query syntax.
The Execute SQL query event action passes a single native SQL statement to a database that must be accessible to the Lobster Data Platform / Orchestration server via an 'alias'.
While for read accesses the Value from SQL query value resolver can be used alternatively, the event action also allows write (or delete) accesses as far as corresponding permissions exist for the database addressed by alias.
The return value of the SQL statement is written to a result variable. Depending on the type of the SQL statement, two cases can be distinguished:
The rows returned by a SELECT statement are written to the result variable as a list of client objects whose fields reflect the columns of the query. Depending on the database system, the column names appear either uniformly in upper case, uniformly in lower case, or case-sensitive. In any case, the respective spelling must match exactly ('case-sensitive') when accessing the data fields in product name (e.g. via an Object property value resolver).
►NOTE◄ If a query returns no rows, the result variable will contain an empty list that satisfies an Is empty check, but not a comparison like Equals 'no value' (see first example below).All other SQL statements return the number of affected rows as an integer in the result variable. The value is 0, even if the statement does not affect any rows (e.g. DROP TABLE ...).
The SQL statement can include the values of variables from the context of the current event handling via type-safe placeholders according to the Lobster_data query syntax.
Configuration
In the Store result as parameter, static text can be specified as the name of the result variable to which the return value of the database should be written. The specification is basically optional. When executing a SELECT statement, however, it makes limited sense to omit the result variable, provided it is not just a matter of determining whether it can be executed without errors.
The Alias parameter can be specified as static text or as the return value of a value resolver. It must point to a database that can be accessed by the Lobster Data Platform / Orchestration server.
The SQL Query parameter defines the SQL statement to be executed in the native syntax of the database addressed by Alias, if necessary taking into account more typical placeholders, in the place of which the Value of one variable each from the event handling context is inserted at runtime.
For the definition of these placeholders the Lobster_data query syntax with the structure @<index>:<typ>@ is used, e.g. @1:s@ for a string value or @2:t@ for a timestamp.
The <index> must be a positive integer, which is also used as Variable name within the configuration. The values used do not have to be assigned without gaps and in ascending order.
As <typ> an identification letter for a data type must be specified ('l' long, 's' string, for a complete list see Lobster_data query syntax), which must match the intended use for the placeholder.
For all placeholders used in the SQL Query, a corresponding Variable name must be explicitly configured with a value resolver whose return value must correspond to the data type of the placeholder or at least be suitably convertible.
The same Variable name can be referenced by several placeholders, which can even specify different data types if needed, as long as any value occurring at runtime can be converted to all target data types.
►NOTE◄ Placeholders can only be used at positions in the SQL statement that affect values and not, for example, to dynamically assign fields, table names or keywords to the syntax. However, the value for the SQL Query parameter as a whole can be built dynamically (e.g. via Concat strings) to achieve corresponding flexibility.
Example
►NOTE◄ The SQL statements in the following examples refer to a PostgreSQL database.
Querying data from an existing table
The default installation of Lobster_data provides access to database tables via the Alias hub. One of these is the table dw_log, where log entries are stored.
For the following example, the dw_log table is searched for entries written when Lobster_data was restarted. The following SQL query filters for the msg (message text) column and returns the date_at column (number of milliseconds since 01.01.1970) for all 'matches':
SELECT date_at FROM dw_log
WHERE msg like
'%Lobster data%started'
ORDER BY date_at DESC
Since the result rows are sorted in descending order by timestamp (date_at), the first match represents the most recent logged restart of Lobster_data. If no log entry meets the check criterion for the message text (msg), the result list contains no elements.
Whenever a user with the role 'Super user limited' logs in to the client, a notification with the time of the last restart should appear.
Configuration:
An event handler is configured as shown on the right:
|
|
|
|
Alternative configuration with 'conditional notification' |
|
The variant for the configuration shown on the right executes the notification via the Show alert (Popup) event action only if a suitable entry was found in the log table. Otherwise, after executing the Execute SQL query event action, the records variable returns a list object without entries. The Is empty compare type used within the Entity property rule is negated here, so that the Show alert (Popup) event action placed in the 'Then' block is only executed if the log returns a 'match'. ►NOTE◄ The Default value resolver used for notification in the above configuration can be omitted within this case distinction if it can be assumed that the date_at column in the database table contains a timestamp for each log entry. |
|
Delete entries from an existing table
As an example of a 'write access', the deletion of specific entries from an interface table named who_is_who is to be demonstrated here, which is to be triggered whenever certain types of common business objects are assigned the 'Finished' working state.
DELETE FROM who_is_who WHERE obj_ref=@1:l@ AND obj_type=@2:s@
The entries to be deleted are to be identified by a combination of reference number (obj_ref as long value) and object type (as string), for which placeholders are already inserted here.
If entries are deleted, the user should be notified about their number.
Runtime example:
A common business object of the 'Lot/Batch' (LOT) type with the '1402' identifier as the reference value (reference) of the 'Receipt No.' (RECEIPT_NO) reference attribute is assigned the Working state 'Finished'. This deletes all entries in the interface table who_is_who that concern this object (DELETE FROM who_is_who WHERE obj_ref=1402 AND obj_type='LOT') and a notification like the following appears:
Configuration:
An event handler is configured as shown on the right:
|
|
The Execute SQL query event action is parameterized as shown on the right:
|
|