Application Development

REST-Enabling Oracle Machine Learning Models

Use RESTful services to make your machine learning model available for easier access by developers across a variety of development environments.

By Brendan Tierney

October 24, 2019

One of the biggest challenges of working with machine learning projects is putting the machine learning models into production. Traditionally this has involved changing architectures; porting to other software; and, in some cases, rewriting the models in other languages, such as Java or C. With Oracle Machine Learning, putting the model into production is no longer a challenge. With RESTful services, the in-database machine learning models of Machine Learning can be made available to the developers of production applications. It doesn’t matter what programming language or development tools the app developers are using—they can easily incorporate a REST API in their code.

This article walks you through the steps of REST-enabling a Machine Learning model created with Oracle Autonomous Database.

Let’s Work Through an Example

This article starts with one of the sample Oracle Machine Learning notebooks, “Picking a Good Wine for _$20,” and will REST-enable the machine learning model that that notebook creates. To get started, first load the sample notebook into your Machine Learning notebook and run it. This will execute the notebook code and generate the machine learning model.

Here is the CREATE_MODEL command used in the Machine Learning notebook to create the “Wine” model. This is just a subset of the code from the notebook, and Figure 1 shows more of the Wine model code.

-- Build a Classification Model
DBMS_OUTPUT.PUT_LINE ('Created model: Wine_CLASS_MODEL ');

Creating the machine learning model for Wine predictions

Figure 1: Creating the machine learning model for Wine predictions

Approximately 20 different SQL functions are available to call and interact with in-database machine learning models. Two of the most commonly used functions are PREDICTION and PREDICTION_PROBABILITY. These return the predicted outcome from the model and a probability score, respectively, to indicate how strong a prediction is.

One option for putting the in-database machine learning model into production is to enable the developers to call these PREDICTION and PREDICTION_PROBABILITY SQL functions directly. For instance, the following example uses SQL to call the Wine machine learning model and passes in the values to use to make the prediction.

select prediction(Wine_CLASS_MODEL USING
                'Portugal' as country,
                   'Douro' as province,
                        30 as price,
           'Portuguese Red' as variety) pred_wine,
from dual;

An alternative approach is to use RESTful services, which allows for easier use across a variety of development environments.

Oracle Application Express (Oracle APEX) comes with Oracle Autonomous Data Warehouse and Oracle Autonomous Transaction Processing, and APEX provides access to Oracle REST Data Services, which, in turn, exposes RESTful services to developers. Before you can expose and use the RESTful services, you first need to enable them. To do so in Autonomous Data Warehouse or Autonomous Transaction Processing, log into APEX with the schema you used to create the Machine Learning notebook. You may need to first connect as the APEX admin user and set up your schema to use APEX. After logging into your schema in APEX—in my example, I log in as OML_USER—from the SQL Workshop tab menu, select RESTful Services, as shown in Figure 2.

Accessing RESTful Services in APEX

Figure 2: Accessing RESTful Services in APEX

If RESTful Services has not been set up for your schema, you will be prompted that the schema is not registered with Oracle REST Data Services (sometimes referred to as ORDS). Click Register Schema with ORDS, as shown in Figure 3. In the pop-up window, click Yes for Install Sample Service to install some examples from which you can learn, as shown in Figure 4.

Register schema with Oracle REST Data Services

Figure 3: Register schema with Oracle REST Data Services

Install sample services

Figure 4: Install sample services

With the RESTful sample services installed, you should be able to see the sample REST APIs shown in Figure 5. These examples demonstrate different types of REST APIs with GET and POST functions, returning data in CSV and JSON formats.

Sample REST APIs created in APEX

Figure 5: Sample REST APIs created in APEX

Now let’s create a simple REST API to display the Wine dataset. To do this, first click the Create Template button, halfway down the page on the right side. Enter the name wine in the URI Template field, as shown in Figure 6. The process will automatically generate a URL to point to the REST API and display it in the Full URL field.

Create a simple REST API template

Figure 6: Create a simple REST API template

The next step is to create a handler, which can be GET, POST, or DELETE. The GET method will be used to call the in-database machine learning model. As shown in Figure 7, create the GET method, specifying Query for Source Type and JSON or CSV for Format. In the Source box, enter the following SQL query to retrieve all the records:

select * from winereviews130k

Creating the GET method

Figure 7: Creating the GET method

After saving the method, copy the text in the Full URL field, open a web browser, and paste the URL into the address bar. This will display the list of wines in the table, as shown in Figure 8.

Results from Wine REST API

Figure 8: Results from Wine REST API

Using the SQL query shown earlier (SELECT PREDICTION . . . FROM DUAL) to demonstrate how to call the in-database machine learning algorithm, let’s now create a RESTful API for it. Figure 9 shows the full setup for calling the in-database machine learning model. The first red box highlights the URI Template field, which defines the name of the API and the parameters. The second red box highlights Source Type as Query One Row, because the SQL query will return only one row. Format is set to JSON. The third red box contains the SQL query (Source), which includes the parameters referenced in the URI Template field. The parameters are identified with a colon preceding the parameter name.

REST API for in-database machine learning model

Figure 9: REST API for in-database machine learning model

Copy the REST API, and paste it into the web browser address field. But before running it, change the values for the parameters to the actual values to pass to the REST API. For example:

…/oml_user/wine/wine_pred/Portugal/Douro/Portuguese Red/30

Figure 10 displays the results from calling the REST API with these parameter values.

Running in-database machine learning model with the REST API and a $30 price

Figure 10: Running in-database machine learning model with the REST API and a $30 price

Figure 11 shows that changing one value—the price of the wine—

…/oml_user/wine/wine_pred/Portugal/Douro/Portuguese Red/31

and rerunning the REST API call returns different results.

Rerunning the in-database machine learning model with the REST API and $31 price

Figure 11: Rerunning the in-database machine learning model with the REST API and $31 price

It is easy to see the benefits of using these REST APIs to call machine learning models. An additional benefit is that when a model is updated or modified, developers do not need to modify their applications.

The REST APIs can also be called from other languages, such as Java, C, or Python. The following example uses Python and two libraries to call a REST API. The json library is needed for printing and displaying the JSON object returned by the REST API, and the requests library is needed to make the call out to the REST API. The first call to the REST API calls the machine learning model and makes a prediction based on the country, province, variety, and price of the wine ($30). The second call uses a different value for the price ($31). The output shows the predicted result: Paying $1 more might make getting a better bottle of wine possible.

import json
import requests

rest_api = '<full REST API>'

country = 'Portugal'
province = 'Douro'
variety = 'Portuguese Red'
price = 30

resp = requests.get(rest_api+country+'/'+province+'/'+variety+'/'+str(price))
json_data = resp.json()
print('Predictions for Price = ', price)
print(json.dumps(json_data, indent=2))

#change the price to $31
price = 31

resp = requests.get(rest_api+country+'/'+province+'/'+variety+'/'+str(price))
json_data = resp.json()
print('Predictions for Price = ', price)
print(json.dumps(json_data, indent=2))

Predictions for Price =  30
  "pred_wine": "LT_90_POINTS",
  "prob_wine": 0.6844716987704507

Predictions for Price =  31
  "pred_wine": "GT_90_POINTS",
  "prob_wine": 0.5137163891143298


Using RESTful services is an easy and efficient way to expose in-database machine learning models to a wide variety of development languages and frameworks, which makes it easy for developers to add machine learning to their applications. The in-database machine learning examples shown in this article were built on Oracle Autonomous Database and used the RESTful Services interface of Oracle APEX.

Next Steps

LEARN more about Oracle Machine Learning.

READ more about using Oracle Machine Learning notebooks.

TRY Oracle Cloud Free Tier.

EXPLORE Oracle Machine Learning notebooks on GitHub.

Illustration by Wes Rowell