Comments

You can associate comments with SQL statements and schema objects.

Comments Within SQL Statements

Comments within SQL statements do not affect the statement execution, but they may make your application easier for you to read and maintain. You may want to include a comment in a statement that describes the statement's purpose within your application.

A comment can appear between any keywords, parameters, or punctuation marks in a statement. You can include a comment in a statement using either of these means:

• Begin the comment with a slash and an asterisk (/*). Proceed with the text of the comment. This text can span multiple lines. End the comment with an asterisk and a slash (*/). The opening and terminating characters need not be separated from the text by a space or a line break.

• Begin the comment with -- (two hyphens). Proceed with the text of the comment. This text cannot extend to a new line. End the comment with a line break.

A SQL statement can contain multiple comments of both styles. The text of a comment can contain any printable characters in your database character set.

Note: You cannot use these styles of comments between SQL statements in a SQL script. Use the SQL*Plus REMARK command for this purpose. For information on these statements, see SQL*Plus User's Guide and Reference.

Example

These statements contain many comments:

SELECT ename, sal + NVL(comm, 0), job, loc
/* Select all employees whose compensation is
greater than that of Jones.*/
  FROM emp, dept
       /*The DEPT table is used to get the department name.*/
  WHERE emp.deptno = dept.deptno
    AND sal + NVL(comm,0) >   /* Subquery:       */
   (SELECT sal + NLV(comm,0)
                              /* total compensation is sal + comm */
      FROM emp 
      WHERE ename = 'JONES');

SELECT ename,                    -- select the name
    sal + NVL(comm, 0),          -- total compensation
    job,                         -- job
    loc                          -- and city containing the office
  FROM emp,                      -- of all employees
       dept
  WHERE emp.deptno = dept.deptno
    AND sal + NVL(comm, 0) >     -- whose compensation 
                                 -- is greater than
      (SELECT sal + NVL(comm,0)  -- the compensation
    FROM emp 
    WHERE ename = 'JONES');       -- of Jones.

Comments on Schema Objects

You can associate a comment with a table, view, materialized view, or column using the COMMENT command described in Chapter 7, "SQL Statements". Comments associated with schema objects are stored in the data dictionary.

Hints

You can use comments in a SQL statement to pass instructions, or hints, to the Oracle optimizer. The optimizer uses these hints as suggestions for choosing an execution plan for the statement.

A statement block can have only one comment containing hints, and that comment must follow the SELECT, UPDATE, INSERT, or DELETE keyword. The syntax below shows hints contained in both styles of comments that Oracle supports within a statement block.

{DELETE|INSERT|SELECT|UPDATE} /*+ hint [text] [hint[text]]... */

or

{DELETE|INSERT|SELECT|UPDATE} --+ hint [text] [hint[text]]...

where

DELETE INSERT SELECT UPDATE	is a DELETE, INSERT, SELECT, or UPDATE keyword that begins a statement block. Comments containing hints can appear only after these keywords.
+	is a plus sign that causes Oracle to interpret the comment as a list of hints. The plus sign must follow immediately after the comment delimiter (no space is permitted).
hint	is one of the hints discussed in this section and in Oracle8i Designing and Tuning for Performance. The space between the plus sign and the hint is optional. If the comment contains multiple hints, separate the hints by at least one space.
text	is other commenting text that can be interspersed with the hints.

Table 2-15 lists hint syntax and descriptions.

See Also: Oracle8i Designing and Tuning for Performance and Oracle8i Concepts for more information on hints.

Table 2-15  Hint Syntax and Descriptions

Hint Syntax	Description
Optimization Approaches and Goals
/*+ ALL_ROWS */	Explicitly chooses the cost-based approach to optimize a statement block with a goal of best throughput (that is, minimum total resource consumption).
/*+ CHOOSE */	Causes the optimizer to choose between the rule-based approach and the cost-based approach for a SQL statement based on the presence of statistics for the tables accessed by the statement.
/*+ FIRST_ROWS */	Explicitly chooses the cost-based approach to optimize a statement block with a goal of best response time (minimum resource usage to return first row).
/*+ RULE */	Explicitly chooses rule-based optimization for a statement block.
Access Methods
/*+ AND_EQUAL(table index) */	Explicitly chooses an execution plan that uses an access path that merges the scans on several single-column indexes.
/*+ CLUSTER(table) */	Explicitly chooses a cluster scan to access the specified table.
/*+ FULL(table) */	Explicitly chooses a full table scan for the specified table.
/*+ HASH(table) */	Explicitly chooses a hash scan to access the specified table.
/*+ HASH_AJ(table) */	Transforms a NOT IN subquery into a hash anti-join to access the specified table.
/*+ HASH_SJ(table) */	Transforms a NOT IN subquery into a hash semi-join to access the specified table.
/*+ INDEX(table index) */	Explicitly chooses an index scan for the specified table.
/*+ INDEX_ASC(table index) */	Explicitly chooses an ascending-range index scan for the specified table.
/*+ INDEX_COMBINE(table index) */	If no indexes are given as arguments for the INDEX_COMBINE hint, the optimizer uses whatever Boolean combination of bitmap indexes has the best cost estimate. If particular indexes are given as arguments, the optimizer tries to use some Boolean combination of those particular bitmap indexes.
/*+ INDEX_DESC(table index) */	Explicitly chooses a descending-range index scan for the specified table.
/*+ INDEX_FFS(table index) */	Causes a fast full index scan to be performed rather than a full table scan.
/*+ MERGE_AJ(table) */	Transforms a NOT IN subquery into a merge anti-join to access the specified table.
/*+ MERGE_SJ(table) */	Transforms a correlated EXISTS subquery into a merge semi-join to access the specified table.
/*+ NO_EXPAND */	Prevents the optimizer from considering OR expansion for queries having OR or IN conditions in the WHERE clause.
/*+ NO_INDEX(table index) */	Instructs the optimizer not to consider a scan on the specified index or indexes. If no indexes are specified, the optimizer does not consider a scan on any index defined on the table.
/*+ NOREWRITE */	Disables query rewrite for the query block, overriding a TRUE setting of the QUERY_REWRITE_ENABLED parameter.
/*+ NO_UNNEST */	Prohibits the unnesting of the subquery. The hints HASH_SJ, HASH_AJ, MERGE_SJ, and MERGE_AJ take precedence over this hint.
/*+ ORDERED_PREDICATES */	Forces the optimizer to preserve the order of predicate evaluation (except predicates used in index keys), as specified in the WHERE clause of SELECT statements.
/*+ REWRITE (view [,...]) */	Enforces query rewrite. If you specify a view list and the list contains an eligible materialized view, Oracle will use that view regardless of the cost. No views outside of the list are considered. If you do not specify a view list, Oracle will search for an eligible materialized view and always use it regardless of the cost.
/*+ ROWID(table) */	Explicitly chooses a table scan by rowid for the specified table.
/*+ UNNEST */	Forces the unnesting of the subquery if possible.
/*+ USE_CONCAT */	Forces combined OR conditions in the WHERE clause of a query to be transformed into a compound query using the UNION ALL set operator.
Join Orders
/*+ ORDERED */	Causes Oracle to join tables in the order in which they appear in the FROM clause. This hint overrides the LEADING hint.
/*+ STAR */	Forces the large table to be joined last using a nested-loops join on the index.
Join Operations
/*+ DRIVING_SITE(table) */	Forces query execution to be done at a different site from that selected by Oracle.
/*+ LEADING (table) */	Causes Oracle to use the specified table as the first table in the join order. The ORDERED hint overrides this hint.
/*+ USE_HASH(table) */	Causes Oracle to join each specified table with another row source with a hash join.
/*+ USE_MERGE(table) */	Causes Oracle to join each specified table with another row source with a sort-merge join.
/*+ USE_NL(table) */	Causes Oracle to join each specified table to another row source with a nested-loops join using the specified table as the inner table.
Parallel Execution
Note: Oracle ignores parallel hints on a temporary table. For more information on temporary tables, see "CREATE TABLE" and Oracle8i Concepts.
/*+ APPEND */ /*+ NOAPPEND */	Specifies that data is simply appended (or not) to a table; existing free space is not used. Use these hints only following the INSERT keyword.
/*+ NOPARALLEL(table) */	Disables parallel scanning of a table, even if the table was created with a PARALLEL clause. Restriction: You cannot parallelize a query involving a nested table.
/*+ PARALLEL(table) /*+ PARALLEL(table, integer) */	Lets you specify parallel execution of DML and queries on the table; integer specifies the desired degree of parallelism, which is the number of parallel threads that can be used for the operation. Each parallel thread may use one or two parallel execution servers. If you do not specify integer, Oracle computes a value using the PARALLEL_THREADS_PER_CPU parameter. If no parallel hint is specified, Oracle uses the existing degree of parallelism for the table. DELETE, INSERT, and UPDATE operations are considered for parallelization only if the session is in a PARALLEL DML enabled mode. (Use ALTER SESSION ENABLE PARALLEL DML to enter this mode.)
/*+ PARALLEL_INDEX	Allows you to parallelize fast full index scans for partitioned and nonpartitioned indexes that have the PARALLEL attribute.
/*+ PQ_DISTRIBUTE (table, outer_distribution, inner_distribution) */	Specifies how rows of joined tables should be distributed between producer and consumer query servers. The four possible distribution methods are NONE, HASH, BROADCAST, and PARTITION. However, only a subset of the combinations of outer and inner distributions are valid. For the permitted combinations of distributions for the outer and inner join tables, see Oracle8i Designing and Tuning for Performance.
/*+ NOPARALLEL_INDEX */	Overrides a PARALLEL attribute setting on an index.
Other Hints
/*+ CACHE */	Specifies that the blocks retrieved for the table in the hint are placed at the most recently used end of the LRU list in the buffer cache when a full table scan is performed.
/*+ NOCACHE */	Specifies that the blocks retrieved for this table are placed at the least recently used end of the LRU list in the buffer cache when a full table scan is performed.
/*+ MERGE(table) */	Causes Oracle to evaluate complex views or subqueries before the surrounding query.
/*+ NO_MERGE(table) */	Causes Oracle not to merge mergeable views.
/*+ PUSH_JOIN_PRED(table) */	Causes the optimizer to evaluate, on a cost basis, whether to push individual join predicates into the view.
/*+ NO_PUSH_JOIN_PRED(table) */	Prevents pushing of a join predicate into the view.
/*+ PUSH_SUBQ */	Causes nonmerged subqueries to be evaluated at the earliest possible place in the execution plan.
/*+ STAR_TRANSFORMATION */	Makes the optimizer use the best plan in which the transformation has been used.