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:

  1. 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).

  2. 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

images/download/attachments/177911946/image-2024-9-17_15-53-4-version-1-modificationdate-1726581183546-api-v2.png

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:

  • 'Client logged in' is selected as the Triggering event (see Login (Events)).


  • As a Validating rule, a Role rule for the 'Super user limited' role is checked.


  • Under the Action on passed rule, the Execute SQL query event action is executed first, which should store its search result in the records variable specified by Store result as.

  • The Alias hub, is specified here as static text. It defines the context in which the statement defined by the SQL Query parameter is executed. This is also defined as static text, but unlike the version above, it contains the placeholder @1:s@, which 'makes variable' the last section of the string to be checked. This is to demonstrate the use of a placeholder, but also simplifies an adjustment of the statement, if any other keyword than 'started' – e.g. 'stopped' – is to be searched for.

  • In the present configuration, the Value for the placeholder is defined as static text for Variable name 1.

  • This is followed by an event handler of the Show alert (Popup) type, which prepares the result of the SELECT statement stored in the variable records for a notification like the following (see below for details):

images/download/attachments/177911946/image2021-4-22_8-26-38-version-1-modificationdate-1726581069994-api-v2.png

images/download/attachments/177911946/image2021-4-22_8-28-6-version-1-modificationdate-1726581069991-api-v2.png

  • The information should appear as a notification of the Type 'Info' (i.e. temporarily displayed on the right edge of the screen).

  • The Title content builder defines a static text, for the notification headline.
    NOTE◄ In practice, a value resolver of the Value from localization type would actually be preferred, which provides a suitable localization entry.

  • In the Message content builder, a concatenation of value resolvers controls access to the 'loading capacity' from the return value of the SELECT statement:

    • First, a Variable value resolver reads the variable records, whose value is always expected as a list (see the option Is collection of) of client objects (see Type) with a single data field (date_at), which can be empty if necessary.

    • Since the query used can return multiple 'matching rows', the decisive match at the first list position must be explicitly addressed by the List item resolver with the Mode 'Get first' and Offset 0.

    • Within the 'result row' determined in this way, the following Object property value resolver accesses the only field (latest_ts) with the searched timestamp. This is prepared for output by Format date, so that the user is not confronted with the huge number of milliseconds.

    • The concatenation of value resolvers is completed here by a Default value resolver, which outputs a statically defined text in cases where the searched log entry tag is not found at all. Then the variable records contains an empty list and the List item resolver for the first list value returns 'no value'.

images/download/attachments/177911946/image2021-4-22_8-30-10-version-1-modificationdate-1726581069988-api-v2.png

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.

images/download/attachments/177911946/image2021-4-22_8-32-0-version-1-modificationdate-1726581069986-api-v2.png

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:

images/download/attachments/177911946/image2021-4-22_8-36-41-version-1-modificationdate-1726581069983-api-v2.png

Configuration:

An event handler is configured as shown on the right:

  • The event handling reacts to the Triggering event 'Finished' (see Working state (Events)), which is triggered when a business object is assigned the working state 'Finished'.


  • Deletion in the interface table should be performed only for common business objects of certain types. For this purpose, a Check type (on 'Common business object') and an Entity property rule for the field 'Business object type' are AND-linked (collapsed in the image), which checks whether the type of the input object is named in a positive list.


  • If the deletion is relevant, an event action of the Execute SQL query type is first executed under the Actions on passed rule, which passes the DELETE statement to the database and stores the returned number of deleted records in the deleted variable. Details about this are explained below.

  • Then the return value is used to check whether records have been deleted (deleted> 0) via If then else.

  • The user will only be notified about the deletion performed via the Show alert (Popup) if records have been deleted. A detailed description of the configuration for this event action is omitted here. Essentially, the components relevant to the output are combined by text concatenation. This accesses the value of the deleted variable, which contains the number of deleted records.

images/download/attachments/177911946/image2021-4-22_8-38-43-version-1-modificationdate-1726581069969-api-v2.png

The Execute SQL query event action is parameterized as shown on the right:

  • The return value is stored in the variable named deleted by the Store result as parameter.

  • The database with the interface table who_is_who is to be accessible for the Lobster Data Platform / Orchestration server via the Alias scm set up for this purpose. The delete query defined in the SQL Query parameter is sent to this database.

  • At runtime, the placeholders @1:l@ and @2:s@ defined in the SQL Query are replaced with the Values of the variables defined below with the Variable names 1 and 2.

  • The placeholder @1:l@ is assigned the reference (reference) from the reference attribute 'Receipt No.' (RECEIPT_NO) of the just completed business object. This is previously converted from the String type to Long via the concatenated Input object (type safe) resolver, which the placeholder specifies to match the column definition of the interface table.

    NOTE◄ It is also possible to do without this explicit type conversion. However, an error (possibly with abort and rollback) occurs if the reference attribute contains a string at runtime for which the automatic type conversion to Long fails. In contrast, the explicit type conversion returns the value null in this case. Whether this causes an error, no effect or undesired effects, depends on the specific content of the SQL Query. If required, a Default value resolver can be concatenated in the definition for the Variable name, which assigns a specific value with the data type of the placeholder in case of conversion problems.

  • The placeholder @2:s@ is assigned the internal name of the business object type to which the just completed business object belongs. In the runtime example, the text value LOT is for the type 'Lot/Batch'.

images/download/attachments/177911946/image2021-4-22_8-40-5-version-1-modificationdate-1726581069965-api-v2.png