Skip Headers
Oracle® Data Mining Application Developer's Guide
11g Release 1 (11.1)

Part Number B28131-01
Go to Documentation Home
Go to Book List
Book List
Go to Table of Contents
Go to Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Go to next page
View PDF

2 A Tour of the Data Mining APIs

This chapter provides an overview of the PL/SQL, SQL, and Java interfaces to Oracle Data Mining.

This chapter contains the following sections:

Data Mining PL/SQL Packages

The PL/SQL interface to Oracle Data Mining is implemented in three packages:


The DBMS_DATA_MINING package includes procedures for:

  • Creating, dropping, and renaming mining models

  • Applying a model to new data

  • Describing the model details

  • Computing test metrics for a classification model

  • Exporting and importing models

Build Results

The CREATE_MODEL procedure creates a mining model. The attributes, transformations, rules, and other information internal to the model are returned by GET_MODEL_DETAILS functions. You can also obtain information about mining models by querying data dictionary views, as described in "Data Mining Data Dictionary Views".

Apply Results

The APPLY procedure creates a table with specific columns and populates the columns with mining results. The columns of this table vary based on the particular mining function and algorithm.


For real-time scoring, use the data mining SQL functions described Chapter 4.


This package includes routines for transforming the data to make it suitable for mining. Since Oracle Data Mining supports Automatic Data Transformation (ADP), you will not need to use this package unless you want to implement specialized transformations

You can supplement the ADP-generated transformations with additional transformations that you specify yourself. Alternatively, you can elect to transform the data yourself instead of using the automatic transformation feature.

The routines in DBMS_DATA_MINING_TRANSFORM are convenience routines to assist you in creating your own transformations. If these routines do not entirely suit your needs, you can write SQL to modify their output, or you can write your own routines.

To specify transformations for a model, pass a transformation list to the DBMS_DATA_MINING.CREATE_MODEL procedure. You can use the STACK procedures in DBMS_DATA_MINING_TRANSFORM to build the transformation list.

Oracle Data Mining embeds automatic transformations and transformations you pass to CREATE_MODEL in the model. The embedded transformations are automatically applied to the data when the model is applied. You do not need to separately transform the test or scoring data.

See Also:


This package includes routines for predictive analytics, an automated form of data mining. With predictive analytics, the user does not need to be aware of model building or scoring. All mining activities are handled internally by the predictive analytics procedure.

Predictive analytics routines prepare the data, build a model, score the model, and return the results of model scoring. Before exiting, they delete the model and supporting objects.

Oracle predictive analytics support these routines:

  • EXPLAIN ranks attributes in order of influence in explaining a target column.

  • PREDICT predicts the value of a target column based on values in the input data.

  • PROFILE generates rules that describe the cases from the input data.

    See Also:

    DBMS_PREDICTIVE_ANALYTICS in Oracle Database PL/SQL Packages and Types Reference

Data Mining Data Dictionary Views

You can obtain information about mining models from the data dictionary. The data dictionary views for Oracle Data Mining are available for ALL_, USER_, and DBA_ access.

The Data Mining data dictionary views are summarized as follows:

Data Mining SQL Functions

The built-in SQL functions for Data Mining implement scoring operations for models that have already been created in the database. They provide the following benefits:


SQL functions are built into Oracle Database and are available for use within SQL statements. SQL functions should not be confused with functions defined in PL/SQL packages.

When applied to a given row of scoring data, classification and regression models provide the best predicted value for the target and the associated probability of that value occurring. The SQL functions for prediction are described in Table 2-1.

Table 2-1 SQL Functions for Prediction

Function Description


Returns the best prediction for the target


Applies to generalized linear models

Returns the upper and lower bounds of the interval wherein the values (linear regression) or probabilities (logistic regression) will lie


Returns a measure of the cost of incorrect predictions


Returns the rules of a Decision Tree model


Returns the probability of a given prediction


Returns the results of a classification model, including the prediction and associated probability for each case

Applying a cluster model to a given row of scoring data returns the cluster ID and the probability of that row's membership in the cluster. The SQL functions for clustering are described in Table 2-2.

Table 2-2 SQL Functions for Clustering

Function Description


Returns the ID of the predicted cluster


Returns the probability of a case belonging to a given cluster


Returns a list of all possible clusters to which a given case belongs along with the associated probability of inclusion

Applying a feature extraction model involves the mapping of features (sets of attributes) to columns in the scoring data set. The SQL functions for feature extraction are described in Table 2-3.

Table 2-3 SQL Functions for Feature Extraction

Function Description


Returns the ID of the feature with the highest coefficient value


Returns a list of objects containing all possible features along with the associated coefficients


Returns the value of a given feature

Data Mining Java API

The Oracle Data Mining Java API is an Oracle implementation of the JDM standard (JSR-73) Java API. It is a thin API developed using the rich in-database functionality of Oracle Data Mining.

The Oracle Data Mining Java API implements Oracle specific extensions to provide all the data mining features available in the database. All extensions are designed to be compliant with the JDM standards extension framework. All the mining functions and algorithms available in the database are exposed through the Oracle Data Mining Java API.

Oracle Database introduced the JDM 1.0 standard compliant API that replaced the old Oracle proprietary Java API in the previous releases. Database patch-set release extended the JDM standards support by implementing Oracle Data Mining Java API compatible with JDM 1.1.

In this release, the Oracle Data Mining Java API continues to be compatible with the JDM 1.1 and provides new data mining functionality in the database server as Oracle extensions. In this release new Oracle features include auto and embedded data preparations, generalized linear models, transformation sequencing and task dependency specifications.

See Also:

"What's New in Oracle Data Mining" in Oracle Data Mining Concepts for a summary of the new features in the Oracle Data Mining Java API.

The JDM Standard

JDM is an industry standard Java API for data mining, it is developed under the Java Community Process (JCP). It defines Java interfaces that any vendor could implement for their Data Mining Engine. It includes interfaces supporting mining functions such as classification, regression, clustering, attribute importance and association; along with specific mining algorithms such as naïve bayes, support vector machines, decision tree, feed forward neural networks, and k-means.

An overview of the Java packages defined by the standards is listed in Table 2-4. For more details, refer to the Java documentation published with the standard at In the Go to JSR box, type in 73.

Table 2-4 JDM Standard Java Packages

Package Description


Defines objects supporting all JDM subpackages.


Defines objects supporting many top-level mining objects. Introduced to avoid cyclic package dependencies.


Defines objects that support connecting to the Data Mining ENgine and executing tasks.

Defines objects supporting logical and physical data, model signature, taxonomy, category set and the generic super class category matrix.


Defines objects supporting attribute statistics.


Defines objects supporting rules and their predicate components.


Defines objects supporting tasks for build, compute statistics, import, and export. Task has an optional subpackage for apply since apply is used mainly for supervised and clustering functions.


Defines objects supporting the build settings and model for association.


Defines objects supporting the build settings and model for clustering.


Defines objects supporting the build settings and model for attribute importance.


Defines objects supporting the build settings and models for supervised learning functions, specifically classification and regression, with corresponding optional packages. It also includes a common test task for the classification and regression functions.


Defines objects supporting the settings that are specific to algorithms. The algorithm package has optional sub packages for different algorithms.


Defines objects supporting details of various model representation. Model Details has optional sub packages for different model details.

Oracle Extensions to JDM

Oracle extensions are defined to support the functionality that is not part of the JDM standards. This section gives an overview of these extensions.

Oracle extensions have the following major additional features:

  • Feature Extraction function with Non-negative Matrix Factorization (NMF) algorithm

  • Generalized linear models algorithm for regression and classification functions

  • Oracle proprietary algorithm called Orthogonal Clustering for clustering function

  • Adaptive Bayes Network (ABN) algorithm for classification function

  • Automated and embedded transformations

  • Predictive analytics tasks

An overview of the Oracle extensions higher-level Java packages is provided in Table 2-5.

Table 2-5 Oracle Extensions Higher-Level Packages

Package Description


Defines the objects related to the feature extraction function. Feature extraction supports the scoring operation.


Defines the objects related to the Non-negative Matrix Factorization (NMF) algorithm.



Defines the objects related to the Generalized Linear Model (GLM) algorithm.


Defines the objects related to the Orthogonal Clustering (O-Cluster) algorithm.


Defines the objects related to the Adaptive Bayes Network (ABN) algorithm.


Defines the objects related to the transformations.

Principal Objects in the Oracle Data Mining Java API

In JDM, named objects are objects that can be saved using the save method in the Connection. All the named objects are inherited from the javax.datamining.MiningObject interface. A vendor can choose to persist the named objects either permanently (persistent objects) or only for the lifetime of the connection object (transient objects).

Table 2-6 lists the JDM named objects supported by Oracle.

Table 2-6 JDM Named Objects Supported by Oracle

Persistent Objects Transient Objects Unsupported Objects


Apply Settings

Logical Data

Build Settings

Physical Dataset



Cost Matrix

Test Metrics

Transformation sequence

Physical Data Set

Physical data sets refer to the data to be used as input to data mining operations. Physical data set objects reference specific data via a URI, e.g., specifying a table or file. Oracle supports a table or view in the same database as a valid physical dataset URI. Syntax of the oracle physical dataset URI is as follows:

Data URI Syntax:

[schemaName.] tableName/viewName

The physical data set object can support multiple data representations. Oracle Data Mining supports two types of data representation, i.e., single-record case and wide data. Refer to data mining concepts guide for more details. The Oracle implementation requires users to specify the case-id column in the physical dataset.

A physical data set object is a transient object in the Oracle Data Mining Java API. It is stored in the Connection object as an in-memory object.

Build Settings

A build settings object captures the high-level specification input for building a model. The API specifies mining functions: classification, regression, attribute importance, association, clustering, and feature extraction.

Build settings allows a user to specify the type of result desired without having to specify a particular algorithm. Although a build settings object allows for the specification of an algorithm and its settings, if the algorithm settings are omitted, the DME selects an algorithm based on the build settings and possibly characteristics of the data.

Build settings may also be validated for correct parameters using the verify method.

Build settings is a persistent object in the API, it is stored as a table with the user specified name in the user schema. This settings table is interoperable with the PL/SQL API. It is recommended not to modify the build settings table manually in the schema.


The execute method in the Connection object is used to start an execution of a mining task. Typically, mining operations are done using tables with millions of records, so the execution of operations like building a model can take more time. JDM supports asynchronous execution of mining tasks using DBMS_SCHEDULER in the database. Each mining task is stored as a DBMS_SCHEDULER Job object in the user schema. When the user saves the task object, it creates a Job object and sets the object to be in the DISABLED state. When the user executes a task, it enables the job to start execution.

Applications that would like to use the DBMS_SCHEDULER functionality like scheduling mining tasks could use DBMS_SCHEDULER PL/SQL package provided in the database.

To monitor tasks that are executed asynchronously, the execute method returns a javax.datamining.ExecutionHandle object. It provides all the necessary features like waitForCompletion, getStatus methods to retrieve the status details of the task.


A model object is the result of applying an algorithm to data as specified in a build settings object.

Models can be used in several operations. They can be:

  • Inspected, for example to examine the rules produced from a decision tree or association

  • Tested for accuracy

  • Applied to data for scoring

  • Exported to an external representation such as native format or PMML

  • Imported for use in the DMS

When a model is applied to data, it is submitted to the DMS for interpretation. A Model references its BuildSettings object as well as the Task that created it. as.

Test Metrics

A Test Metrics object is the result of testing a supervised model with test data. Based on the type of mining function, different test metrics are computed. For classification models, accuracy, confusion-matrix, lift, and receiver-operating characteristic can be computed to access the model. Similarly for regression models, R-squared and RMS errors can be computed.

Apply Settings

An apply settings object allows users to tailor the results of an apply task. It contains a set of ordered items. Output can consist of:

  • Data to be passed through to the output from the input dataset, e.g., key attributes

  • Values computed from the apply itself, e.g., score, probability and in the case of decision trees, rule identifiers

  • Multi-class categories for its associated probabilities, e.g., in a classification model with target favoriteColor, users could select the specific colors to receive the probability that a given color is favorite.

Each mining function class defines a method to construct a default apply settings object. This simplifies the programmer's effort if only standard output is desired. For example, typical output for classifications apply would include the top prediction and its probability.

Transformation Sequence

A transformation sequence object represents the sequence of transformations that are to be performed as part of a mining operation. For example, a Support Vector Machine model build involves outlier handling and normalization transformations. In addition to this, there can be new derived attribute creation and business transformations, and so on. Typicaly these transformations are resused for other model builds and hence applications can save the transformation sequence as a named object in the API.

Transformation sequence can be used either to perform transformations as a separate task or embed them to the modeling process by specifying it as one of the input objects for model building.