CREATE OUTLINE

CREATE OUTLINE

Purpose

Use the CREATE OUTLINE statement to create a stored outline, which is a set of attributes used by the optimizer to generate an execution plan. You can then instruct the optimizer to use a set of outlines to influence the generation of execution plans whenever a particular SQL statement is issued, regardless of changes in factors that can affect optimization. You can also modify an outline so that it takes into account changes in these factors.

Note: The SQL statement issued subsequently must be an exact string match of the statement specified when creating the outline.

See Also:

■Oracle9i Database Performance Tuning Guide and Reference for information on execution plans

■ALTER OUTLINE on page 9-118 for information on modifying an outline

■ALTER SESSION on page 10-2 and ALTER SYSTEM on page 10-20 for information on the USE_STORED_OUTLINES and USE_PRIVATE_OUTLINES parameters

Prerequisites

To create a public or private outline, you must have the CREATE ANY OUTLINE system privilege.

If you are creating a clone outline from a source outline, you must also have the

SELECT_CATALOG_ROLE role.

To create a private outline, you must provide an outline editing table to hold the outline data in your schema by executing the DBMS_OUTLN_EDIT.CREATE_EDIT_ TABLES procedure. You must have the EXECUTE privilege on the DBMS_OUTLN_ EDIT package to execute this procedure.

You enable or disable the use of stored outlines dynamically for an individual session or for the system:

■Enable the USE_STORED_OUTLINES parameter to use public outlines

14-48 Oracle9i SQL Reference

CREATE OUTLINE

■Enable the USE_PRIVATE_OUTLINES parameter to use private stored outlines.

See Also:

■Oracle9i Database Performance Tuning Guide and Reference for information on using outlines for performance tuning

■Oracle9i Supplied PL/SQL Packages and Types Reference for information on the DBMS_OUTLN_EDIT package

Syntax

create_outline::=

Semantics

OR REPLACE

Specify OR REPLACE to replace an existing outline with a new outline of the same name.

PUBLIC | PRIVATE

Specify PUBLIC if you are creating an outline for use by PUBLIC. This is the default.

Specify PRIVATE to create an outline for private use by the current session only. The data of this outline is stored in the current schema.

Note: Before first creating a private outline, you must run the

OUTLN_PKG.CREATE_EDIT_TABLES procedure to create the required outline tables and indexes in your schema.

SQL Statements: CREATE LIBRARY to CREATE SPFILE 14-49

CREATE OUTLINE

outline

Specify the unique name to be assigned to the stored outline. If you do not specify outline, the system generates an outline name.

See Also: "Creating an Outline: Example" on page 14-51

FROM ... source_outline Clause

Use the FROM clause to create a new outline by copying an existing one. By default, Oracle looks for source_category in the public area. If you specify PRIVATE, Oracle will look for the outline in the current schema.

Restriction on Copying an Outline If you specify the FROM clause, you cannot specify the ON clause.

See Also: "Creating a Private Clone Outline: Example" on page 14-51 and "Publicizing a Private Outline to the Public Area: Example" on page 14-51

FOR CATEGORY Clause

Specify an optional name used to group stored outlines. For example, you could specify a category of outlines for end-of-week use and another for end-of-quarter use. If you do not specify category, the outline is stored in the DEFAULT category.

ON Clause

Specify the SQL statement for which Oracle will create an outline when the statement is compiled. This clause is optional only if you are creating a copy of an existing outline using the FROM clause.

You can specify any one of the following statements:

Restrictions on the Outline SQL Statement

■If you specify the ON clause, you cannot specify the FROM clause.

14-50 Oracle9i SQL Reference

CREATE OUTLINE

■You cannot create an outline on a multitable INSERT statement.

Note: You can specify multiple outlines for a single statement, but each outline for the same statement must be in a different category.

Example

Creating an Outline: Example The following statement creates a stored outline by compiling the ON statement. The outline is called salaries and is stored in the category special.

CREATE OUTLINE salaries FOR CATEGORY special

ON SELECT last_name, salary FROM employees;

When this same SELECT statement is subsequently compiled, if the USE_STORED_ OUTLINES parameter is set to special, Oracle generates the same execution plan as was generated when the outline salaries was created.

Creating a Private Clone Outline: Example The following statement creates a stored private outline my_salaries based on the public category salaries created in the preceding example. In order to create a private outline, the user creating the private outline must have the EXECUTE privilege on the DBMS_OUTLN_ EDIT package, and must execute the CREATE_EDIT_TABLES procedure of that package.

EXECUTE DBMS_OUTLN_EDIT.CREATE_EDIT_TABLES;

CREATE OR REPLACE PRIVATE OUTLINE my_salaries

FROM salaries;

Publicizing a Private Outline to the Public Area: Example The following statement copies back (or publicizes) a private outline to the public area after private editing:

CREATE OR REPLACE OUTLINE public_salaries

FROM PRIVATE my_salaries;

SQL Statements: CREATE LIBRARY to CREATE SPFILE 14-51