OPG_APIS.CF

Format

OPG_APIS.CF(
     edge_tab_name   IN      VARCHAR2,
     edge_label      IN      VARCHAR2,
     rating_property IN      VARCHAR2,
     iterations      IN      NUMBER DEFAULT 10,
     min_error       IN      NUMBER DEFAULT 0.001,
     k               IN      NUMBER DEFAULT 5,
     learning_rate   IN      NUMBER DEFAULT 0.0002,
     decrease_rate   IN      NUMBER DEFAULT 0.95,
     regularization  IN      NUMBER DEFAULT 0.02,
     dop             IN      NUMBER DEFAULT 8,
     wt_l            IN/OUT  VARCHAR2, 
     wt_r            IN/OUT  VARCHAR2, 
     wt_l1           IN/OUT  VARCHAR2, 
     wt_r1           IN/OUT  VARCHAR2, 
     wt_i            IN/OUT  VARCHAR2, 
     wt_ld           IN/OUT  VARCHAR2, 
     wt_rd           IN/OUT  VARCHAR2, 
     tablespace      IN      VARCHAR2 DEFAULT NULL,
     options         IN      VARCHAR2 DEFAULT NULL);

Description

Runs collaborative filtering using matrix factorization on the given graph. The resulting factors of the matrix product will be stored on the left and right tables.

Parameters

edge_tab_name

Name of the property graph edge table (GE$).

edge_label

Label of the edges that hold the rating property.

rating_property

(Reserved for future use: Name of the rating property.)

iterations

Maximum number of iterations that should be performed. Default = 10.

min_error

Minimal error to reach. If at some iteration the error value is lower than this value, the procedure finishes.. Default = 0.001.

k

Number of features for the left and right side products. Default = 5.

learning_rate

Learning rate for the gradient descent. Default = 0.0002.

decrease_rate

(Reserved for future use: Decrease rate if the learning rate is too large for an effective gradient descent. Default = 0.95.)

regularization

An additional parameter to avoid overfitting. Default = 0.02

dop

Degree of parallelism. Default = 8.

wt_l

Name of the working table that holds the left side of the matrix factorization.

wt_r

Name of the working table that holds the right side of the matrix factorization.

wt_l1

Name of the working table that holds the left side intermediate step in the gradient descent.

wt_r1

Name of the working table that holds the right side intermediate step in the gradient descent.

wt_I

Name of the working table that holds intermediate matrix product.

wt_ld

Name of the working table that holds intermediate left side delta in gradient descent.

wt_rd

Name of the working table that holds intermediate right side delta in gradient descent.

tablespace

Name of the tablespace to use for storing intermediate data.

options

Additional settings for operation. An optional string with one or more (comma-separated) of the following values:

'INMEMORY=T' is an option for creating the schema tables with an 'inmemory' clause.
'IMC_MC_B=T' creates the schema tables with an INMEMORY MEMCOMPRESS BASIC clause.

Usage Notes

For information about collaborative filtering with RDF data, see SQL-Based Property Graph Analytics, especially Collaborative Filtering Overview and Examples.

If the working tables already exist, you can specify their names for the working table-related parameters. In this case, the algorithm can continue the progress of the previous iterations without recreating the tables.

If the working tables do not exist, or if you do not want to use existing working tables, you must first call the OPG_APIS.CF_PREP procedure, which creates the necessary working tables.

The final result of the collaborative filtering algorithm are the working tables wt_l and wt_r, which are the two factors of a matrix product. These matrix factors should be used when making predictions for collaborative filtering.

If (and only if) you have no interest in keeping the output matrix factors and the current progress of the algorithm for future use, you can call the OPG_APIS.CF_CLEANUP procedure to drop all the working tables that hold intermediate tables and the output matrix factors.

Examples

The following example calls the OPG_APIS.CF_PREP procedure to create the working tables, and then the OPG_APIS.CF procedures to run collaborative filtering on the phones graph using the edges with the rating label.

DECLARE
  wt_l varchar2(32);
  wt_r varchar2(32);
  wt_l1 varchar2(32);
  wt_r1 varchar2(32);
  wt_i varchar2(32);
  wt_ld varchar2(32);
  wt_rd varchar2(32);
  edge_tab_name    varchar2(32) := 'phonesge$';
  edge_label       varchar2(32) := 'rating';
  rating_property  varchar2(32) := '';
  iterations       integer      := 100;
  min_error        number       := 0.001;
  k                integer      := 5;
  learning_rate    number       := 0.001;
  decrease_rate    number       := 0.95;
  regularization   number       := 0.02;
  dop              number       := 2;
  tablespace       varchar2(32) := null;
  options          varchar2(32) := null; 
BEGIN
 opg_apis.cf_prep(edge_tab_name,wt_l,wt_r,wt_l1,wt_r1,wt_i,wt_ld,wt_rd);
 opg_apis.cf(edge_tab_name,edge_label,rating_property,iterations,min_error,k,
             learning_rate,decrease_rate,regularization,dop,
             wt_l,wt_r,wt_l1,wt_r1,wt_i,wt_ld,wt_rd,tablespace,options);
END;
/

The following example assumes that OPG_APIS.CF_PREP had been run previously, and it specifies the various working tables that were created during that run. In this case, the preceding example automatically assigned suffixes like '$$CFL57' to the names of the working tables. (The output names can be printed when they are generated or be user-defined in the call to OPG_APIS.CF_PREP.) Thus, the following example can run more iterations of the algorithm using OPG_APIS.CF without needing to call OPG_APIS.CF_PREP first, thereby continuing the progress of the previous run.

DECLARE
  wt_l varchar2(32)  = 'phonesge$$CFL57';
  wt_r varchar2(32)  = 'phonesge$$CFR57';
  wt_l1 varchar2(32) = 'phonesge$$CFL157';
  wt_r1 varchar2(32) = 'phonesge$$CFR157';
  wt_i varchar2(32)  = 'phonesge$$CFI57';
  wt_ld varchar2(32) = 'phonesge$$CFLD57';
  wt_rd varchar2(32) = 'phonesge$$CFRD57';
  edge_tab_name    varchar2(32) := 'phonesge$';
  edge_label       varchar2(32) := 'rating';
  rating_property  varchar2(32) := '';
  iterations       integer      := 100;
  min_error        number       := 0.001;
  k                integer      := 5;
  learning_rate    number       := 0.001;
  decrease_rate    number       := 0.95;
  regularization   number       := 0.02;
  dop              number       := 2;
  tablespace       varchar2(32) := null;
  options          varchar2(32) := null; 
BEGIN
 opg_apis.cf(edge_tab_name,edge_label,rating_property,iterations,min_error,k,
             learning_rate,decrease_rate,regularization,dop,
             wt_l,wt_r,wt_l1,wt_r1,wt_i,wt_ld,wt_rd,tablespace,options);
END;
/