6
RE Batch API Overview

The OP (Oracle9iAS Personalization) RE Batch API (Recommendation Engine Batch Application Programming Interface) enables an application written in Java to request Oracle9iAS Personalization-style recommendations in bulk mode.

RE Batch API was designed to be extensible, to minimize the number of API functions, to be uniform, and to keep the number of arguments to a minimum.

Chapter 9 contains examples of how to perform common tasks using RE Batch API.

Appendix B contains a complete example of RE Batch API usage.

RE Batch API classes and methods are described in detail in the Javadoc in the OP section of the Oracle9i Application Server Documentation Library

Note: RE Batch API is installed on the system where Oracle9iAS is installed.

RE Batch API Prerequisites

Before you can use RE Batch API methods, OP must be installed and the appropriate tables must be created and populated. Your database tables must be converted to the OP schemas. It is important that the OP MTR is populated with customer profiles. You should also create tables or views containing the customer IDs for which you want recommendations.

If you are using one or more taxonomies, they must be properly specified.

At least one OP package must have been built and deployed. Use the OP administrative interface to do this. For an example of how to create and deploy a package, see Oracle9iAS Personalizaton User's Guide.

RE Batch API Definitions and Concepts

This section describes the collections of methods that make up the RE Batch API and concepts and terms used in the description of the API.

RE Batch API End Users (Customers)

End users (users of a Web site that uses OP for recommendations) are divided into two groups: customers and visitors. A customer is a registered user, who can be identified by a unique customer ID assigned by the Web application. The RE Batch API makes recommendations for customers only.

RE Batch API Recommendations

Recommendations are based on historical data, which is stored in the database and retrieved when the customer profiles are loaded.

Using RE Batch API

Before you execute an RE Batch program, you must

• Set up the OP environment (create an RE, and create and deploy an OP package)

• Create the tables used by the RE Batch methods

Setting Up the RE Batch API Environment

Before you can execute RE Batch API methods, the following must be true:

• Properly formatted customer profile data must be available in the Mining Table Repository (MTR)

• A recommendation engine (RE) farm containing at least one recommendation engine must exist.

• A package must have been successfully built and then deployed in the recommendation engine farm.

The OP administrator's guide and the online help for the OP administrative GUI explain how to perform these steps.

Customer Profile Data

Customer profile data resides in the MTR.

Deploy a Package to an RE

You cannot get recommendations until there is an existing deployed package, which is created using the OP administrative interface. You must build a package before you deploy it. You cannot build a package until there is some data available; data is converted from existing data collected by your Web application and stored in an Oracle database.

When you design an OP application, you must decide if there should be more than one RE and, if there are several REs, how to use them. We recommend that the REs used for bulk recommendations not be used for any other purpose. For a discussion of the design considerations, see "Recommendation Engine Usage" in Chapter 9.

Note: If you try to deploy a package an RE while a batch program is running, the deployment will fail.

Recommendations may want to take income level (salary) into consideration; for example, you may want to recommend items that the user can afford to buy. If the items that are recommended have prices in several currencies (for example, items are sold in Japan and India), see "Handling Multiple Currencies" in Chapter 9.

Sample RE Batch API Usage

OP includes a sample Java program that illustrates the use of many of the RE Batch API methods; the program is in Appendix B. There are also some examples of how to perform typical tasks in Chapter 9.

Creating an REBatchProxy Object

Before you can use any of the RE Batch API methods, you must create at least one REBatchProxy object; see Chapter 9 for details. The object establishes a JDBC connection to a specified database and schema. The connection exists until it is explicitly destroyed.

Creating Instances of RE Batch API Objects

To use the API, you must create instances of the objects used by the API method signatures. Use the RE Batch API supporting classes, described in Chapter 8, to create these instances. It is always necessary, for example to create filtering settings and tuning sessions. For examples, see Chapter 9.

Converting Data for RE Batch API

OP generates recommendations based on data describing past user behavior.

User data stored in an Oracle table must be transformed and stored in the Mining Table Repository (MTR) before it can be used to generate recommendations.

Managing Customer Profiles for RE Batch API

OP stores customer profiles in the Mining Table Repository (MTR). The profiles to be used must be loaded into an RE before any recommendation requests are made. The following methods manage load and unload customer profiles from an RE:

• loadCustomerProfiles()

• purgeCustomerProfiles()

Before you load a set of customer profiles, you must create a table or a view containing a list of the customer IDs that identify the profiles that you wish to load, that is, a list of the customer IDs for which you want a recommendation.

Getting RE API Batch Recommendations

To get a recommendation, the application calls one of the following recommendation methods:

• crossSellForItem()

• rateItem()

• recommendTopItems()

These methods are used for getting recommendations for customers (registered users).

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.

Creating Recommendations

OP uses rule tables stored in the RE to calculate the recommendations requested by the methods listed above. The specific rule table used depends upon the RE Batch API method used. In general, the antecedents of the rules are matched against the historical data and the probabilities of the various consequents are computed. These items are then ordered by probability, and numberOfItems (an API argument) items are returned. The recommendations are written to a database table.

If there is enough memory in the RE database, the RE caches all rules associated with a particular package deployed from the MTR to the RE, not just the most recent rules.

Scoring:

For scoring, all available historical data is used.

The OP Mining Table Repository (MTR) contains historical rating, transactional data, and navigational data stored in both detailed and aggregated formats. The MTR also contains demographic data. When scoring for customers, the RE retrieves the demographic data and the aggregated version of the other data source types.

Making RE Batch Recommendations

RE Batch API methods that make recommendations write the recommendations to a database table. The schema used for the output depends on the method used. You can extract the recommendations in many ways, for example, with an appropriate SQL query, and then decide which recommendations to pass to the user.

Removing the REBatchProxy Object

Before you exit the application, you should destroy any proxy objects that you no longer need.