======================== Important Metalink Notes

====================================

Using Stored Outlines (Doc ID 132547.1)

HOW TO CREATE SQL STORED OUTLINES ON RAC ENVIRONMENT (Doc ID 825997.1)
How to Enable USE_STORED_OUTLINES Permanently (Doc ID 560331.1)
EXAMPLES OF STORED OUTLINES (Doc ID 788406.1)
Note:102311.1 How to Move Stored Outlines for One Application from One Database to
Another

======================== Using Stored Outlines

====================================

Plan Stability
==============

Plan stability forces the optimizer to use the same unvarying execution plan for a
statement.

It is implemented using stored outlines which are stored in the OUTLN schema.

Simplified Procedure for Using Stored Outlines:

o Create stored outlines

o Run application with activated outlines

A stored outline is a representation of the execution plan for a statement.

Outlines can be grouped in to categories.
To use the execution plans of a stored outline, the session (or the instance) must
have the corresponding category activated.

Stored outlines can prevent changes in

o Oracle version
o Optimizer mode
o Statistics
o Data volumes
o Data distribution
o Creation of new indexes

from changing the execution plan of SQL statements.

Stored outlines cannot handle differences in several initialization parameters,

especially some of those ending with _enabled, such as query_rewrite_enabled,
star_transformation_enabled, and optimizer_features_enable.
This means that these parameters must be consistent across execution environments
for stored outlines to function as expected.

Storing Outlines
==================
Stored outlines can be generated for a single atement or at the session or the
instance level

ALTER SESSION set create_stored_outlines = {TRUE|category|FALSE}

ALTER SYSTEM set create_stored_outlines = {TRUE|category|FALSE} [NOOVERRIDE]
CREATE OUTLINE outline [FOR CATEGORY category] ON statement

CREATE_STORED_OUTLINES
======================

By setting this parameter to TRUE or a category name, all subsequent SQL statements
in your session (or the instance) generate stored outlines. If this parameter is
set to an existing category, then new outlines will be added to that category.

If no category name is specified, the stored outlines are added to the DEFAULT
category.

If you do not specify NOOVERRIDE, this system setting takes effect in all sessions.

Setting this parameter to FALSE stops the generation of outlines.

Existing outlines in the category are not updated if these should happen to be
executed again with a different execution plan during the period of storing
outlines in the category.

CREATE OUTLINE
================

This command creates (or replaces) the stored outline for the specified statement
without executing the statement. Note: Outline names must be unique across the
database.

Data Dictionary
=================

Stored outlines are stored as a set of hints necessary to reproduce the execution
plan.

{USER|ALL|DBA}_OUTLINES
{USER|ALL|DBA}_OUTLINE_HINTS

Data dictionary views:

Columns in USER_OUTLINES

NAME Outline name (SYS_OUTLINE_nnn if not specified with CREATE OUTLINE)

CATEGORY Category name (DEFAULT if not specified)
USED USED/UNUSED depending whether the stored outline has ever been used
VERSION Oracle version
SQL_TEXT The statement

Columns in USER_OUTLINE_HINTS

NAME Outline name (SYS_OUTLINE_nnn if not specified with CREATE OUTLINE)

NODE Query or subquery ID to which the hint applies. The top-level query is
labeled 1 subqueries are assigned sequentially numbered labels, starting with 2
STAGE Outline hints can be applied at three different stages during the
compilation process; this column indicates at which stage this hint was applied
JOIN_POS Position of the table in the join order; the value is 0 for all hints
except access method hints, which identify a table to which the hint and the join
position apply
HINT Text of the hint

Hints within Stored Outlines

===============================

Outline hints are not limited to the documented hints

Outline hints cannot be edited

Note that the normal, documented hints will not be able to reproduce all execution
plans.

To illustrate this, consider the following two examples:

1. If the statement is a join, it is necessary to be able to specify the join

order without changing the sequence of tables in the FROM clause; the ORDERED hint
will not suffice in this case as it simply ties the
join order to the sequence of tables in the FROM clause.
2. It is impossible to specify hints into a subquery embedded in a view.

To solve these problems stored outlines not only employ hints not supported as
normal hints (for example, NO_FACT) but they also use information on where in the
statement the hints apply (the NODE column), in what sequence tables
should be joined, and at what stage in the statement compilation the hint should be
applied.

For reasons of complexity it should therefore be obvious that direct editing of the
contents in the underlying table OUTLN.OL$HINTS is not supported nor encouraged.

Stored Outlines Usage

===============================

Stored outlines are used when:

o An outline category is enabled

 alter session set use_stored_outlines = {category|TRUE}
alter system set use_stored_outlines = {category|TRUE} [NOOVERRIDE]

o The executed statement can be found as a direct match of a statement in the

outline category.

When setting use_stored_outlines to TRUE, the category named DEFAULT will be used.

Stored outlines are not used when:

o A hint in the stored outline becomes invalid.

o CURSOR_SHARING = FORCE

CURSOR_SHARING was introduced in Oracle8i Release 2. It internally replaces

literals values in queries with bind variables, thus allowing these statements to
be shared.

CURSOR_SHARING = FORCE disables the use of stored outlines.

Setting CURSOR_SHARING to SIMILAR changes the SQL text in the presence of literals.
Hence, it prevents any outlines generated with literals from being used. Literals
in CREATE [OR REPLACE] OUTLINE... statements are not
replaced by bind variables.

To use stored outlines with CURSOR_SHARING=FORCE or SIMILAR, the outlines must be

generated with CURSOR_SHARING set to FORCE or SIMILAR and with the
CREATE_STORED_OUTLINES parameter.

Stored outlines will not be used if not all hints are valid. This is in contrast to
normal hints where if one hint fails (for example, an index has been removed) the
rest of the hints are still considered.

To test whether a statement did indeed use a stored outline, query the column
OUTLINE_CATEGORY in V$SQL (does not exist in V$SQLAREA); if this column is NULL the
statement did not use a stored outline.

Making Stored Outlines Persistent

===================================

There is no init.ora parameter to enable Stored Outlines Stored Outlines may be

made persistent by the use of a logon or startup trigger An example is given in:

If parameter is set using alter session or by defining in pfile/spfile the

change is not permanent and will no longer be set after database has been
restarted.

A STARTUP trigger needs to be defined in order to make this setting persistent

after restart of database

Solution
Create the following trigger to be run on startup of the database:
create or replace trigger enable_outlines_trig
after startup on database
begin
execute immediate('alter system set use_stored_outlines=true');
end;

Maintaining Stored Outlines

===================================

A Stored Outline can be rebuilt according to present conditions; the statement can
be re-parsed and a new set of outline hints stored.

A plsql package called "OUTLN_PKG" is supplied for maintenance of categories The

package is supplied with the following procedures:

o DROP_UNUSED - Drops all stored outlines that have never been used
(USED column in %_OUTLINES).
o DROP_BY_CAT (category) - Drops all stored outlines within the specified
category.

o UPDATE_BY_CAT (old_category, new_category) - Changes all the outlines in a

category to another category. If an outline is defined for a SQL statement which
already has an outline defined in the new category, this outline will not be moved
from the old category.

Exporting and Importing Outlines

===================================

Export and import of the tables used for stored outlines is supported.

%_OUTLINES is based on OUTLN.OL$

%_OUTLINE_HINTS is based on OUTLN.OL$HINTS

This enables portability of stored outlines between databases.

Exporting With a Condition By using the QUERY parameter of the export utility it is
possible to export a particular outline or category to later import into another
database.

Windows NT example:
exp outln/outln FILE=exportfile TABLES='OL$' 'OL$HINTS'
QUERY=\"WHERE CATEGORY='category'\"

Stored Outlines Example

=======================
The following Oracle 9i example illustrates a situation where a legacy, Rule based,
plan is to be stored with a goal of transferring it to a current release.

Set the OPTIMIZER_MODE to RULE, and enable the creation of stored outlines for your
session.

Suppose a query on the REGISTRATIONS table has the following execution plan:

Execution Plan
----------------------------------------------------
SELECT STATEMENT Optimizer=RULE
SORT (AGGREGATE)
TABLE ACCESS (BY INDEX ROWID) OF 'REGISTRATIONS'
INDEX (RANGE SCAN) OF 'REG_PK' (UNIQUE)

If this plan is stored in a outline called "Outline_Test" then this can be used to
force the desired plan in preference to one the optimizer has chosen.

To choose a different plan, disable the creation of stored outlines, and change the
session environment:

SQL> alter session set optimizer_mode=all_rows;

Running the same SQL statement again probably displays the following execution
plan:

Execution Plan
------------------------------------------
SELECT STATEMENT Optimizer=ALL_ROWS (Cost=43 Card=1 Bytes=11)
SORT (AGGREGATE)
TABLE ACCESS (FULL) OF 'REGISTRATIONS'

Now activate the stored outline category "Outline_Test":

SQL> alter session set use_stored_outlines = Outline_Test;

Run the same SQL statement again:

Execution Plan
----------------------------------------------------------------
SELECT STATEMENT Optimizer=ALL_ROWS (Cost=11779 Card=1 Bytes=11)
SORT (AGGREGATE)
TABLE ACCESS (BY INDEX ROWID) OF 'REGISTRATIONS'
INDEX (RANGE SCAN) OF 'REG_PK' (UNIQUE)

The execution plan from the RBO environment reappears even though the normal
indicators of the CBO (costs in the execution plan) are present.