Using the SQL Worksheet

You can use the SQL Worksheet to enter and execute SQL, PL/SQL, and SQL*Plus statements. You can specify any actions that can be processed by the database connection associated with the worksheet, such as creating a table, inserting data, creating and editing a trigger, selecting data from a table, and saving that data to a file.

You can display a SQL Worksheet by right-clicking a connection in the Connections navigator and selecting Open SQL Worksheet, by selecting Tools and then SQL Worksheet, or by clicking the Use SQL Worksheet icon under the menu bar. In the Select Connection dialog box, select the database connection to use for your work with the worksheet. You can also use that dialog box to create and edit database connections. (You can have a SQL Worksheet window open automatically when you open a database connection by enabling the appropriate SQL Developer user preference under Database Connections.)

To create a separate unshared worksheet for a connection, use Ctrl+Shift+N.

The SQL Worksheet has the user interface shown in the following figure:

SQL Worksheet toolbar (under the SQL Worksheet tab): Contains icons for the following operations:

Execute Statement executes the statement at the mouse pointer in the Enter SQL Statement box. The SQL statements can include bind variables and substitution variables of type VARCHAR2 (although in most cases, VARCHAR2 is automatically converted internally to NUMBER if necessary); a pop-up box is displayed for entering variable values.
Run Script executes all statements in the Enter SQL Statement box using the Script Runner. The SQL statements can include substitution variables (but not bind variables) of type VARCHAR2 (although in most cases, VARCHAR2 is automatically converted internally to NUMBER if necessary); a pop-up box is displayed for entering substitution variable values.
Commit writes any changes to the database, and ends the transaction; also clears any output in the Results and Script Output panes.
Rollback discards any changes without writing them to the database, and ends the transaction; also clears any output in the Results and Script Output panes.
Cancel stops the execution of any statements currently being executed.
Monitor SQL Status (Oracle Database Release 11.1 and later only) calls the real-time SQL monitoring feature of Oracle Database, enabling you to monitor the performance of SQL statements while they are executing.
Execute Explain Plan generates the execution plan for the statement (internally executing the EXPLAIN PLAN statement). To see the execution plan, click the Explain tab. For more information, see Execution Plan.
Autotrace generates trace information for the statement. To see the execution plan, click the Autotrace tab. For more information, see Execution Plan.
Clear erases the statement or statements in the Enter SQL Statement box.
To the right of these icons is a drop-down list for changing the database connection to use with the worksheet.

The context menu (right-click, or Shift+F10) includes the preceding SQL Worksheet toolbar operations, plus the following operations:

Print File prints the contents of the Enter SQL Statement box.
Cut, Copy, Paste, and Select All have the same meanings as for normal text editing operations.
Query Builder opens the Query Builder dialog box, where you can create a SELECT statement by dragging and dropping table and view names and by graphically specifying columns and other elements of the query.
Refactoring enables you to do the following on selected text: switch character case (to upper/lower/initcap), extract the sequence of PL/SQL statements to a procedure, or rename the local variable.
Format formats the SQL statement (capitalizing the names of statements, clauses, keywords, and so on).
Popup Describe, if the name of a database object is completely selected, displays a window with tabs and information appropriate for that type of object (see Describe Object Window).
Save Snippet opens the Save Snippet (User-Defined) dialog box with the selected text as the snippet text.

Enter SQL Statement: The statement or statements that you intend to execute. For multiple statements, each non-PL/SQL statement must be terminated with either a semicolon or (on a new line) a slash (/), and each PL/SQL statement must be terminated with a slash (/) on a new line. SQL keywords are automatically highlighted. To format the statement, right-click in the statement area and select Format SQL.

You can drag some kinds of objects from the Connections navigator and drop them into the Enter SQL Statement box:

If you drag and drop a table or view, a SELECT statement is constructed with all columns in the table or view. You can then edit the statement, for example, modifying the column list or adding a WHERE clause.
If you drag and drop a function or procedure, a snippet-like text block is constructed for you to edit when including that object in a statement.

To view details for any object, you can select its name in the Enter SQL Statement box and select Popup Describe from the context menu (or press Shift+F4). For example, if you select a table name and press Shift+F4, information about Columns, Constraints, Grants, and so on is displayed; or if you select a procedure name and press Shift+F4, information about Code, Grants, Dependencies, References, and Details is displayed.

Tabs display panes with the following information:

Results: Displays the results of the most recent Execute Statement operation.
Explain: Displays the output if you clicked the Explain Execution Plan icon (see Execution Plan).
Script Output: Displays the output if you clicked the Run Script icon (see Script Runner).
DBMS Output: Displays the output of DBMS_OUTPUT package statements (see DBMS Output Pane).
OWA Output: Displays Oracle Web Agent (MOD_PLSQL) output (see OWA Output Pane).

To toggle the relative heights of the Enter SQL Statement area and the area for tabs and display panes, press Ctrl+Alt+L. You can also manually adjust the heights.

Gauges: In the SQL Worksheet and User-Defined Reports

Using Snippets to Insert Code Fragments

Using the SQL Worksheet for Queries (tutorial)

SQL Developer Concepts and Usage

SQL*Plus Statements Supported and Not Supported in SQL Worksheet

The SQL Worksheet supports some SQL*Plus statements. SQL*Plus statements must be interpreted by the SQL Worksheet before being passed to the database; any SQL*Plus that are not supported by the SQL Worksheet are ignored and not passed to the database.

The following SQL*Plus statements are supported by the SQL Worksheet:

@
@@
acc[ept]
conn[ect]
cl[ear]
def[ine]
desc[ribe]
doc[ument]
exec[ute]
exit (Stops execution and reinstates the specified connection)
ho[st]
pau[se]
pro[mpt]
quit (Stops execution and reinstates the specified connection)
rem[ark]
set pau[se] {ON | OFF}
sta[rt]
timi[ng]
undef[ine]
whenever
xquery

The following SQL*Plus statements are not supported by the SQL Worksheet:

a[ppend]
archive
attr[ibute]
bre[ak]
bti[tle]
c[hange]
col[ulmn]
comp[ute]
copy
del
disc[onnect]
ed[it]
get
help
i[nput]
l[ist]
newpage
oradebug
passw[ord]
print
r[un]
recover
repf[ooter]
reph[eader]
sav[e]
sho[w]
shu[tdown]
spo[ol]
startup
store
tti[tle]
var[iable]

Related Topics

Using the SQL Worksheet

Script Runner

The script runner emulates a limited set of SQL*Plus features. You can often enter SQL and SQL*Plus statements and execute them by clicking the Run Script icon. The Script Output pane displays the output.

The SQL*Plus features available in the script runner include @, @@, CONNECT, EXIT, QUIT, UNDEFINE, WHENEVER, and substitution variables. For example, to run a script named c:\myscripts\mytest.sql, type @c:\myscripts\mytest in the Enter SQL Statement box, and click the drop-down next to the Execute Statement icon and select Run Script.

The following considerations apply to using the SQL Developer script runner:

You cannot use bind variables. (The Execute SQL Statement feature does let you use bind variables of type VARCHAR2, NUMBER, and DATE.)
For substitution variables, the syntax &&variable assigns a permanent variable value, and the syntax &variable assigns a temporary (not stored) variable value.
For EXIT and QUIT, commit is the default behavior, but you can specify rollback. In either case, the context is reset: for example, WHENEVER command information and substitution variable values are cleared.
DESCRIBE works for most, but not all, object types for which it is supported in SQL*Plus.
For SQL*Plus commands that are not supported, a warning message is displayed.
SQL*Plus comments are ignored.

If you have SQL*Plus available on your system, you may want to use it instead of the script runner.

Related Topics

Using the SQL Worksheet

Execution Plan

The Execute Explain Plan icon generates the execution plan, which you can see by clicking the Explain tab. The execution plan is the sequence of operations that will be performed to execute the statement. An execution plan shows a row source tree with the hierarchy of operations that make up the statement. For each operation, it shows the ordering of the tables referenced by the statement, access method for each table mentioned in the statement, join method for tables affected by join operations in the statement, and data operations such as filter, sort, or aggregation.

In addition to the row source tree, the plan table displays information about optimization (such as the cost and cardinality of each operation), partitioning (such as the set of accessed partitions), and parallel execution (such as the distribution method of join inputs). For more information, see the chapter about using EXPLAIN PLAN in Oracle Database Performance Tuning Guide.

Related Topics

Using the SQL Worksheet

Autotrace Pane

The Autotrace pane displays trace-related information when you execute the SQL statement by clicking the Autotrace icon. Most of the specific information displayed is determined by the SQL Developer Preferences for Database: Autotrace Parameters. If you cancel a long-running statement, partial execution statistics are displayed.

This information can help you to identify SQL statements that will benefit from tuning. For example, you may be able to optimize predicate handling by transitively adding predicates, rewriting predicates using Boolean algebra principles, moving predicates around in the execution plan, and so on. For more information about tracing and autotrace, see the chapter about tuning in SQL*Plus User's Guide and Reference.

To use the autotrace feature, the database user for the connection must have the SELECT_CATALOG_ROLE privilege.

Related Topics

Using the SQL Worksheet

DBMS Output Pane

The PL/SQL DBMS_OUTPUT package enables you to send messages from stored procedures, packages, and triggers. The PUT and PUT_LINE procedures in this package enable you to place information in a buffer that can be read by another trigger, procedure, or package. In a separate PL/SQL procedure or anonymous block, you can display the buffered information by calling the GET_LINE procedure. The DBMS Output pane is used to display the output of that buffer. This pane contains icons and other controls for the following operations:

Enable/Disable DBMS Output: Toggles the SET SERVEROUTPUT setting between ON and OFF. Setting server output ON checks for any output that is placed in the DBMS_OUTPUT buffer, and any output is displayed in the pane.
Clear: Erases the contents of the pane.
Save: Saves the contents of the pane to a file that you specify.
Print: Prints the contents of the pane.
Buffer Size: For databases before Oracle Database 10.2, limits the amount of data that can be stored in the DBMS_OUTPUT buffer. The buffer size can be between 1 and 1000000 (1 million).
Poll: The interval (in seconds) at which SQL Developer checks the DBMS_OUTPUT buffer to see if there is data to print. The poll rate can be between 1 and 15.

Related Topics

Using the SQL Worksheet

OWA Output Pane

OWA (Oracle Web Agent) or MOD_PLSQL is an Apache (Web Server) extension module that enables you to create dynamic Web pages from PL/SQL packages and stored procedures. The OWA Output pane enables you to see the HTML output of MOD_PLSQL actions that have been executed in the SQL Worksheet. This pane contains icons for the following operations:

Enable/Disable OWA Output: Enables and disables the checking of the OWA output buffer and the display of OWA output to the pane.
Clear: Erases the contents of the pane.
Save: Saves the contents of the pane to a file that you specify.
Print: Prints the contents of the pane.

Related Topics

Using the SQL Worksheet

SQL History

You can click View, then SQL History (or press F8) to view a dockable window with SQL statements and scripts that you have executed, and optionally select one or more statements to have them either replace the statements currently on the SQL Worksheet or be added to the statements currently on the SQL Worksheet.

You can click on a column heading to sort the rows by the values in that column.

The SQL history list will not contain any statement that can include a password. Such statements include (but are not necessarily limited to) CONNECT, ALTER USER, and CREATE DATABASE LINK.

Append: Appends the selected statement or statements to any statements currently on the SQL Worksheet. You can also append the selected statement or statements by dragging them from the SQL History window and dropping them at the desired location on the SQL Worksheet.

Replace: Replaces any statements currently on the SQL Worksheet with the selected statement or statements.

Clear: Removes all statements from the SQL history.

Filter: If you type a string in the text box and click Filter, only SQL statements containing that string are displayed.

Related Topics

Using the SQL Worksheet

Gauges: In the SQL Worksheet and User-Defined Reports

You can use graphical gauges to display query results in the SQL Worksheet and in user-defined reports. In both cases, you need to specify the name of the value column for the gauge data, and minimum and maximum values on the gauge, and the values to be shown as low and high on the gauge (usually between the minimum and maximum values). In the SQL Worksheet, the required structure for the value to be selected is:

'SQLDEV:GAUGE:<min>:<max>:<low>:<high>:' || <value-column>

For example, to display the last name and the salary in gauge format, where the gauge shows from 1000 to 30000 with below 10000 as low and above 18000 as high, for employees with ID numbers less than a number to be specified, connect to the supplied HR schema and execute the following query:

SELECT last_name, 'SQLDEV:GAUGE:1000:30000:10000:18000:' || salary 
  FROM employees WHERE employee_id < :employee_id

If you specify 104 as the bind variable value, the output appears as shown in the following figure:

For a user-defined gauge report, the query must specify only the value column, the minimum and maximum values, and the low and high values, and optionally a WHERE clause. The required structure for the query (before any optional WHERE clause) is:

SELECT <value-column>, <min>, <max>, <low>, <high> FROM <table-name>

For example, to create a report of salaries in gauge dial format, with the same values and WHERE clause as in the preceding query, right-click on User Defined Reports in the Reports navigator and select Add Report. In the Add Report dialog box, specify a report name; for Style, select Gauge; and for SQL, enter the following:

SELECT salary, 1000, 30000, 10000, 18000 FROM employees
  WHERE employee_id < :EMPLOYEE_ID;

Click the Chart Details tab near the bottom of the box; for Chart Type, select DIAL; for Query Based, select true; and click Apply.

Use the Reports navigator to view the newly created user-defined report. For Connection, specify one that connects to the HR sample schema. For the bind variable value, specify 104. The report shows four semicircular dials, each with a label containing the salary amount and a "needle" pointing to an appropriate place on the dial.

Related Topics

Using the SQL Worksheet

User Defined reports