13. Using SQL Workbench/J specific annotations in SQL comments
Prev |  | Next

## 13. Using SQL Workbench/J specific annotations in SQL comments

By adding special comments to a SQL (select) statement, you can influence the way the result is displayed in SQL Workbench/J. This comments are called "annotations" and must be included in a comment preceding the statement that is executed. The comment can be a single line or multi-line SQL comment

### 13.1. Naming result tabs

You can change the name of the result tab associated with a statement. To give a result set a name, use the annotation `@WbResult` followed by the name that should appear as the result's name.

The following examples executes two statements. The result for the first will be labelled "List of contacts" and the second will be labelled "List of companies":

    -- @WbResult List of contacts
    SELECT * FROM person;

    /*
     @WbResult List of companies
     this will retrieve all companies from the database
    */
    SELECT * FROM company;

The result name that is used, will be everything after the annotation's keyword until the end of the line.

For the second select (with the multi-line comment), the name of the result tab will be `List of companies`, the comment on the second line will not be considered.

### 13.2. Adding macros to the result's context menu

The annotation `@WbMacro` can be used to add macros to the context menu of the result.

When such a macro is executed, the values of all columns of the currently selected row will be defined as variables that are usable in the macro. The result of the macro will always be appended to the current result regardless of the setting in the macro definition.

Variables which are defined by invocation of a macro from this menu item will not be deleted after the macro has been executed.

This annotation has no effect in console mode.

Assume the following macro with the name `"Person Address"`:

    select *
    from address
    where person_id = $[id];

and the following SQL query:

    -- @WbMacro name="Person Address"
    select id, firstname, lastname
    from person;

The context menu of the result will then contain a new submenu: Macros → Person Address. The variables `$[id]`, `$[firstname]` and `$[lastname]` will contain the values of the currently selected row when the macro is executed.

It is also possible to re-map the column names to different variable names.

    -- @WbMacro name="Person Address" map="id:PersonID"
    select id, firstname, lastname
    from person;

In this case a variable named `PersonID` will be created with the value of the `id` column from the selected row.

The `map` parameter can be repeated several times to re-map multiple columns, e.g. `map=p_id:PersonID map=o_id:OrderID`

It is possible to specify more than one macro for the context menu:

    -- @WbMacro name="Person Address" map="id:PersonID"
    -- @WbMacro name="Customer Orders" map="id:PersonOrderID"
    select id, firstname, lastname
    from person;

A macro can only be executed from the menu when exactly one row is selected in the result.

You can assign a title to the result by using the `@WbResult` annotation based on a variable in the macro:

    -- @WbResult Addresses for $[firstname] $[lastname]
    select *
    from address
    where person_id = $[PersonID];

### 13.3. Re-using an existing named result tab

If the result of a query should be displayed in an existing result tab, the annotation `@WbUseTab` together with a tab name can be used. If this annotation is present and a result tab with that name already exists, the existing result will be replaced with the new result. If no result tab with that name exists, a new tab (with the supplied name) will be created.

Re-using a result tab only works if SQL → Append new results is enabled. You can combine `@WbUseTab` with the `@WbAppendResult` annotation to force re-using an existing result even though the option is turned off.

If the following query is run for the second time, the existing data will be replaced with the newly retrieved data:

    -- @WbUseTab List of contacts
    SELECT * FROM person;

This annotation has no effect in console mode.

### 13.4. Scrolling the result

The annotation `@WbScrollTo` can be used to automatically scroll a result set after it has been retrieved to a specific row number. The row number has to be supplied using a `#` sign:

    -- @WbScrollTo #100
    SELECT *
    FROM person;

In addition to a row number, the special values `end` or `last` (without a `#`) are also recognized. When they are supplied, the result is automatically scrolled to the last row. This is useful when displaying the contents of log tables.

    -- @WbScrollTo end
    SELECT *
    FROM activity_log;

This annotation has no effect in console mode.

### 13.5. Appending a results

The annotation `@WbAppendResult` can be used to always append the result of the associated query regardless of the current setting of SQL → Append new results.

This annotation has no effect in console mode.

### 13.6. Suppressing empty results

To suppress an empty result, the annotation `@WbRemoveEmpty` can be used. If a query returns no rows and contains this annotation, no result tab will be created. No warning or message will be shown if this happens!

This annotation has no effect in console mode.

### 13.7. Automatic refresh of the result

To automatically refresh a result in a defined interval, the `@WbRefresh` annotation can be used. The interval is specified as a parameter to the annotation:

    -- @WbRefresh 15s
    SELECT *
    FROM pg_stat_activity;

The automatic refresh can also be enabled through the context menu of the result tab.

This annotation also works in console mode.

### 13.8. Optimize row height

If the automatic optimization of the row height is disabled, the annotation `@WbOptimizeRowHeight` can be used to optimize the height of the rows for a specific SQL query.

The annotation supports the parameter `lines` that defines the maximum number of lines to display, even if the content was longer.

    -- @WbOptimizeRowHeight lines=10
    select id, json_payload
    from messages
    order by id;

This annotation has no effect in console mode.

### 13.9. Keep result

The annotation `@WbKeepResult` will "lock" a result tab, i.e. the result will never be closed automatically. This can also be enabled through the context menu of a result.

This annotation has no effect in console mode.

### 13.10. Result as text

The annotation `@WbResultAsText` will display the result of the SQL query in text mode in the messages area rather than a scrollable table.

The annotation can be used with or without a parameter. If no parameter is specified, it will turn text mode on for the statement immediately following the annotation.

If the parameter `on` is specified, the text mode will be kept until the script finishes or it's turned off again using `@WbResultAsText off`.

Assuming the following script:

    -- @WbResultAsText
    select * from table_one;

    select * from table_two;

    -- @WbResultAsText on
    select * from table_three;
    select * from table_four;

    -- @WbResultAsText off
    select * from table_five;
    select * from table_six;

The first result ("table_one") will be shown in text mode. The second result ("table_two") will be shown as a table. The results for table_three and table_four will again be shown in text mode and the last two results will be shown as tables again.

This annotation has no effect in console mode.

### 13.11. Create crosstab (pivot) from a result

The annotation `@WbCrossTabl` can automatically transpose rows to columns from a result of a query. This is also known as "crosstab" or "pivot".

Assuming the following statement

    select department_id as dept,
           count(*) as "Employees",
           avg(salary)::int as "Avg. Salary",
           min(salary)::int as "Min. Salary"
    from employees
    where department_id in (10,20,30)
    group by department_id
    order by department_id;

Returns the following result:

    dept | Employees | Avg. Salary | Min. Salary
    -----+-----------+-------------+------------
      10 |         1 |        4400 |        4400
      20 |         2 |        9500 |        6000
      30 |         6 |        4150 |        2500

Then the result can be turned into a crosstab by adding the annotation `@WbCrossTab`. The annotation supports two parameters:

`labelColumn` - to define the column that should be used for the header's label
`addLabel` - an additional text that will be added to the value of the labels

    -- @WbCrossTab labelColumn=dept addLabel="Dept "
    select department_id as dept,
           count(*) as "Employees",
           avg(salary) as "Avg. Salary",
           min(salary) as "Min. Salary"
    from employees
    where department_id in (10,20,30)
    group by department_id
    order by department_id;

Returns the following result:

                | Dept 10 | Dept 20 | Dept 30
    ------------+---------+---------+--------
    Employees   | 1       | 2       | 6
    Avg. Salary | 4400    | 9500    | 4150
    Min. Salary | 4400    | 6000    | 2500

If this is used to export a crosstab using `WbExport`, the data is always read completely into memory in order to be able to generate the crosstab - even if the query would normally be streamed directly to the export file.

Prev |  | Next
12. Using SQL Workbench/J | Home | 14. Using macros and text clips