3
Using the Recommendation Engine Batch Proxy

This chapter consists of an overview of the class and methods that are used to manage the recommendation engine proxy, to collect data, and to obtain recommendations, followed by the individual methods listed in alphabetical order. The supporting classes for these methods are described in Chapter 2.

All methods described in this chapter are public.

Overview

The recommendation proxy (REBatchProxy) methods can be divided according to function, as follows:

• Proxy creation and management, including customer profile management (load and purge customer profiles)

• Recommendation methods (obtain recommendations)

For examples of how to use these classes and methods, see Appendix A.

Location of Classes

To use the REProxyBATCH (and its exceptions), you must include the following statements in your Java program:

import oracle.dmt.op.re.reapi.batch.*;
import oracle.dmt.op.re.reexception.*;

These classes are installed on the system where Oracle9iAS is installed.

Proxy Creation and Management

The REProxyBatch.java class establishes the JDBC connection to the RE schema where the methods execute. The connection continues to exist until the connection is explicitly destroyed with the destroy() method. The class also includes customer profile management methods.

Customer Profile Management

You must load customer profiles from the MTR to the RE before you can request recommendations; after you are done, you should purge the loaded profiles from the RE. The methods are

• LoadCustomerProfiles();

• PurgeCustomerProfiles();

Recommendations

The following methods obtain recommendations:

• crossSellForItems

• rateItem

• recommendTopItems

Communicating the returned recommendations to the end user is the responsibility of the application. The recommendations are written to an output table; the schema of the output table depends on the method called. For details, see the description of each method.

Ratings in OP

Ratings in OP are in "ascending order of goodness", that is, the higher the rating, the more the user prefers the item. Low rated items are items that the user does not prefer. OP algorithms use these assumptions, so it is important that ratings are in ascending order of goodness.

Meaning of Returned Value for Recommendations

The meaning of the value returned for recommendation instances where ItemDetailData.attribute is equal to Enum.RecommendationAttribute.PREDICTION depends on the value of interestDimension as follows:

• For InterestDimension.RATING, the expected rating for the item is returned.

• For InterestDimension.PURCHASING or InterestDimension.NAVIGATION, a scaled probability is returned. The most probable item is assigned a value of 1 and other items are assigned values less than 1 that are proportional to how probable the items are compared to the most probable item.

Rules and Recommendations

OP uses rule tables stored in the RE to generate the recommendations requested by the recommendation methods. The rule tables are created when a package is built and stored in the RE when the package is deployed. The specific rule table used depends upon the RE Batch API call made. In general, the antecedents of the rules are matched against the data in cache (historical data only for RE Batch) and the probabilities of the various consequents are computed. These items are then ordered by probability, and numberOfItems (an API argument) items are returned.

Class and Method Details

The rest of this chapter contains detailed descriptions of the methods and classes, which are listed in alphabetical order.

---

crossSellForItems

Returns cross-sell recommendations for list of items in a table. The recommendations are written to a table.

Syntax

crossSellForItems (Location oItemIdsTableLocations,
int iNumberofItems,
TuningSettings oTuningSettings,
FilteringSettings oFilteringSettings,
Location oResultLocation);

Arguments

oItemIdsTable

Type Location, specifies the location of the table containing the list of items for which cross-sell recommendations are required. The table must be created before the method is invoked. The table must have the following schema:

ITEM_ID NUMBER
ITEM_TYPE VARCHAR2(30)

iNumberofItems

Type int, the number of items for which cross-sell recommendations are required.

oTuningSettings

Specifies data to use (purchasing or navigation) and personalization index (low, medium, or high). Interest dimension must be the same as the data source type of the input item

oFilteringSettings

Specifies taxonomyID, category filtering on or off, a category list, category membership (in, exclude leaves, exclude nodes, level, subtree nodes, or subtree leaves) and attribute filtering on or off.

oResultLocation

Type Location, specifies the location of the table containing the recommendations. The output table has the following schema:

SOURCE_ITEM_ID NUMBER
SOURCE_ITEM_TYPE VARCHAR2(30
REC_ITEM_ID NUMBER
REC_ITEM_TYPE VARCHAR2(30)
CONFIDENCE NUMBER

Return Value

None.

Usage Notes

Interest dimension must be the same as that of the data source type of the input item.

Data source type must be either navigational or purchasing. No other types are supported.

---

rateItem

Returns the rating, computed along an interest dimension, for an item. The rating could indicate, for example, the likelihood that customer X will buy item Y.

Syntax

rateItem(String sCustomerProfileTableName,
Item oItem,
TuningSettings oTuningSettings,
FilteringSettings oFilteringSettings,
Location oResultLocation);

Arguments

sCustomerProfileTableName

Type String, specifies the name of the customer profiles table that has been previously loaded into the RE via LoadCustomerProfiles().

oItem

Type Item, the item type and item ID of the item to be rated.

oTuningSettings

Specifies settings to be applied when computing a recommendation; for details, see "TuningSettings" in Chapter 2

oFilteringSettings

Specifies taxonomyID, category filtering on or off, a category list, category membership (in, exclude leaves, exclude nodes, level, subtree nodes, or subtree leaves) and attribute filtering on or off.

oResultLocation

Type Location, specifies the location of the table containing the recommendations. The output table has the following schema:

CUSTOMER_ID VARCHAR2(32)
ITEM_ID VARCHAR2(30)
ITEM_TYPE NUMBER
PREDICTION NUMBER

Return Value

None.

Usage Notes

Interest dimension must be that same as that of the data source type.

In the tuning settings, the profile data balance is always historical, regardless of the value specified. only historical data is available for bulk recommendations; there is no session data.

How to interpret the recommendations depends on the value of interest dimension:

• For InterestDimension.RATING, return value is the expected rating

• For any other value of interest dimension, return value is a scaled probability with the most probable item assigned a value of 1.

For more information, see "Meaning of Returned Value for Recommendations" earlier in this chapter.

Exceptions

---

recommendTopItems

Returns the rating and other relevant item information for the numberOfItems items with the highest rating along the specified interest dimension. It answers questions such as: Which are the N items that person X is most likely to buy/like?

Syntax

recommendTopItems(String sCustomerProfileTableName,
int iNumberOfTopItems,
TuningSettings oTuningSettings,
FilteringSettings oFilteringSettings,
Location oResultLocation);

Arguments

sCustomerProfileTableName

Type String, specifies the name of the customer profiles table that has been previously loaded into the RE via LoadCustomerProfiles().

iNumberOfTopItems

Type int, the number of items to be recommended for each customer. This number represents the maximum number of items to be returned; the actual number returned may be less.

oTuningSettings

Specifies data to use (demographic, purchasing, rating, navigation, or all), interest dimension (interest, like, or buy) and personalization index (low, medium, or high)

oFilteringSettings

Specifies taxonomyID, category filtering on or off, a category list, category membership (in, exclude leaves, exclude nodes, level, subtree nodes, or subtree leaves) and attribute filtering on or off.

oResultLocation

Type Location, specifies the location of the table containing the recommendations. The output table has the following schema:

CUSTOMER_ID VARCHAR2(32)
ITEM_ID VARCHAR2(30)
ITEM_TYPE NUMBER
PREDICTION NUMBER

Return Value

None.

Exceptions

SQLException

IOException

CMException

Usage Notes

Interest dimension must be that same as that of the data source type.

Data source type must be either navigational or purchasing. No other types are supported.

In the tuning settings, the profile data balance is always historical, regardless of the value specified. only historical data is available for bulk recommendations; there is no session data.

How to interpret the recommendations depends on the value of interest dimension:

• For InterestDimension.RATING, return value is the expected rating

• For any other value of interest dimension, return value is a scaled probability with the most probable item assigned a value of 1.

For more information, see "Meaning of Returned Value for Recommendations" earlier in this chapter.

---

REProxyBatch.java

This class manages the database connection and customer profiles.

Attribute

String Name

Methods

//Constructor
REProxyBatch (String sProxyName,
String sDbURL,
String sUserName,
String sPassword);

• sProxyName is the name of the object to be returned.

• sDbURL is a URL that points to the database where the RE to be used for recommendations resides.

• sUserName is the username for the RE schema

• sPassword is the password for the RE schema

Returns an REProxyBatch object with a valid JDBC connection to the specified RE engine.

void destroy();

Destroys the connection created with the constructor.

void loadCustomerProfiles(Location oCustomerIdsTable,
String sCustomerProfileTableName);

• oLocation of type Location describes the database location of the customer IDs table.

• sCustomerProfileTableName is a string containing the name of the table to be created in the RE.

Load the MTR profiles into the RE for the customers in the customer IDs table. The schema of the customers ID table is

CUSTOMER_ID VARCHAR2(32)

The customer profile table is created in the RE schema to which REProxyBatch is connected. The format of the customer profiles table is

CUSTOMER_ID VARCHAR2(32)
ITEM_ID NUMBER
ITEM_TYPE VARCHAR2(30)
ATTRIBUTE_ID NUMBER
BIN_VALUE NUMBER
DATA_SOURCE_TYPE NUMBER(3)

void purgeCustomerProfiles(String sCustomerProfileTableName);

• sCustomerProfileTableName is the name of the RE table to be dropped.

Drops the specified table from the RE.