This is an automated email from the ASF dual-hosted git repository.
bamaer pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/hop.git
The following commit(s) were added to refs/heads/main by this push:
new 70205185a5 Batch 8: Result sections for the database actions. #8970
(#9139)
70205185a5 is described below
commit 70205185a52dd406dcccc800de882ddf6abb9009
Author: Adalennis <[email protected]>
AuthorDate: Fri Oct 30 10:35:02 2026 +0100
Batch 8: Result sections for the database actions. #8970 (#9139)
* Batch 8: Result sections for the database actions: Check DB connections,
Columns exist, Evaluate rows numbers, SQL, Table exists, Truncate tables, Wait
for SQL. #8970
* Batch 8: Columns exist passes on Lines written when it stops early, empty
Custom SQL is an error. #8970
* Wait for SQL waits forever with the default timeout; empty or unknown
connection in the False rows. #8970
---
.../pages/workflow/actions/checkdbconnection.adoc | 22 ++++++++++++++++-----
.../ROOT/pages/workflow/actions/columnsexist.adoc | 16 ++++++++++++++-
.../workflow/actions/evaluatetablecontent.adoc | 22 ++++++++++++++++++---
.../modules/ROOT/pages/workflow/actions/sql.adoc | 23 ++++++++++++++++++----
.../ROOT/pages/workflow/actions/tableexists.adoc | 15 ++++++++++++++
.../pages/workflow/actions/truncatetables.adoc | 20 +++++++++++++++++--
.../ROOT/pages/workflow/actions/waitforsql.adoc | 19 +++++++++++++++++-
7 files changed, 121 insertions(+), 16 deletions(-)
diff --git
a/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/checkdbconnection.adoc
b/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/checkdbconnection.adoc
index b7ba1cb9d3..f4896c9451 100644
---
a/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/checkdbconnection.adoc
+++
b/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/checkdbconnection.adoc
@@ -30,12 +30,24 @@ The `Check DB Connections` workflow action verifies
connectivity with one or sev
|===
|Option|Description
|Action name|The name of the workflow action.
-|Connection|List of connections.
-// |Wait|After the connection was opened, wait x (s, min, hrs).
-// |Units of Time|Specify the unit of measurement for the length of time to
remain connected.
-// |Get connections|Get available connects.
+|Connections|The connections to check, one per line. Each line has a
*Connection*, a *Wait* and *Units of time*.
+|Wait|How long to keep the connection open after it was opened. Empty or 0: no
wait.
+|Units of time|The unit of *Wait*: Milliseconds, Seconds, Minutes or Hours.
|===
The `Get connections` retrieves all of the available
xref:metadata-types/rdbms-connection.adoc[Relational Database Connections] in
the current project.
-The `Delete` button deletes the selected database connection line from the
`Connections` table.
\ No newline at end of file
+The `Delete` button deletes the selected database connection line from the
`Connections` table.
+
+== Result
+
+What this action passes on to the next action. See
xref:workflow/action-results.adoc[Action results] for how results travel
through a workflow.
+
+[options="header", width="90%", cols="1,3"]
+|===
+|Result|Value
+|True|Every connection in the list could be opened, with 0 errors. An empty
list is also true.
+|False|A connection can't be opened, or doesn't exist in the project. The
other connections are still checked: the number of errors is the number of
connections that failed.
+|Result files|Passed on unchanged.
+|Result rows|Passed on unchanged.
+|===
diff --git
a/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/columnsexist.adoc
b/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/columnsexist.adoc
index 25791020f3..5a08e452b0 100644
--- a/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/columnsexist.adoc
+++ b/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/columnsexist.adoc
@@ -38,4 +38,18 @@ The `Columns exist in a table` action verifies that one or
more columns exist in
Use the `Browse` buttons to select a database schema or table from the
selected connection.
-Use the `Get columns` button to retrieve the columns from the selected table.
\ No newline at end of file
+Use the `Get columns` button to retrieve the columns from the selected table.
+
+== Result
+
+What this action passes on to the next action. See
xref:workflow/action-results.adoc[Action results] for how results travel
through a workflow.
+
+[options="header", width="90%", cols="1,3"]
+|===
+|Result|Value
+|True|Every column in the list exists in the table, with 0 errors.
+|False|A column doesn't exist, the table doesn't exist, the list of columns is
empty, or the connection is empty, unknown or can't be opened. The number of
errors is 1.
+|Result files|Passed on unchanged.
+|Result rows|Passed on unchanged.
+|Lines written|The number of columns that exist in the table. When the
connection is empty or unknown, *Table name* is empty or the list of columns is
empty, the action stops before it checks anything and the value of the previous
action is passed on unchanged.
+|===
diff --git
a/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/evaluatetablecontent.adoc
b/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/evaluatetablecontent.adoc
index 0e604f638c..5eab281fa8 100644
---
a/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/evaluatetablecontent.adoc
+++
b/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/evaluatetablecontent.adoc
@@ -52,13 +52,29 @@ For the success condition you can check the number of rows
if they are:
* Smaller than
* Smaller or equal to
* Greater than (default)
-* Greater than or equal to
+* Greater or equal to
|Limit|the number of rows to evaluate in combination with the selected option
above.
2+|Custom SQL
|Custom SQL|Check this option when you want to specify a custom SQL statement
in the `SQL Script` field below.
|Use variable substitution|Variables in the SQL statements will be substituted.
-|Clear list of result rows|Clears the internal list of result rows before
executing.
+|Clear list of result rows before execution|Clears the internal list of result
rows before executing.
|Add rows to result|Adds all rows returned from the SQL statement within the
internal list of result rows.
This list of result rows can then be used in subsequent workflow actions to
loop over or e.g. within a pipeline by the Get rows from result transform.
|SQL Script|The custom SQL script to use. The `Custom SQL` option above needs
to be checked before this field is enabled.
-|===
\ No newline at end of file
+|===
+
+== Result
+
+What this action passes on to the next action. See
xref:workflow/action-results.adoc[Action results] for how results travel
through a workflow.
+
+[options="header", width="90%", cols="1,3"]
+|===
+|Result|Value
+|True|The number of rows meets the *Success when rows count* condition, with 0
errors.
+|False|The condition is not met: the number of errors is 0. When the table
doesn't exist, *Target table name* is empty (without *Custom SQL*), *SQL
Script* is empty (with *Custom SQL*), the query fails, or the connection is
empty, unknown or can't be opened, the number of errors is 1.
+|Result files|Passed on unchanged.
+|Result rows|Without *Custom SQL*: passed on unchanged. With *Custom SQL*:
*Clear list of result rows before execution* removes the previous result rows,
also when *Add rows to result* is unchecked. *Add rows to result* adds the rows
the query returns, also when the condition is not met.
+|Lines read|The number of rows counted.
+|===
+
+NOTE: With *Custom SQL*, the action counts the rows the query returns, not a
value in them. `SELECT count(*) FROM my_table` returns 1 row, so the number of
rows is 1 whatever the table holds. Write a query that returns one row per item
to count, such as `SELECT * FROM my_table WHERE ...`.
diff --git a/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/sql.adoc
b/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/sql.adoc
index 2333363909..7eeb7a5054 100644
--- a/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/sql.adoc
+++ b/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/sql.adoc
@@ -36,13 +36,28 @@ Common uses associated with the SQL workflow action include
truncating tables, d
|===
|Option|Description
|Action name|The name of the workflow action.
-|Database Connection|The database connection to use.
+|Connection|The database connection to use.
|SQL from file|Enable this option to load the SQL statement from a file given
by the SQL filename
|SQL filename|The filename for the file with SQL statements.
|File encoding|Character encoding of the SQL file (e.g. UTF-8, windows-1252).
Leave empty to use the system default. Useful when the file is UTF-8 but the
system uses another encoding (e.g. Windows-1252).
-|Send SQL as single statement?|Enable this option to not separate the
statement by semicolons.
+|Send SQL as single statement|Enable this option to not separate the statement
by semicolons.
This is often useful when a script is given or multiple statements should be
processed and committed as one single statement.
-|Use variable substitution?|Enables variables to be used in the SQL Script.
-|SQL script|The SQL script to execute.
+|Use variable substitution|Enables variables to be used in the SQL Script.
+|SQL Script|The SQL script to execute.
Multiple statements can be separated by semicolons.
|===
+
+== Result
+
+What this action passes on to the next action. See
xref:workflow/action-results.adoc[Action results] for how results travel
through a workflow.
+
+[options="header", width="90%", cols="1,3"]
+|===
+|Result|Value
+|True|Every statement ran, with 0 errors. An empty SQL script is also true.
+|False|A statement fails, the SQL file doesn't exist, or the connection is
unknown or can't be opened. The number of errors is 1.
+|Result files|Passed on unchanged.
+|Result rows|Passed on unchanged.
+|===
+
+NOTE: Without *Send SQL as single statement*, the statements run one after the
other. When one fails, the changes of the statements before it are kept, and
the statements after it are not run. With *Send SQL as single statement*, the
script goes to the database in one piece, and what is kept after an error
depends on the database: on PostgreSQL, none of the changes are kept.
diff --git
a/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/tableexists.adoc
b/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/tableexists.adoc
index c9de9d8b8c..060133d7cb 100644
--- a/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/tableexists.adoc
+++ b/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/tableexists.adoc
@@ -44,3 +44,18 @@ There is no point in processing the workflow until the data
is available, so you
|Schema name|The schema name if applicable to your database
|Table name|The name of the database table to check
|===
+
+== Result
+
+What this action passes on to the next action. See
xref:workflow/action-results.adoc[Action results] for how results travel
through a workflow.
+
+[options="header", width="90%", cols="1,3"]
+|===
+|Result|Value
+|True|The table exists, with 0 errors.
+|False|The table doesn't exist: the number of errors is 0. When the connection
is empty or can't be opened, the number of errors is 1.
+|Result files|Passed on unchanged.
+|Result rows|Passed on unchanged.
+|===
+
+NOTE: A *Connection* that doesn't exist in the project also gives false with 0
errors, and nothing is logged: the same result as a table that doesn't exist.
diff --git
a/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/truncatetables.adoc
b/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/truncatetables.adoc
index 6df6bee99c..c2f4e781b3 100644
---
a/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/truncatetables.adoc
+++
b/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/truncatetables.adoc
@@ -31,10 +31,26 @@ The `Truncate tables` action truncates one or several
tables.
|Option|Description
|Action name|The name of the workflow action.
|Connection|Name of the database connection on which the tables reside.
-|Previous results to args?|Check this option if you want to get in a dynamic
way tables to truncate from results of previous workflow action.
+|Previous results to args|Check this option if you want to get in a dynamic
way tables to truncate from results of previous workflow action.
|Click here to return tables name list|This button will return all tables
defined on the connection.
Select tables (one or several) and press "OK".
Tables name will be automatically added to "Selected tables" grid.
|Selected tables grid|Specify here the tables to truncate (insert it manually
or use the previous button).
-If the table is in a different schema that the default one, please specify the
schema name.
+If the table is in a different schema than the default one, please specify the
schema name.
|===
+
+== Result
+
+What this action passes on to the next action. See
xref:workflow/action-results.adoc[Action results] for how results travel
through a workflow.
+
+[options="header", width="90%", cols="1,3"]
+|===
+|Result|Value
+|True|Every table was truncated, with 0 errors. Also true when there is
nothing to truncate: an empty list, or *Previous results to args* checked while
there are no previous result rows (the tables in the grid are not truncated
then).
+|False|A table doesn't exist, or the connection is unknown or can't be opened.
The number of errors is 1: the action stops at the first table that fails, and
the tables after it are not truncated.
+|Result files|Passed on unchanged.
+|Result rows|Passed on unchanged.
+|Lines deleted|The number of tables truncated, not the number of rows.
+|===
+
+NOTE: With *Previous results to args*, the first field of each result row is
the table name and the second field the schema name. A row with an empty table
name is skipped: it is logged as an error, but doesn't count as one.
diff --git
a/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/waitforsql.adoc
b/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/waitforsql.adoc
index d53576ef2c..d1d76f6ad2 100644
--- a/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/waitforsql.adoc
+++ b/docs/hop-user-manual/modules/ROOT/pages/workflow/actions/waitforsql.adoc
@@ -32,7 +32,7 @@ The `Wait for SQL` action scans a database and checks if the
database meets user
|Action name|The name of the workflow action.
|Connection|Identifies the database connection to use.
|Target schema|Name of the table schema to evaluate.
-|Target table name|Name of the table to evaluate.
+|Target table|Name of the table to evaluate.
2+|Success condition
|Success when rows count a|Defines the evaluation method used to compare the
number of rows with the given value. The options are:
@@ -54,3 +54,20 @@ When left unchecked, reaching the maximum timeout limit
causes the workflow acti
|Add rows to result|Includes returned rows to the result set.
|SQL Script|The custom SQL script to use when the `Custom SQL` option is
enabled.
|===
+
+== Result
+
+What this action passes on to the next action. See
xref:workflow/action-results.adoc[Action results] for how results travel
through a workflow.
+
+[options="header", width="90%", cols="1,3"]
+|===
+|Result|Value
+|True|The condition is met before *Maximum timeout*, or the timeout is reached
while *Success on timeout* is checked. The number of errors is 0.
+|False|The timeout is reached while *Success on timeout* is unchecked, the
connection is empty, unknown or can't be opened, *Target table* is empty
(without *Custom SQL*), or *SQL Script* is empty (with *Custom SQL*). The
number of errors is 1.
+|Result files|Passed on unchanged.
+|Result rows|Without *Custom SQL*: passed on unchanged. With *Custom SQL*:
*Clear list of result rows before execution* removes the previous result rows
when the action starts, also when the condition is never met. *Add rows to
result* adds the rows the query returns only when the condition is met.
+|===
+
+NOTE: A query that fails, for example on a table that doesn't exist, counts as
a condition that is not met: the action logs the error and keeps checking until
*Maximum timeout*. With the default *Maximum timeout* of 0, it keeps checking
forever.
+
+NOTE: With *Custom SQL*, the action counts the rows the query returns, not a
value in them: `SELECT count(*) FROM my_table` returns 1 row, also when the
table is empty.
